Skip to content

Escape and outgassing

The [escape] section configures atmospheric escape (mass loss to space). The [outgas] section configures volatile outgassing (partitioning between interior and atmosphere).

Submodule documentation: ZEPHYRUS | CALLIOPE | atmodeller. See also Model description.

Atmospheric escape [escape]

Parameter Type Default Description
module str or none "zephyrus" Escape module to use. Choices: none, "dummy", "zephyrus", "boreas".
reservoir str "outgas" Escaping composition when not doing fractionation. Choices: bulk, outgas, pxuv.
hill_clamp bool true Limit the XUV level to the Hill radius. Gas beyond the Hill radius is not bound to the planet, so an XUV radius outside it sizes the escape cross-section with material the planet does not hold.
hill_clamp_frac float 1.0 Fraction of the Hill radius used as that limit, when hill_clamp is enabled. Must be > 0.0 and <= 1.0.
step_max_frac float 0.25 Largest share of the escapable reservoir a single step may remove. The bulk rate is sized without reference to how much mass remains, so over a long step it can ask for many times the reservoir. The default guards reduced compositions rather than limiting the grid. Measured on production cases, every one at IW-5 asks for more than it at some step and the worst for eighty times the reservoir, while cases from IW-1 to IW+5 stay under a thousandth of it and never meet the cap at all. A larger value lets one step take more of what is left, so a reduced case draws its reservoir down in fewer and coarser steps. The cap keeps binding at every setting in this range, because an unchanged rate settles at max_frac / (1 - max_frac), which is above the cap for every value it accepts. Must be > 0.0 and <= 1.0.
step_dt_floor_frac float 0.001 How far below params.dt.minimum a capped step may shorten the next one. The floor otherwise overrides the shortened step on 94 % of the steps the cap binds on, leaving the reduction inert where it is needed. Must be > 0.0 and <= 1.0.

ZEPHYRUS [escape.zephyrus]

Energy-limited escape: the mass loss rate scales with the XUV flux and escape efficiency.

Parameter Type Default Description
Pxuv float 5e-05 Pressure at which XUV radiation become opaque in the planetary atmosphere [bar]. Must be >= 0.
efficiency float 0.1 Escape efficiency factor. Must be >= 0 and <= 1.
tidal bool false Tidal contribution enabled.

Dummy escape [escape.dummy]

A fixed bulk escape rate, useful for testing and parameter studies.

Parameter Type Default Description
rate float 0.0 Bulk unfractionated escape rate [kg s-1]. Must be >= 0.

BOREAS [escape.boreas]

Hydrodynamic escape with optional elemental fractionation. BOREAS is an optional module; install it with bash tools/get_boreas.sh before setting escape.module = "boreas". It requires a radiative atmosphere model (atmos_clim.module = "agni" or "janus").

Parameter Type Default Description
fractionate bool true Enable elemental fractionation in outflow?.
efficiency float 0.1 Energy efficiency factor. Must be >= 0 and <= 1.
sigma_H float 1.89e-18 Absorption cross-section of H in XUV [cm2]. Must be >= 0.
sigma_O float 2e-18 Absorption cross-section of O in XUV [cm2]. Must be >= 0.
sigma_C float 2.5e-18 Absorption cross-section of C in XUV [cm2]. Must be >= 0.
sigma_N float 3e-18 Absorption cross-section of N in XUV [cm2]. Must be >= 0.
sigma_S float 6e-18 Absorption cross-section of S in XUV [cm2]. Must be >= 0.
kappa_H2 float 0.01 Grey H2 opacity in IR [cm2 g-1]. Must be >= 0.
kappa_H2O float 1.0 Grey H2O opacity in IR [cm2 g-1]. Must be >= 0.
kappa_O2 float 1.0 Grey O2 opacity in IR [cm2 g-1]. Must be >= 0.
kappa_CO2 float 1.0 Grey CO2 opacity in IR [cm2 g-1]. Must be >= 0.
kappa_CO float 1.0 Grey CO opacity in IR [cm2 g-1]. Must be >= 0.
kappa_CH4 float 1.0 Grey CH4 opacity in IR [cm2 g-1]. Must be >= 0.
kappa_N2 float 1.0 Grey N2 opacity in IR [cm2 g-1]. Must be >= 0.
kappa_NH3 float 1.0 Grey NH3 opacity in IR [cm2 g-1]. Must be >= 0.
kappa_H2S float 1.0 Grey H2S opacity in IR [cm2 g-1]. Must be >= 0.
kappa_SO2 float 1.0 Grey SO2 opacity in IR [cm2 g-1]. Must be >= 0.
kappa_S2 float 1.0 Grey S2 opacity in IR [cm2 g-1]. Must be >= 0.

