The Exoplanet Codex science pipeline

The Exoplanet Codex science pipeline

Open-science software, scientific registries, and curated inputs for deriving stellar elemental abundances from high-resolution spectra across the UV, visible, near-infrared, and infrared. This is the science repository, not the separately deployed Exoplanet Codex website.

The project is active research software. Solar and Procyon benchmark paths are the most developed; Alpha Centauri A/B and 55 Cancri A are current science targets. Read the reproduction status before interpreting any output.

Canonical scientific registries

New here, human or agent? Read LEDGERS.md first. It is the canonical read-set index: the five ledgers that hold the project's current state, what each is source-of-truth for, and its update trigger.

These machine-readable artifacts are the discovery layer for agents, collaborators, reviewers, and downstream publication systems:

• System Register — target identity, role, run order, lifecycle, and website key.
• Instrument and Data-Source Register — archive, wavelength capability, resolution, preprocessing, support state, and provenance.
• Element Status Register — the current canonical element/status artifact while a normalized data/catalog/elements.csv remains unratified.
• Stellar parameters — fundamental parameters and pin/solve policy for runnable stars.
• Method policy — per-star/species EW-versus-synthesis selection.

The current target inventory is always the System Register; the README does not maintain a second star list. Instrument capability likewise does not prove that a system has data. Verified per-system holdings belong in manifests that join system_catalog.star_params_key to instrument_catalog.instrument_id. Schemas and join rules are documented in data/catalog/README.md.

What is reproducible today

“Tested” does not make a correction-grid smoke result a publishable stellar abundance. Full products require the stated spectra, model assets, line data, corrections, diagnostics, and provenance.

Tested quick start

The exact lock below was tested on macOS 15 arm64 with CPython 3.9.6. Python 3.10/3.11 users should resolve requirements.txt and record pip freeze.

git clone https://github.com/damienabraxas/exoplanetcodex.git
cd exoplanetcodex

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-lock-py39.txt

python scripts/validate_installation.py
python -m data.catalog.instruments
python scripts/quickstart_example.py
cat results/tables/quickstart_oi777.json
python -m pytest -q

The example reads canonical solar parameters and the vendored Amarsi et al. (2019) C/O grid, evaluates the O I 777.194 nm correction, and writes a manifest. Expected: delta≈-0.169 dex, corrected A(O)≈8.521. It is an offline correction-grid smoke test, not spectral synthesis.

For full iSpec/Turbospectrum work:

export ISPEC_DIR=/absolute/path/to/ispec
python scripts/validate_installation.py --full \
  --json results/tables/install-validation.json

The smallest real-spectrum benchmark uses one approved solar or Procyon HARPS product plus its manifest. A full multi-wavelength reproduction adds only the arms required for the science question and independently validates each one.

Multi-wavelength data strategy

HARPS is the optical backbone, not the whole program. HST/STIS and COS provide FUV/NUV access; UVES and ESPRESSO extend optical/red diagnostics; NIRPS and SPIRou cover YJH/K; CRIRES+ reaches CO/OH and isotope-sensitive K-band regions; Kitt Peak, CALSPEC, ACE, and NSO products anchor solar/reference work.

The table below is validated byte-for-byte against selected rows of the canonical instrument CSV. The full register also records HARPS-N, HIRES, NIRSPEC, KPF, ESPaDOnS, NARVAL, Phoenix, CHIRON, iSHELL, MIKE, APOGEE, and explicit candidate/rejected decisions.

See instrument strategy and preprocessing for archive coverage, air/vacuum handling, tellurics, iodine rejection, product formats, and minimal versus full reproduction.

Pipeline

flowchart LR
  A[Archive or reference source] --> B[Manifest, identity, checksum]
  B --> C[Instrument-aware conditioning]
  C --> D[Line selection and profile fitting]
  D --> E[Equivalent widths]
  D --> F[Flux synthesis]
  G[System + element + instrument registries] --> C
  H[stars.yaml + method policy] --> E
  H --> F
  I[Atomic/molecular data + atmosphere] --> E
  I --> F
  E --> J[1D-LTE abundance]
  F --> J
  K[NLTE/3D correction grids] --> L[Corrected abundance]
  J --> L
  L --> M[Diagnostics, uncertainty, manifest]
  M --> N[Reviewed publication product]

run_pipeline.py is a thin driver over real stage run() functions. It does not generate synthetic replacement data or own stellar parameters. Current stages stop loudly when a target/path is unsupported.

Do not use python run_pipeline.py --star 55cancri as a quick start; its normalization route is not implemented.

Public release roadmap

Release progress is generated from the canonical 27-product element registry and the current publishable channel in the abundance-product store:

python3 scripts/generate_release_roadmap.py \
  --site-root /path/to/exoplanetcodex-site

Archive, quarantine, gap, missing, and superseded records never advance release progress. The generated site artifact is assets/data/release-roadmap.v1.json.

Documentation

• Environment and prerequisites
• Atmospheres, radiative transfer, NLTE, and 3D assets
• Instrument and archive strategy
• Spectral/atomic data and directory layout
• Solar, Procyon, host-star, and M-dwarf workflows
• Reproducibility and provenance
• Categorized scientific references
• Troubleshooting

License and citation

Code is MIT licensed; data/model assets retain upstream terms. Cite the code commit, spectrum archive and instrument paper, atmosphere/radiative-transfer software, atomic/molecular datasets, solar reference, and every correction grid actually used. Start with the citation guide and categorized bibliography.