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 2.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]. Outgassing treats H, C, N or S below it as absent; escape empties a non-noble element whose reachable mass (its total less the mass trapped in the solid) is below it, down to the trapped mass, except on a mantle frozen with params.stop.solid.freeze_volatiles. Noble gases are exempt. CALLIOPE also uses it as the absolute mass tolerance [kg] of its equilibrium solve. 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. Not available yet: true is rejected when the config loads.
T_floor float 700.0 Temperature floor [K]. The outgassing temperature is clamped to this value from below for the chemistry solve and the target masses. Must be > 0.0.
solver_rtol float 0.0001 Relative tolerance [1] of the CALLIOPE and atmodeller equilibrium solvers. It is also the relative tolerance of the per-element mass closure check that runs after each outgassing step while trapping is on. Must be > 0.0.
solver_atol float 1e-06 Absolute tolerance of the equilibrium solvers: CALLIOPE takes it as xtol of its root solve, atmodeller as atol. Unused by the dummy module. Must be > 0.0.
prevent_desaturation bool false Whether condensed mass leaves the outgassing system for good. With false, each solve re-equilibrates the whole inventory, so a condensate can re-vapourise as conditions change. With true, the mass held in each {e}_kg_condensed reservoir is withheld from the chemistry, from escape and from the desiccation gate, and the reservoir can only grow: a condensed layer can only get thicker. Each condensate's {X}_cd_activity is then the saturation of the inventory left in the solve, so it can fall below 1 while its layer is held. Only atmodeller with outgas.atmodeller.include_condensates forms condensates: with another backend, or with atmodeller and its condensates off, the flag holds nothing, and a warning at config load says so.
trap_mode str "none" Solid-phase volatile trapping during mantle crystallisation. Choices: 'none' (off) and 'front' (F_tl from the drainage of melt across the freezing front the interior solver resolves; needs interior_energetics.module = 'aragog'). The disaggregation melt fraction that tops the front is interior_energetics.rfront_loc, the melt fraction of the solver's own rheological transition, not a separate field. Choices: "none", "front".
trap_phi_min float 0.01 Porosity below which a node counts as solid [1]. Needed because the density-derived porosity never reaches exactly zero. Must be > 0.0 and < 1.0.
trap_mush_log10visc float -1.0 Log10 viscosity of the mush near the solidus [log10(Pa s)], entering the matrix deformation time. A value of zero or below selects the default of 20, mid-range of the 18 to 22 the literature allows.
trap_n_front_min int 3 Fewest nodes a freezing front must span before its drainage is integrated rather than bounded above. Must be >= 2.
trap_max_front_fraction float 1.0 Largest fraction of the mantle thickness the front may occupy before its drainage is bounded above instead of integrated [1]. The default of 1 sets no limit: where percolation controls the drainage, the retained fraction depends on the ratio of drainage speed to front speed and not on the front thickness, and a thicker front only lengthens the residence time. Must be > 0.0 and <= 1.0.
D_const_H2O float 0.0017 Crystal/melt partition coefficient of H2O [1], D = w_solid / w_liquid. Must be >= 0.0.
D_const_CO2 float 0.0 Crystal/melt partition coefficient of CO2 [1], D = w_solid / w_liquid. Must be >= 0.0.
D_const_O2 float 0.0 Crystal/melt partition coefficient of O2 [1], D = w_solid / w_liquid. Must be >= 0.0.
D_const_H2 float 0.0 Crystal/melt partition coefficient of H2 [1], D = w_solid / w_liquid. Must be >= 0.0.
D_const_CH4 float 0.0 Crystal/melt partition coefficient of CH4 [1], D = w_solid / w_liquid. Must be >= 0.0.
D_const_CO float 0.0 Crystal/melt partition coefficient of CO [1], D = w_solid / w_liquid. Must be >= 0.0.
D_const_N2 float 0.0 Crystal/melt partition coefficient of N2 [1], D = w_solid / w_liquid. Must be >= 0.0.
D_const_NH3 float 0.0 Crystal/melt partition coefficient of NH3 [1], D = w_solid / w_liquid. Must be >= 0.0.
D_const_S2 float 0.0 Crystal/melt partition coefficient of S2 [1], D = w_solid / w_liquid. Must be >= 0.0.
D_const_SO2 float 0.0 Crystal/melt partition coefficient of SO2 [1], D = w_solid / w_liquid. Must be >= 0.0.
D_const_H2S float 0.0 Crystal/melt partition coefficient of H2S [1], D = w_solid / w_liquid. 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. The samples come from a fixed seed, so identical inputs draw the same guesses, and an input that exhausts the samples fails the same way on a rerun. 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

bash install.sh sets atmodeller up as an editable clone in Atmodeller/; the default outgassing module is calliope. To set it up by hand, run bash tools/get_atmodeller.sh, or install from PyPI with pip install "fwl-proteus[atmodeller]". atmodeller is GPL-3.0 licensed; review its terms before installing. See atmodeller setup.

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 50 Maximum number of attempts per solve. atmodeller perturbs a start that fails and tries again, up to this many times, so a larger value costs time only on a solve that does not converge at once. A solve that still fails raises. Must be > 0.
include_condensates bool true Enable condensed phases in the equilibrium: every condensate atmodeller provides for the outgassing elements, which are graphite (C), sulfur (S), water (H2O) and sulfuric acid (H2O4S). Each joins a solve when its elements have budgets and T_magma lies inside its thermodynamic data range.

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 Lower bound [K] on the surface temperature that LavAtmos uses: the vapourisation runs at max(T_min, T_magma). Must be > 0.0.
melt_comp_name str "BSE_palm" Name of the melt composition file, a CSV file without its extension in the input/lava_compositions folder of LAVA_DIR.
P_melt float 0.01 Pressure used for melt activities [bar]. Must be > 0.0.
xatol float 1e-05 Absolute tolerance of the LavAtmos fO2 solve, passed to LavAtmos as its xatol argument. 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).
  • Front trapping reads the freezing front the Aragog interior resolves.
  • ZEPHYRUS escape with JANUS requires the escape stop criterion to be enabled.
  • prevent_desaturation holds nothing unless atmodeller forms condensates.
  • 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