Reference data¶

This page documents the reference datasets that PROTEUS uses at runtime: where they come from, what they contain, and how they are identified in config files. For instructions on switching between spectrum sources, see Switch and choose a stellar spectrum.

Automatic data download¶

PROTEUS downloads reference data from Zenodo on first run, through fwl-io; the stellar evolution tracks come through MORS, which uses fwl-io as well.

fwl-io. fwl-io pins a dataset to a Zenodo version DOI declared in a manifest, verifies every file against a checksum registry committed beside that manifest, and places the files in a version directory named for the record, so a re-pinned deposit lands beside its predecessor rather than overwriting it. Every request carries a connect and read timeout, and a transient failure is retried with backoff. For every dataset except the PHOENIX spectra, which have no mirror yet, a file that Zenodo does not serve is fetched from the DataverseNL mirror the manifest pins beside the record, and checked against the same registry. Data several models read (spectral files, stellar spectra, equations of state, melting curves, lookup tables, mass-radius curves) is declared in the shared manifest that fwl-io ships; data only PROTEUS reads is declared in src/proteus/data/proteus_manifest.toml. A data folder in the older layout is brought into this one as described in Upgrading an older data folder.

The scattering tables in the version directory below $FWL_DATA/atmos_clim/scattering/socrates_aerosols decide which .mon aerosol species PROTEUS offers to AGNI; AGNI reads the tables themselves from its own res/scattering folder. Fetch them with proteus get scattering before a run with --offline and aerosols enabled: without them that run only warns and offers no .mon aerosol species.

With aerosols enabled, PROTEUS also fetches the aerosol refractive indices (proteus get refractive) and points AGNI at their version directory below $FWL_DATA/atmos_clim/refractive/agni_aerosols through AGNI_DIR_refractive once every file of the dataset is present, from which AGNI computes Mie optical properties; an incomplete fetch is a warning and leaves the variable unset. A value of AGNI_DIR_refractive or AGNI_DIR_res set before the run is kept, with a warning when the folder AGNI then reads holds no refractive index file. Fetch them before a run with --offline: without them, and without the copy AGNI's get_data.sh places in its res/refractive, AGNI lists no Mie aerosol species.

Upgrading an older data folder¶

A $FWL_DATA folder written by an older PROTEUS keeps its files at paths that are no longer read. Three steps bring it into the current layout:

1. Run fwl-io relocate. It moves every dataset whose files all match their pinned checksums into its version directory. fwl-io relocate --dry-run lists what would move, what is incomplete and what does not match, without moving anything.
2. Run proteus start --config <config.toml> once without --offline, which downloads the data that configuration needs, or proteus get interiordata --config-path <config.toml> for the interior tables alone. This downloads what the first step left: incomplete and mismatched datasets, and those it cannot move (the Chabrier archive, the surface albedos, the Seager tables, the Spada tracks and the scattering tables).
3. Delete $FWL_DATA/scattering, which PROTEUS does not read; proteus get scattering fetches the tables into their version directory. The zenodo_download.log and zenodo_validate.log files in $FWL_DATA and the *.zenodo files beside downloaded files are no longer written or read and can be deleted too.

A run with --offline stops when an interior EOS table, a melting curve, a P-S lookup table, a spectral file, a stellar spectrum or a surface albedo file is missing. The error names its download command and ends with: "Data kept in the older FWL_DATA layout can be moved into place with fwl-io relocate." Two stops have no download command. A spectral file of a group and band count that no manifest declares is not downloaded, so its error says to place the file at the path it names. PALEOS-API tables are built at start from the paleos package, so their error names that package.

The stop writes a status code as follows:

Stellar spectra¶

The spectrum source is set via star.mors.spectrum_source and star.mors.star_name (or star.mors.star_path for a custom file). See Switch and choose a stellar spectrum for full usage instructions.

Solar spectra¶

Observed solar spectra are stored under $FWL_DATA/star/spectra/solar/r<record>/, where <record> is the Zenodo record that the manifest pins. The modern spectrum is from Gueymard (2003) via NREL. Historical and future spectra are from Claire et al. (2012).

star_name matching is case-insensitive.

MUSCLES / Mega-MUSCLES spectra¶

Observed UV-optical-IR spectra from the MUSCLES and Mega-MUSCLES surveys, stored under $FWL_DATA/star/spectra/muscles/r<record>/ as <star_name>.txt. star_name matching is case-insensitive.

PHOENIX synthetic spectra¶

Med-resolution synthetic spectra from the PHOENIX library, stored under $FWL_DATA/star/spectra/phoenix/r17674612/FeH<FeH>_alpha<alpha>/. Each subdirectory corresponds to one metallicity-alpha combination (e.g. FeH-0.5_alpha+0.0/). The Zenodo record holds one zip archive per combination. PROTEUS fetches only the archive that a run needs, checks it against the committed checksum, and unpacks it next to the archive.

Parameters defining the PHOENIX grid:

Any parameter set to "none" in the config is derived from the MORS stellar evolution tracks using star.mass. Grid inputs are automatically rounded to the nearest available grid point.

Custom stellar spectrum¶

A user-supplied spectrum is loaded when star.mors.star_path is set. It overrides spectrum_source, star_name, and all phoenix_* parameters. Environment variables (e.g. $FWL_DATA, $HOME) in the path are expanded at load time.

Required file format:

The spectrum must be scaled to a distance of 1 AU. Comment lines begin with #.

Spectral files¶

