HR_Proposal_Tools

General-purpose tools for proposals of exoplanet observations with high-resolution spectrographs. This toolkit leverages ANTARESS (a high-resolution spectroscopy simulator) to in part, predict RV precision and Rossiter-McLaughlin signature detectability achievable for given targets, observing configurations, and instruments.

Overview

These tools facilitate the creation and analysis of exoplanet observation proposals by:

1. Gathering target and stellar parameters from astronomical databases
2. Computing stellar properties (limb-darkening coefficients)
3. Running ANTARESS simulations to estimate RV measurement precision and Rossiter-McLaughlin signature detectability.
4. Processing and organizing results for proposal documentation

File Reference

Target & Parameter Management

targets.py — Target parameter loader

• Imports exoplanet and stellar parameters from a CSV file (targets_input_2.csv)
• Provides TARGETS — a list of dicts, each containing:
  • Star data: name, vsini (rotation), limb-darkening coefficients (ld_u1, ld_u2)
  • Planet data: period, transit time (T0), eccentricity, orbital inclination, planet-to-star radius ratio (RpRs), etc.
  • Observation parameters: instrument name, visit label, exposure count and duration, observing window
  • CCF profile: contrast (0–1), FWHM (km/s), noise flag
• Required CSV columns (see docstring for full reference):
  • star_name, planet_name, target_rv_err (desired RV precision in m/s)
  • vsini, ld_u1, ld_u2, period, T0, aRs, RpRs, Incl, texp, etc.
• Usage:

  import targets
  print(targets.TARGETS[0])   # first target dict
  print(len(targets.TARGETS)) # total number of targets

• Environment variable TARGETS_CSV can override the default CSV path

NEA_parser.py — NASA Exoplanet Archive data retriever

• Queries the NASA Exoplanet Archive TAP service to fetch exoplanet orbital and stellar parameters
• Downloads stellar properties (Teff, log g, [Fe/H]) and planet orbital elements
• Outputs a CSV suitable for downstream processing
• Usage: Edit the targets list at the top, then run: python NEA_parser.py
• Handles target name matching and coordinate queries

Exposure time calculation (MAROON-X specific)

ETC_parser.py — Exposure Time Calculator and spectral type utilities

• Provides spectral type–to–effective temperature mappings (Pecaut & Mamajek 2013)
• Implements spectral type snapping: maps arbitrary spectral types to the nearest MAROON-X ETC grid point while preserving luminosity class
• Contains full MAROON-X ETC spectral type catalog and Teff table
• Usage: Edit the planets, mag, and spectral_type list at the top, then run: python ETC_parser.py

Stellar Property Computations

LD_calculator.py — Limb-darkening coefficient computer

• Computes quadratic limb-darkening coefficients (u₁, u₂) using exotic_ld library
• Integrates stellar model atmosphere grids (default: MPS1 model) across the MAROON-X spectral range (4900–9200 Å)
• Reads stellar parameters (Teff, log g, [Fe/H]) from an input CSV
• Outputs limb-darkening coefficients and uncertainties to a CSV
• Requirements: Fetches and caches stellar model data locally (configurable via LD_DATA_PATH)
• Usage: Fill in input CSV path and output location, then run: python LD_calculator.py

Core Execution

run_parallel.py — Main entry point for batch processing

• Runs the ANTARESS RMR-estimate (Rossiter–McLaughlin RV) pipeline across multiple targets in parallel
• Usage:

  python run_parallel.py                  # run all targets with default settings
  python run_parallel.py --workers 4      # use 4 parallel workers
  python run_parallel.py --targets 0 1 2  # run only targets at indices 0, 1, 2
  python run_parallel.py --csv results.csv # custom output CSV path
  python run_parallel.py --dry-run        # preview targets without executing

• Creates per-target log files (<star_name>.log) with timestamps and error tracebacks
• Appends results atomically to a shared output CSV via process locking
• Worker count advice: Set to the number of physical cores to dedicate; default is os.cpu_count() // 2

run_one_target.py — Single-target pipeline orchestrator

• Encapsulates the full 17-step ANTARESS notebook pipeline for one target
• Implements two-pass flux calibration logic:
  • Pass 1 (diagnostic): Runs steps 1–16 with a fixed flux=1000, then monitors ANTARESS output to extract the RV error
  • Pass 2 (final): Runs the full pipeline with flux adjusted as flux_pass2 = 1000 * (rv_err_pass1 / target_rv_err)², using true stellar parameters
