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

Capability	Status	External inputs
Registries, line data, correction grids, and core validation	Tested	None
Solar O I 777 nm 3D-NLTE correction smoke example	Tested	None; grid is vendored
Solar/Procyon normalization and abundance workflows	Research workflow	Approved spectra and full iSpec input bundle
Multi-arm solar/Procyon work	Mixed active/experimental	Per-arm holdings, loaders, and conditioning
55 Cancri full pipeline	Incomplete	Normalization route remains unimplemented
M-dwarf abundance reproduction	Experimental/planned	MARCS.GES, molecular assets, approved spectrum

“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.

Instrument / atlas	Facility · archive	Coverage (nm)	R	Bands	Science role	Key caveats	Codex status
HST/STIS	STScI · MAST	114–1027	500–114000	FUV/NUV/VIS	Resolved FUV/NUV abundance diagnostics	Grating-specific coverage; scattered-light/chromospheric masks; convert vacuum to air only above 200nm	active
HST/COS	STScI · MAST	90–320	1500–24000	FUV/NUV	FUV/NUV coverage and cross-checks	Grating/segment-specific conditioning and chromospheric masks	experimental
HARPS	ESO · ESO Science Archive	378–691	115000	VIS/red_optical	Primary optical abundance backbone	Use reduced merged products; verify BERV and SPECSYS; shared telluric framework routes clean visible lines by line selection and sends affected red-edge windows through molecfit/GDAS	active
ESPRESSO	ESO · ESO Science Archive	378–788	70000–140000	VIS/red_optical	High-stability optical cross-arm reference	Prefer WAVE_AIR where supplied; reject velocity-smeared stack products	active
UVES	ESO · ESO Science Archive	300–1100	40000–110000	FUV_edge/NUV/VIS/red_optical	UV-to-red high-resolution diagnostics	Mode/dichroic specific coverage; apply BERV only when product frame requires it	active
FEROS	ESO · ESO Science Archive

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.

Stage	Current role/status
pipeline/spectra_normalize.py	Real FITS/co-add/normalization paths for supported targets
pipeline/lines_fit.py	Real line-profile/EW path where wired
pipeline/abundances_derive.py	LTE/NLTE abundance and synthesis engines
pipeline/params_stellar.py	Spectroscopic solve path; incomplete for some targets
pipeline/uncertainty_stack.py	Partial/stub
pipeline/ratios_interpret.py	Partial/stub

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.