Skip to content

Planet and volatiles

The [planet] section defines the bulk planet properties, initial temperature profile, and volatile inventory. These parameters set the initial conditions for the coupled evolution.

Parameters [planet]

Parameter Type Default Description
mass_tot float 1.0 Total planet mass (interior + atmosphere) in Earth masses [M_earth]. Must be > 0.
temperature_mode str "liquidus_super" How to set the initial mantle thermal state. 'isothermal': T = tsurf_init everywhere. 'linear': T from tsurf_init (surface) to tcenter_init (center). 'adiabatic': integrate dT/dP|_S downward from tsurf_init. 'adiabatic_from_cmb': anchor the adiabat at the core-mantle boundary (T = tcmb_init at P_cmb) and integrate upward to the surface. Use this when the surface-anchored adiabat under the current EOS would put the mantle into the mushy zone at IC and you want to force a fully molten initial state by pinning the CMB temperature instead. PROTEUS converts the (P_cmb, tcmb_init) anchor into a target entropy via PALEOS-2phase lookup, then hands that S to the interior solver as if it were the isentropic IC. 'accretion': White & Li (2025) parameterization. 'isentropic': set the initial specific entropy directly via ini_entropy + ini_dsdr (bypasses PALEOS lookup; matches the CHILI intercomparison protocol). The interior solver maps the entropy IC to T(P) via its own EOS table. 'liquidus_super' (default): start the mantle on the coolest single adiabat that is fully molten everywhere, with at least delta_T_super Kelvin of superheat above the configured liquidus. The surface temperature (hence the uniform initial entropy) is solved so the minimum superheat over the whole mantle equals delta_T_super, evaluated against the solidus/liquidus actually in use. This guarantees a fully molten initial state with a controlled margin for any planet mass and any melting-curve parameterisation, without the user having to pick a surface temperature or entropy. The solve raises if the requested superheat cannot be reached before the deep adiabat exhausts the EOS table. Choices: "isothermal", "linear", "adiabatic", "adiabatic_from_cmb", "accretion", "isentropic", "liquidus_super".
tsurf_init float 4000.0 Initial magma surface temperature [K] (isothermal, linear, adiabatic). Ignored when temperature_mode = 'isentropic', 'adiabatic_from_cmb', or 'liquidus_super'. Must be > 0.
tcmb_init float 6000.0 Initial core-mantle boundary temperature [K] (adiabatic_from_cmb only). The mantle adiabat is anchored at this temperature at P = P_cmb and integrated outward to the surface. Must be > 0.
tcenter_init float 6000.0 Center temperature [K] (linear only). Must be > 0.
f_accretion float 0.04 Accretion heat retention [0-1] (accretion mode, White & Li 2025). Must be >= 0.
f_differentiation float 0.5 Differentiation heat retention [0-1] (accretion mode). Must be >= 0.
ini_entropy float 3900.0 Initial specific entropy at the surface [J/kg/K] (isentropic mode). CHILI Earth-SPIDER reference: 3900.0. Must be > 0.
ini_dsdr float -4.698e-06 Initial entropy gradient with radius [J/kg/K/m] (isentropic mode). CHILI Earth-SPIDER reference: -4.698e-6 (small numerical perturbation needed for SPIDER's BDF stability on a uniform IC).
delta_T_super float 500.0 Minimum superheat [K] above the liquidus for the liquidus_super initial condition (liquidus_super mode only). The initial adiabat is solved so that, at its most-constraining depth, the temperature is at least delta_T_super above the configured liquidus; this fixes the whole isentropic profile and guarantees a fully molten mantle with that margin, for any planet mass and any melting curve. The default 500 K gives a comfortably molten start across the Earth-mass to ten-Earth-mass range. delta_T_super = 0 makes the mantle marginally molten (just touching the liquidus at the binding depth). If the requested superheat cannot be reached within the EOS table, the solve raises and reports the largest achievable value. Must be >= 0.
volatile_mode str "elements" How to set the initial volatile inventory: 'elements' or 'gas_prs'. Choices: "elements", "gas_prs".
volatile_reservoir str "mantle" Interior mass reference for ppmw calculations. 'mantle': M_mantle = M_int - M_core (default). 'mantle+core': M_int = M_mantle + M_core (total dry interior). Choices: "mantle", "mantle+core".
fO2_source str "user_constant" How the chemistry solver treats atmospheric fO2. 'user_constant' (default): fO2 is buffered to the iron-wustite offset set by outgas.fO2_shift_IW; atmospheric and dissolved O are derived from the equilibrium chemistry at that fO2. 'from_O_budget': the user O budget (from planet.elements.O_mode/O_budget) is authoritative; fO2 is derived by the chemistry solver as the IW-buffer offset that produces the supplied O inventory. Use this when you want whole-planet O accounting to drive the redox state instead of buffering to a fixed dIW. Requires O_mode != 'ic_chemistry' (the chemistry needs an O target to invert against). 'from_mantle_redox' (reserved): fO2 is derived from a tracked Fe3+/Fe2+ ratio in the silicate melt (Schaefer et al. 2024 / issue #653). NOT YET IMPLEMENTED; the config-level validator rejects this value until the radial fO2 framework lands. Choices: "user_constant", "from_O_budget", "from_mantle_redox".
R_int_override float or none none Bypass the radius root finder and force a fixed interior radius [m]; 'none' (default) uses the root finder. Used for SPIDER/Aragog parity runs where the two energetics modules have different Adams-Williamson density implementations. Must be > 0.
prevent_warming bool false When True, require the planet to monotonically cool over time. Enforced in all atmosphere modules and termination checks.

Initial temperature profile

The temperature_mode parameter selects how the initial temperature distribution is constructed. Different modes anchor the profile at different reference points.

Mode Key parameter(s) Description
isothermal tsurf_init Uniform temperature throughout mantle
linear tsurf_init, tcenter_init Linear gradient from center to surface
adiabatic tsurf_init Adiabat anchored at the surface, integrated downward
adiabatic_from_cmb tcmb_init Adiabat anchored at the CMB at a fixed temperature, integrated upward
liquidus_super delta_T_super Solves for the coolest fully molten adiabat with at least \(\Delta T_\mathrm{super}\) of superheat above the configured liquidus (default: Fei et al. 20211 MgSiO\(_3\)) at its most-constraining depth. Mass-robust and independent of the liquidus parameterisation; raises if the superheat cannot be reached within the EOS table. \(\Delta T_\mathrm{super} = 0\) makes the mantle marginally molten.
accretion f_accretion, f_differentiation Temperature from gravitational accretion and core-mantle differentiation energy retention (White and Li, 2025)
isentropic ini_entropy, ini_dsdr Entropy-based IC; the interior solver maps \(S \to T(P)\) via its EOS table

Redox state

When fO2_source = "user_constant", the atmospheric fO\(_2\) is buffered at the iron-wustite offset set by outgas.fO2_shift_IW. When fO2_source = "from_O_budget", the O budget from planet.elements.O_mode/O_budget is authoritative and the chemistry solver derives the fO\(_2\) that produces the supplied O inventory. A third value, from_mantle_redox, is reserved for a future release and is rejected at config-load until that work lands.

Element abundances [planet.elements]

Used when volatile_mode = "elements". Each element has a mode (defining the unit) and a budget (the value in that unit).

Parameter Type Default Description
H_mode str "oceans" How H_budget is interpreted: 'oceans', 'ppmw', 'kg'. Choices: "oceans", "ppmw", "kg".
H_budget float 0.0 Hydrogen inventory value (units depend on H_mode). Must be >= 0.
C_mode str "C/H" How C_budget is interpreted: 'C/H', 'ppmw', 'kg'. Choices: "C/H", "ppmw", "kg".
C_budget float 0.0 Carbon inventory value (units depend on C_mode). Must be >= 0.
N_mode str "N/H" How N_budget is interpreted: 'N/H', 'ppmw', 'kg'. Choices: "N/H", "ppmw", "kg".
N_budget float 0.0 Nitrogen inventory value (units depend on N_mode). Must be >= 0.
S_mode str "S/H" How S_budget is interpreted: 'S/H', 'ppmw', 'kg'. Choices: "S/H", "ppmw", "kg".
S_budget float 0.0 Sulfur inventory value (units depend on S_mode). Must be >= 0.
O_mode str "ic_chemistry" How O_budget is interpreted: 'ppmw', 'kg', 'FeO_mantle_wt_pct', 'ic_chemistry'. Choices: "ppmw", "kg", "FeO_mantle_wt_pct", "ic_chemistry".
O_budget float 0.0 Oxygen inventory value (units depend on O_mode). Ignored when O_mode = 'ic_chemistry'. Must be >= 0.
use_metallicity bool false Scale C/N/S from solar metallicity (overrides C/N/S mode+budget).
metallicity float 1000.0 Metallicity relative to solar, by mass (only if use_metallicity=True). Must be >= 0.
He_mode str "kg" How He_budget is interpreted: 'kg', 'ppmw' (relative to the volatile reservoir), or 'solar' (multiple of the protosolar He/H mass ratio). Choices: "kg", "ppmw", "solar".
He_budget float 0.0 Helium inventory value (units depend on He_mode). Must be >= 0.
Ne_mode str "kg" As He_mode, for neon. Choices: "kg", "ppmw", "solar".
Ne_budget float 0.0 Neon inventory value (units depend on Ne_mode). Must be >= 0.
Ar_mode str "kg" As He_mode, for argon. Choices: "kg", "ppmw", "solar".
Ar_budget float 0.0 Argon inventory value (units depend on Ar_mode). Must be >= 0.
Kr_mode str "kg" As He_mode, for krypton. Choices: "kg", "ppmw", "solar".
Kr_budget float 0.0 Krypton inventory value (units depend on Kr_mode). Must be >= 0.
Xe_mode str "kg" As He_mode, for xenon. Choices: "kg", "ppmw", "solar".
Xe_budget float 0.0 Xenon inventory value (units depend on Xe_mode). Must be >= 0.

Note

The Python defaults for volatile budgets are zero. The values in all_options.toml (e.g., H_budget = 1.0) show recommended starting points for a typical rocky planet.

Noble gases

The noble gases He, Ne, Ar, Kr, and Xe are opt-in. A noble gas contributes only when its inclusion flag in [outgas.calliope] (include_He, ...) is true and its budget is positive; a run with no noble budget is unchanged. Each noble gas is partitioned between the magma ocean and the atmosphere by a Henry's-law solubility and tracked in the whole-planet mass balance.

In solar mode the budget is a multiple of the protosolar X/H mass ratio, so the inventory is budget * (X/H)_solar * H_kg; a value of 1.0 gives a protosolar noble gas complement.

Warning

The solar mode is an upper-bound reference, not a realistic default. Planetary bodies are depleted in noble gases by orders of magnitude relative to solar, so realistic budgets use solar with a value far below one, or set the inventory directly in kg or ppmw.

Partial pressures [planet.gas_prs]

Used when volatile_mode = "gas_prs". Sets the initial atmosphere directly by surface partial pressure for each gas species, in bar.

Parameter Type Default Description
H2O float 0 Initial atmospheric partial surface pressure of H2O [bar]. Must be >= 0.
CO2 float 0 Initial atmospheric partial surface pressure of CO2 [bar]. Must be >= 0.
N2 float 0 Initial atmospheric partial surface pressure of N2 [bar]. Must be >= 0.
S2 float 0 Initial atmospheric partial surface pressure of S2 [bar]. Must be >= 0.
SO2 float 0 Initial atmospheric partial surface pressure of SO2 [bar]. Must be >= 0.
H2S float 0 Initial atmospheric partial surface pressure of H2S [bar]. Must be >= 0.
NH3 float 0 Initial atmospheric partial surface pressure of NH3 [bar]. Must be >= 0.
H2 float 0 Initial atmospheric partial surface pressure of H2 [bar]. Must be >= 0.
CH4 float 0 Initial atmospheric partial surface pressure of CH4 [bar]. Must be >= 0.
CO float 0 Initial atmospheric partial surface pressure of CO [bar]. Must be >= 0.

Constraints

Cross-field constraints enforced when the config file loads:

  • Validate planet.fO2_source against O_mode, volatile_mode, and against availability.
  • Validate that mass_tot is within range.

See also: Model description | Earth analogue tutorial

  1. Fei, Y., Seagle, C.T., Townsend, J.P., et al., Melting and density of MgSiO3 determined by shock compression of bridgmanite to 1254 GPa, Nature Communications, 12, 876, 2021. SciX. ↩