• Fast rotator handling (vsini > 3 km/s): Pass 1 uses a substitute vsini=2 km/s to isolate flux calibration without rotational broadening contamination
• Called by run_parallel.py; can be run directly for debugging individual targets

Utilities & Data Processing

Directory_saver.py — ANTARESS output organizer

• Collects per-target ANTARESS simulation outputs and organizes them into a structured directory tree
• Copies selected subdirectories and files from raw ANTARESS results into a proposal-ready folder structure
• Populates RMR-estimate Jupyter notebooks with target-specific parameters (read from input and results CSVs)
• Generates one output directory per star/planet system
• Requires:
  • Source ANTARESS results directory
  • Input targets CSV and results CSV from run_parallel.py
  • Notebook template
• Configuration: Edit SOURCE_ROOT, DEST_ROOT, NOTEBOOK_TEMPLATE, and CSV paths in the script header
• Usage: python Directory_saver.py

ANTARESS_nbook_bground.py — Core setup and save utilities

• Provides initialization and configuration functions for the ANTARESS notebook pipeline
• save_system() — Saves processed ANTARESS results and collects RV error statistics
• show_inst() — Lists available ANTARESS instruments
• Called internally by the pipeline; not intended for direct user execution

ANTARESS_nbook_RMR-estimate.ipynb — Interactive analysis notebook

• Jupyter notebook template for individual target analysis and RV precision estimation
• Populated automatically by Directory_saver.py with target-specific parameters and results
• Provides interactive visualization and diagnostic plots
• Regenerated per target/system from this template

---

Workflow: From Targets to Proposals

Step 1: Gather & Prepare Target Data

1. Use NEA_parser.py to query the NASA Exoplanet Archive for planetary and stellar parameters
2. Use ETC_parser.py to iterate over the MAROON-X Exposure Time Calculator and find the optimal exposure time for each planet
3. Run LD_calculator.py to compute limb-darkening coefficients
4. Create or update targets_input_2.csv with all required columns (see targets.py docstring)

Step 2: Run ANTARESS Predictions

python run_parallel.py --workers 8 --csv results.csv

• Processes all targets through the two-pass ANTARESS pipeline
• Each target's RV measurement precision and Rossiter-McLaughlin signature detectability is estimated for the specified observing configuration
• Results are appended to results.csv with per-target metadata

Step 3: Organize & Document Results

python Directory_saver.py

• Collects ANTARESS output files and organizes them into a proposal-ready structure
• Generates indexed Jupyter notebooks per target for interactive exploration
• Populates parameter summaries and performance metrics

---

Proposal Usage

These tools directly support instrument proposal writing by:

1. Quantifying Trade-offs

   • Estimate how exposure time, stellar rotation, and instrument configuration affect measurement uncertainty and RM detectability
   • Predict precision for specific star–planet–instrument combinations
   • Assess feasibility of proposed science cases

2. Validating Observing Strategies

   • Compare multiple spectral orders, exposure times, and observing windows
   • Identify optimal configurations for marginal targets
   • Justify resource allocation in proposals

3. Generating Proposal Figures & Tables

   • Automated results CSVs provide publication-ready precision estimates
   • ANTARESS output includes diagnostic plots (CCF profiles, order-by-order performance, noise budgets)
   • Organized directory structure facilitates proposal document assembly

4. Supporting Feasibility Studies

   • Run quick parameter sweeps to explore performance across stellar types or orbital geometries
   • Batch process large target lists to prioritize science cases
   • Generate supporting evidence for proposal justification

---

Requirements

• Python 3.7+
• ANTARESS simulator (separate installation; this toolkit is a wrapper)
• Dependencies: pandas, numpy, astropy, exotic_ld, playwright (for ETC parsing)
• Environment: Adjust working paths in script headers for your system

Configuration Notes

Before first run:

1. Edit WORKING_PATH, CSV_PATH, and other paths in run_one_target.py to match your system
2. Prepare a targets_input_2.csv file with required columns (template: targets.py)
3. Configure Directory_saver.py input/output paths
4. Ensure ANTARESS is installed and accessible

License & Attribution

These tools are designed to work with the ANTARESS high-resolution spectrograph simulator. Cite ANTARESS publications when using this toolkit in scientific work.