Correlated-k opacity tables used by the atmosphere climate modules (AGNI, JANUS). Selected via atmos_clim.spectral_group and atmos_clim.spectral_bands in the config. Stored under $FWL_DATA/atmos_clim/spectral_files/<group>/<bands>/r<record-id>/, with the group name in lower case. For a full description of each group's spectral coverage and gas species, see docs/assets/spectral_files.pdf in the PROTEUS repository.

The default configuration uses Honeyside / 48. Higher band counts increase spectral resolution and runtime cost.

Surfaces¶

Surface reflectance spectra from Hammond et al. (2024): Zenodo record 15880455. proteus get surfaces downloads them into the versioned dataset directory $FWL_DATA/atmos_clim/surface_albedos/hammond_2024/r15880455.

Set atmos_clim.agni.surf_material to the file name of a spectrum, for example "lunarmarebasalt.dat". The path form "surface_albedos/Hammond24/lunarmarebasalt.dat" is also accepted and selects the same file.

Available surface types can be listed with:

proteus get surfaces
ls $FWL_DATA/atmos_clim/surface_albedos/hammond_2024/r15880455

Exoplanet population data¶

Obtained from the DACE PlanetS database (Parc et al., 2024).

Fetched through fwl-io into $FWL_DATA/observe/exoplanet_reference/r<record-id>/, where <record-id> is the Zenodo record the manifest pins. The population diagram resolves this directory from the pin, so the version segment never has to be typed by hand. The catalogue is decorative for a simulation: when it is absent or cannot be downloaded, the population diagram is skipped with a warning rather than failing the run.

A copy under $FWL_DATA/planet_reference/Exoplanets is not read and can be deleted.

Mass-radius relations¶

Theoretical mass-radius curves for a range of interior and atmospheric structures, from Zeng et al. (2019), taken from the author's planet model tables.

Declared in the fwl-io shared manifest and fetched into $FWL_DATA/interior/mass_radius/zeng_2019/r<record-id>/, on the same terms as the exoplanet catalogue above. Copies under $FWL_DATA/mass_radius/Zeng2019 and $FWL_DATA/observe/mass_radius/zeng_2019 are not read and can be deleted; the curves (57 files, 20 kB) are fetched again. On a machine that runs with --offline, such as a cluster node, run proteus get reference once before the first offline run.

Equations of state¶

The interior structure solver of PROTEUS, Zalmoxis, uses equation-of-state tables by Seager et al. (2007), and from PALEOS by Attia et al. (2026). An overview of equation of state tables can be found here.

All equation-of-state tables are fetched through fwl-io into $FWL_DATA/<dataset directory>/r<record-id>/, on the same terms as the datasets above. Only the files that the selected equations of state read are fetched.

Tables under $FWL_DATA/zalmoxis_eos, $FWL_DATA/EOS_material_properties and $FWL_DATA/interior_struct/eos/seager_2007 are not read where they are; the Seager tables (0.2 MB) are fetched again into interior/eos/seager_2007; before an --offline run, fetch them once with proteus get interiordata --config-path <config.toml>. fwl-io relocate moves a zalmoxis_eos folder that holds every file of its dataset; the rest can be deleted once the run has fetched them.

Melting curves and P-S lookup tables¶

The Monteux+600, Monteux-600 and Wolf_Bower+2018 solidus/liquidus curves used by interior_struct.melting_dir and by Zalmoxis are fetched through fwl-io into $FWL_DATA/interior/melting_curves/<dataset>/r<record-id>/ (datasets monteux_plus_600, monteux_minus_600 and wolf_bower_2018). For these three names the checksum-verified fetched copy is read; a local directory $FWL_DATA/interior_lookup_tables/Melting_curves/<melting_dir>/ of the same name is read only while the fetched copy is not on disk. Any other name is read from that local directory, which holds solidus_P-T.dat and liquidus_P-T.dat (as written by tools/solidus_func.py) or solidus.dat and liquidus.dat; see Melting curves for the full list of parametrizations and how to generate them. When SPIDER or Aragog read melting_dir, a configured curve whose files are missing stops the run with an error naming the missing files instead of switching to other curves. With interior_struct.module = "zalmoxis" and a PALEOS mantle equation of state (for a mixture: a PALEOS MgSiO\(_3\) component, or no MgSiO\(_3\) component and a PALEOS one), the curves are derived from the PALEOS liquidus and melting_dir is not read; a configured melting_dir then gives a warning when the configuration is loaded. Without a PALEOS table set, melting_dir must be set, rather than use whichever curves are on disk: an Aragog configuration without it is rejected when it is loaded, and a SPIDER run stops with an error when it starts. A SPIDER run with const_properties = true reads no melting curves and is exempt.

The Wolf and Bower (2018) pressure-entropy lookup table that SPIDER and Aragog read for eos_dir = "WolfBower2018_MgSiO3" is fetched the same way, into $FWL_DATA/interior/eos/dk09_1tpa_elec_free/mgsio3_wolf_bower_2018_1tpa/r<record-id>/ when SPIDER or Aragog run without a generated PALEOS table set: with the dummy or SPIDER structure, or with Zalmoxis and a non-PALEOS or mixed mantle EOS. It is also fetched whenever interior_struct.eos_dir is set and SPIDER or Aragog run. proteus get interiordata --config-path <config> fetches it for such a config before an offline run. A local table takes precedence: SPIDER reads $FWL_DATA/interior_lookup_tables/EOS/dynamic/<eos_dir>/P-S/ and Aragog reads $FWL_DATA/interior_lookup_tables/EOS/dynamic/<eos_dir>/P-T/. SPIDER uses the table bundled with it (lookup_data/1TPa-dK09-elec-free/) when neither the local nor a complete fetched table is available.