Outgassing [outgas]

The outgassing module computes the thermodynamic equilibrium partitioning of volatiles between the atmosphere, silicate melt, and solid mantle at the planetary surface conditions.

Parameter Type Default Description
module str "calliope" Outgassing module to be used. Choices: "calliope", "atmodeller", "dummy".
fO2_shift_IW float 4.0 Oxygen fugacity relative to Iron-Wustite [log10 units]. Must be >= -12.0 and <= 12.0.
mass_thresh float 1e+16 Minimum threshold for element mass [kg]. Inventories below this are set to zero. Must be > 0.0.
h2_binodal bool false Enable binodal-controlled H2 partitioning between atmosphere and magma ocean using the Rogers+2025 H2-MgSiO3 miscibility model.
T_floor float 700.0 Temperature floor [K]. The outgassing temperature is clamped to this value from below before the chemistry solve. Must be > 0.0.
solver_rtol float 0.0001 Relative tolerance for the volatile equilibrium solver. Must be > 0.0.
solver_atol float 1e-06 Absolute tolerance for the volatile equilibrium solver. Must be > 0.0.
vapourise bool false Enable rock vapourisation via LavAtmos/ThermoEngineLite. Requires LAVA_DIR and FC_DIR to be set; see the optional modules installation guide. LavAtmos parameters are set in outgas.lavatmos.

CALLIOPE [outgas.calliope]

CALLIOPE uses Gibbs free energy minimisation to compute the gas-melt equilibrium at the planetary surface, handling C-H-N-O-S chemistry with fO\(_2\) buffering. The include_* switches exclude individual species from the equilibrium when set to false; the noble gases are excluded by default because their budgets are set in [planet.elements].

Species switches (set to false to exclude a species from the equilibrium)

Parameter Type Default Description
include_H2O bool true If True, include H2O.
include_CO2 bool true If True, include CO2.
include_N2 bool true If True, include N2.
include_S2 bool true If True, include S2.
include_SO2 bool true If True, include SO2.
include_H2S bool true If True, include H2S.
include_NH3 bool true If True, include NH3.
include_H2 bool true If True, include H2.
include_CH4 bool true If True, include CH4.
include_CO bool true If True, include CO.
include_He bool false If True, include He (noble gas; budget set in planet.elements).
include_Ne bool false If True, include Ne (noble gas; budget set in planet.elements).
include_Ar bool false If True, include Ar (noble gas; budget set in planet.elements).
include_Kr bool false If True, include Kr (noble gas; budget set in planet.elements).
include_Xe bool false If True, include Xe (noble gas; budget set in planet.elements).
solubility bool true Enable solubility of volatiles into melt.

Solver

Parameter Type Default Description
nguess int 1000 Maximum number of initial-guess samples for the CALLIOPE equilibrium solver. Default 1000. Must be > 0.
nsolve int 3000 Maximum number of iterations of the CALLIOPE equilibrium solver per call. Default 3000. Must be > 0.
p_guess_max float 100000.0 Upper bound [bar] of the CALLIOPE Monte-Carlo cold-start surface- pressure draw. Sets where the cold start samples, so raising it helps the solver find a high-pressure (e.g. sub-Neptune) basin faster. It does NOT raise the maximum pressure the solver can accept (CALLIOPE's fixed 1e7 bar box), so it is bounded to (0, 1e7]. Default 1e5. Must be > 0 and <= 10000000.0.

Atmodeller [outgas.atmodeller]

An alternative outgassing solver with configurable solubility laws and real-gas equations of state. Set a solubility_* law to "none" to disable dissolution for that species, and an eos_* entry to "none" for ideal-gas behaviour.

Note

atmodeller is an optional backend and is not installed with PROTEUS by default; the standard outgassing module is calliope. Install it with pip install "fwl-proteus[atmodeller]" before setting outgas.module = "atmodeller". atmodeller is GPL-3.0 licensed; review its terms before installing. See Installation: optional modules.

Parameter Type Default Description
solver_mode str "robust" Root-finding mode: 'robust' (slower compile, better convergence) or 'basic' (faster compile, less robust). Choices: "robust", "basic".
solver_max_steps int 1024 Maximum iterations for the root-finder. Must be > 0.
solver_multistart int 10 Number of random restarts for the root-finder. Must be > 0.
include_condensates bool true Enable condensate phases (graphite, etc.) in the equilibrium.

Solubility laws (set to "none" to disable dissolution for a species)

Parameter Type Default Description
solubility_H2O str or none "H2O_peridotite_sossi23" Solubility law for H2O. See atmodeller.solubility.library.
solubility_CO2 str or none "CO2_basalt_dixon95" Solubility law for CO2.
solubility_H2 str or none "H2_basalt_hirschmann12" Solubility law for H2.
solubility_N2 str or none "N2_basalt_dasgupta22" Solubility law for N2.
solubility_S2 str or none "S2_sulfide_basalt_boulliung23" Solubility law for S2.
solubility_CO str or none "CO_basalt_yoshioka19" Solubility law for CO. 'none' = no solubility.
solubility_CH4 str or none "CH4_basalt_ardia13" Solubility law for CH4. 'none' = no solubility.

Real gas EOS (set to "none" for ideal gas)

Parameter Type Default Description
eos_H2O str or none none Real gas EOS for H2O. 'none' = ideal gas.
eos_CO2 str or none none Real gas EOS for CO2. 'none' = ideal gas.
eos_H2 str or none none Real gas EOS for H2. 'none' = ideal gas.
eos_CH4 str or none none Real gas EOS for CH4. 'none' = ideal gas.
eos_CO str or none none Real gas EOS for CO. 'none' = ideal gas.

LavAtmos [outgas.lavatmos]

Rock vapourisation parameters, used when outgas.vapourise = true. Requires LAVA_DIR and FC_DIR; see Installation: optional modules. See also Model description.

Parameter Type Default Description
T_min float 1500.0 Minimum surface temperature [K] used by LavAtmos. Must be > 0.0.
melt_comp_name str "BSE_palm" Name of the melt composition file (without extension).
P_melt float 0.01 Pressure used for melt activities [bar]. Must be > 0.0.
xatol float 1e-05 Absolute tolerance for LavAtmos fO2 solve. Must be > 0.0.
fO2_buffer_model str "oneill" IW buffer model used for LavAtmos fO2 solve. One of 'oneill', 'fischer'. Choices: "oneill", "fischer".

Constraints

Cross-field constraints enforced when the config file loads:

  • BOREAS escape requires a radiative atmosphere (not dummy).
  • ZEPHYRUS escape with JANUS requires the escape stop criterion to be enabled.
  • ZEPHYRUS escape requires the MORS star module with the Spada evolution tracks.
  • Dummy escape requires a non-negative escape rate.
  • Escape reservoir must be one of 'bulk', 'outgas', or 'pxuv'.
  • Validate ZEPHYRUS settings: Pxuv within (0, 10] bar and efficiency within [0, 1].

See also: Escape modules | Outgassing modules