Skip to content

Configuration file

PROTEUS uses TOML to structure its configuration files. This page lists all parameters with their types, defaults, and descriptions. For topic-specific parameter guides, see the configuration reference pages:

For worked examples, see the Tutorials.

Defaults and required parameters

Every parameter has a built-in default. The defaults are defined in the configuration schema in src/proteus/config/, so a configuration file only needs to set the parameters whose defaults you want to change. Empty sections can be omitted entirely. The minimal.toml example shows how little a working file needs: a few science-critical choices (planet mass, orbit, volatiles, redox), with everything else left at its default.

Where to find the default for each parameter. The configuration reference pages listed above give the default value of every parameter in their Default column, alongside its type and description. The auto-generated listing further down this page is built from the same schema and shows each parameter's source definition, including the coded default value.

To see exactly which defaults applied to a run, open the init_coupler.toml file in that run's output folder. It is a completed copy of the configuration with every parameter resolved, including all the defaults that were filled in for the options you did not set. This is the fully-expanded configuration the simulation actually used.

Some parameters are conditionally required. A parameter that is only meaningful for one module is required when that module is selected. For example, the mors stellar evolution module (star.module = 'mors') requires star.mors.age_now, whereas the dummy module does not. The configuration loader reports an error at startup if a required parameter is missing for the chosen modules.

See all_options.toml for a comprehensive example. Have a look at the other input configs for ideas of how to set up your config in practice.

Root parameters

Config

Root config parameters.

Attributes:

Name Type Description
config_version str

Version of the configuration file format.
params Params

Parameters for code execution, output files, time-stepping, convergence.
star Star

Stellar parameters, model selection.
orbit Orbit

Orbital and star-system parameters.
planet Planet

Bulk planet properties (mass, initial volatile inventory).
interior_struct Struct

Planetary structure calculation (radius, composition, Zalmoxis).
interior_energetics Interior

Magma ocean / mantle energetics model parameters, model selection.
outgas Outgas

Outgassing parameters (fO2, etc) and included volatiles.
atmos_clim AtmosClim

Planetary atmosphere climate parameters, model selection.
atmos_chem AtmosChem

Planetary atmosphere chemistry parameters, model selection.
escape Escape

Atmospheric escape parameters, model selection.
accretion Accretion

Late accretion / delivery model selection.
observe Observe

Synthetic observations.

write(out)

Write configuration to a new TOML file.

Source code in src/proteus/config/_config.py 
353
354
355
356
357
358
359
360
361
362
363
364
365
366
def write(self, out: str):
    """
    Write configuration to a new TOML file.
    """

    # Convert to dictionary
    cfg = dict(asdict(self))

    # Replace None with "none"
    cfg = dict_replace_none(cfg)

    # Write to TOML file
    with open(out, 'w') as hdl:
        tomlkit.dump(cfg, hdl)

check_module_dependencies(instance, attribute, value)

Check that required external packages are importable for the selected modules.

Source code in src/proteus/config/_config.py 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def check_module_dependencies(instance, attribute, value):
    """Check that required external packages are importable for the selected modules."""
    import importlib

    checks = {
        'calliope': (
            instance.outgas.module == 'calliope',
            'calliope',
            'outgas.module = "calliope" requires the calliope package. '
            'Install with: git clone git@github.com:FormingWorlds/CALLIOPE && pip install -e CALLIOPE/.',
        ),
        'atmodeller': (
            instance.outgas.module == 'atmodeller',
            'atmodeller',
            'outgas.module = "atmodeller" requires the optional atmodeller package '
            '(GPL-3.0 licensed). The standard outgassing backend is calliope and '
            'needs no extra install. '
            'Install atmodeller with: pip install "fwl-proteus[atmodeller]" '
            '(or pip install "atmodeller>=1.0.0").',
        ),
        'vulcan': (
            instance.atmos_chem.module == 'vulcan',
            'vulcan',
            'atmos_chem.module = "vulcan" requires the optional VULCAN package '
            '(GPL-3.0 licensed). VULCAN is not needed for a standard PROTEUS run. '
            'Install it with: pip install "fwl-proteus[vulcan]" '
            '(or bash tools/get_vulcan.sh for an editable checkout).',
        ),
        'boreas': (
            instance.escape.module == 'boreas',
            'boreas',
            'escape.module = "boreas" requires the optional boreas package. '
            'Install it with: bash tools/get_boreas.sh',
        ),
    }

    for name, (needed, pkg, msg) in checks.items():
        if needed:
            try:
                importlib.import_module(pkg)
            except ImportError as e:
                raise ImportError(f'{msg}\n  Original error: {e}') from e

boreas_requires_atmosphere(instance, attribute, value)

BOREAS escape requires a radiative atmosphere (not dummy).

Source code in src/proteus/config/_config.py 
119
120
121
122
123
124
125
def boreas_requires_atmosphere(instance, attribute, value):
    """BOREAS escape requires a radiative atmosphere (not dummy)."""
    if (instance.escape.module == 'boreas') and (instance.atmos_clim.module == 'dummy'):
        raise ValueError(
            'escape.module = "boreas" requires a radiative atmosphere model (agni or janus), '
            'not atmos_clim.module = "dummy". BOREAS needs per-level T/P/composition profiles.'
        )

planet_mass_valid(instance, attribute, value)

Validate that mass_tot is within range.

Source code in src/proteus/config/_config.py 
146
147
148
149
150
151
152
def planet_mass_valid(instance, attribute, value):
    """Validate that mass_tot is within range."""
    mass_tot = instance.planet.mass_tot
    if mass_tot <= 0:
        raise ValueError('The total planet mass must be > 0')
    if mass_tot > 20:
        raise ValueError('The total planet mass must be < 20 M_earth')

planet_oxygen_mode_explicit(instance, attribute, value)

Validate O_mode in planet.elements.

Whole-planet oxygen accounting requires every config to declare how the IC O budget is interpreted. Valid modes: 'ic_chemistry' (default, defer to CALLIOPE equilibrium), 'ppmw', 'kg', 'FeO_mantle_wt_pct'.

Source code in src/proteus/config/_config.py 
155
156
157
158
159
160
161
162
163
164
165
def planet_oxygen_mode_explicit(instance, attribute, value):
    """Validate O_mode in planet.elements.

    Whole-planet oxygen accounting requires every config to declare how
    the IC O budget is interpreted. Valid modes: 'ic_chemistry' (default,
    defer to CALLIOPE equilibrium), 'ppmw', 'kg', 'FeO_mantle_wt_pct'.
    """
    # O_mode is now validated by the attrs in_() validator on the field
    # itself. This function remains as a hook for cross-field checks
    # (e.g. fO2_source compatibility) that reference O_mode.
    pass

planet_fO2_source_compat(instance, attribute, value)

Validate planet.fO2_source against O_mode, volatile_mode, and against availability.

Rejection rules:

  1. fO2_source = "from_mantle_redox" is a reserved enum value for the radial Fe3+/Fe2+ fO2 framework (issue #653, Schaefer et al. 2024). The runtime path for it does not exist yet; reject the config so users do not silently fall through to the default behaviour.

  2. fO2_source = "from_O_budget" requires the O budget to be authoritative. O_mode = "ic_chemistry" defers the O inventory to the chemistry solver, so there is nothing to invert against. Require a concrete O budget ("ppmw" / "kg" / "FeO_mantle_wt_pct") instead.

  3. fO2_source = "from_O_budget" requires the volatile budget to be set element-wise. volatile_mode = "gas_prs" supplies partial pressures directly and makes planet.elements.O_mode inoperative, so there is nothing to invert against. Switch volatile_mode to "elements" or pick a different fO2_source.

  4. fO2_source = "from_O_budget" requires an outgassing backend with an authoritative-O implementation: CALLIOPE (equilibrium_atmosphere_authoritative_O) and atmodeller (native mass-constraint API) both qualify; the dummy backend does not. The runtime dispatch echoes this rejection too, but failing at config-load saves the user from burning interior IC and structure setup before hitting the wall.

fO2_source = "user_constant" (default) accepts every O_mode and every volatile_mode.

Warning rule:

  • fO2_source = "from_O_budget" with a non-default outgas.fO2_shift_IW emits a UserWarning. With this source the buffer offset is derived, so a user-supplied value is silently ignored. The warning surfaces the misconfiguration without blocking the run.
Source code in src/proteus/config/_config.py 
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
def planet_fO2_source_compat(instance, attribute, value):
    """Validate planet.fO2_source against O_mode, volatile_mode, and
    against availability.

    Rejection rules:

    1. ``fO2_source = "from_mantle_redox"`` is a reserved enum value for
       the radial Fe3+/Fe2+ fO2 framework (issue #653, Schaefer et al.
       2024). The runtime path for it does not exist yet; reject the
       config so users do not silently fall through to the default behaviour.

    2. ``fO2_source = "from_O_budget"`` requires the O budget to be
       authoritative. ``O_mode = "ic_chemistry"`` defers the O inventory
       to the chemistry solver, so there is nothing to invert against.
       Require a concrete O budget
       ("ppmw" / "kg" / "FeO_mantle_wt_pct") instead.

    3. ``fO2_source = "from_O_budget"`` requires the volatile budget to
       be set element-wise. ``volatile_mode = "gas_prs"`` supplies
       partial pressures directly and makes ``planet.elements.O_mode``
       inoperative, so there is nothing to invert against. Switch
       ``volatile_mode`` to ``"elements"`` or pick a different fO2_source.

    4. ``fO2_source = "from_O_budget"`` requires an outgassing backend
       with an authoritative-O implementation: CALLIOPE
       (``equilibrium_atmosphere_authoritative_O``) and atmodeller
       (native mass-constraint API) both qualify; the ``dummy`` backend
       does not. The runtime dispatch echoes this rejection too, but
       failing at config-load saves the user from burning interior IC
       and structure setup before hitting the wall.

    ``fO2_source = "user_constant"`` (default) accepts every O_mode and
    every volatile_mode.

    Warning rule:

    - ``fO2_source = "from_O_budget"`` with a non-default
      ``outgas.fO2_shift_IW`` emits a UserWarning. With this source the
      buffer offset is *derived*, so a user-supplied value is silently
      ignored. The warning surfaces the misconfiguration without
      blocking the run.
    """
    fO2_source = instance.planet.fO2_source
    O_mode = instance.planet.elements.O_mode
    volatile_mode = instance.planet.volatile_mode

    if fO2_source == 'from_mantle_redox':
        raise ValueError(
            'planet.fO2_source = "from_mantle_redox" is reserved for the '
            'radial Fe3+/Fe2+ tracking framework (issue #653) and is not '
            'yet wired into the runtime. Use "user_constant" (fO2 '
            'buffered by outgas.fO2_shift_IW) or "from_O_budget" '
            '(authoritative O budget, fO2 derived) instead.'
        )

    if fO2_source == 'from_O_budget' and O_mode == 'ic_chemistry':
        raise ValueError(
            'planet.fO2_source = "from_O_budget" requires an authoritative '
            'O budget but planet.elements.O_mode = "ic_chemistry" defers '
            'the O inventory to the chemistry solver. Pick an explicit O '
            'budget mode ("ppmw", "kg", or "FeO_mantle_wt_pct") or switch '
            'fO2_source back to "user_constant".'
        )

    if fO2_source == 'from_O_budget' and volatile_mode == 'gas_prs':
        raise ValueError(
            'planet.fO2_source = "from_O_budget" requires '
            'planet.volatile_mode = "elements" so the O inventory is '
            'derived from planet.elements.O_budget. Under '
            'volatile_mode = "gas_prs" the user supplies partial '
            'pressures directly and the element budgets are inert, so '
            'there is no O target to invert against. Either switch '
            'volatile_mode to "elements" or set fO2_source back to '
            '"user_constant".'
        )

    if fO2_source == 'from_O_budget':
        outgas_module = getattr(instance.outgas, 'module', None)
        if outgas_module == 'dummy':
            raise ValueError(
                'planet.fO2_source = "from_O_budget" requires an '
                'outgassing backend with an authoritative-O '
                'implementation. outgas.module = "dummy" has no '
                'chemistry to invert against. Switch outgas.module to '
                '"calliope" or '
                '"atmodeller", or set fO2_source back to '
                '"user_constant".'
            )

    if fO2_source == 'from_O_budget':
        import warnings

        fO2_shift_IW = getattr(instance.outgas, 'fO2_shift_IW', None)
        if fO2_shift_IW is not None and fO2_shift_IW != 0.0:
            warnings.warn(
                'outgas.fO2_shift_IW = %.3f is set but '
                'planet.fO2_source = "from_O_budget" derives the buffer '
                'offset from the O budget. The configured value is used '
                'only as the solver initial fO2 guess, not as the buffered '
                'offset.' % fO2_shift_IW,
                UserWarning,
                stacklevel=2,
            )

boundary_requires_fixed_surface_state(instance, attribute, value)

Boundary backend assumes a fixed surface state coupling.

Source code in src/proteus/config/_config.py 
273
274
275
276
277
278
279
280
def boundary_requires_fixed_surface_state(instance, attribute, value):
    """Boundary backend assumes a fixed surface state coupling."""
    if (instance.interior_energetics.module == 'boundary') and (
        instance.atmos_clim.surf_state != 'fixed'
    ):
        raise ValueError(
            "Must set atmos_clim.surf_state='fixed' when interior_energetics.module='boundary'"
        )

General parameters

This module describes the parameters for the data location, data output, and logging. It also defines stopping criteria.

OutputParams

Parameters for output files and logging

Attributes:

Name Type Description
path str

Output folder name inside PROTEUS/output/. Set to "auto" (default) for a unique timestamped name (run_YYYYMMDD_HHMMSS_xxxx), or any string for a fixed folder (e.g. "my_earth_run").
logging str

Log verbosity. Choices: 'INFO', 'DEBUG', 'ERROR', 'WARNING'.
plot_fmt str

Plotting output file format. Choices: "png", "pdf".
write_mod int

Write CSV frequency. 0: wait until completion. n: every n iterations.
dt_write_rel float

Minimum elapsed simulation time between data writes, expressed as a fraction of the current simulation time. The effective minimum write interval is dt_write_rel * Time. This gives logarithmic spacing: at Time=1e3 yr with dt_write_rel=1e-3 the guard is 1 yr; at Time=1e9 yr it is 1e6 yr. Set to 0 to write every time write_mod triggers (default, preserving existing behaviour).
plot_mod int | None

Plotting frequency. 0: wait until completion. n: every n iterations. None: never plot.
archive_mod int | None

Archive frequency. 0: wait until completion. n: every n iterations. None: never archive.
remove_sf bool

Remove SOCRATES spectral files after model terminates.

TimeStepParams

Parameters for time-stepping.

Attributes:

Name Type Description
minimum float

Minimum absolute time-step size [yr].
minimum_rel float

Minimum relative time-step size [dimensionless].
maximum float

Maximum time-step size [yr].
initial float

Initial time-step size [yr].
starspec float

Maximum interval at which to recalculate the stellar spectrum [yr].
starinst float

Maximum interval at which to recalculate instellation flux [yr].
method str

Time-stepping method. Choices: 'proportional', 'adaptive', 'maximum'.
propconst float

Proportionality constant (proportional method).
atol float

Absolute tolerance on time-step size (adaptive method) [yr].
rtol float

Relative tolerance on time-step size (adaptive method) [dimensionless].
scale_incr float

Scale factor to grow time-step on a successful adaptive step [dimensionless, must be >1].
scale_decr float

Scale factor to shrink time-step on a rejected adaptive step [dimensionless, in (0, 1)].
window int

Number of previous steps to consider for adaptive-method comparison [dimensionless].
maximum_rel float

Time-fraction allowance added to dt.maximum on every step [dimensionless]. The effective per-step cap is the sum dt.maximum + maximum_rel * Time, so at the default 1.0 the allowance grows linearly with simulation Time, and the absolute dt.maximum acts as the early-time floor (cap doubles at Time = dt.maximum). Set maximum_rel = 0.0 to disable the time-proportional allowance and recover the strict dt = min(dt.maximum, ...) cap.
mushy_maximum float

Maximum time-step size [yr] during the mushy-zone transition (phi_crit < Phi_global < mushy_upper). Tighter than maximum because the interior solver hits stiffness cliffs in this regime (phase-boundary Jgrav + rheology contrast). Set to 0 (default) to disable the mushy-regime cap, in which case maximum applies throughout. A typical value for Aragog at 1 M_E is ~4e3 yr; see input/tutorials/tutorial_earth.toml.
mushy_upper float

Upper bound of the mushy regime [dimensionless melt fraction]. When Phi_global < mushy_upper AND Phi_global > stop.solid.phi_crit, mushy_maximum takes over from maximum. Default 0.99 so the cap kicks in as soon as the first cell crystallises.
hysteresis_iters int

Number of PROTEUS iterations after an adaptive "slow down" decision during which the speed-up factor is suppressed. Prevents the controller from ramping dt straight back into the same stiffness cliff it just escaped from. Default 3; set to 0 to disable.
hysteresis_sfinc float

Replacement speed-up factor applied while the hysteresis counter is active. Must be >= 1.0 and <= SFINC (1.6). Default 1.1 (gentle ramp-up).

StopIters

Parameters for iteration number criteria.

Attributes:

Name Type Description
enabled bool

Enable criteria if True
minimum int

Minimum number of iterations.
maximum int

Maximum number of iterations.

StopTime

Parameters for maximum time criteria.

Attributes:

Name Type Description
enabled bool

Enable criteria if True
minimum float

Model will absolutely not terminate until at least this time is reached [yr].
maximum float

Model will terminate when this time is reached [yr].

StopSolid

Parameters for solidification criteria.

Attributes:

Name Type Description
enabled bool

Enable termination at solidification if True.
phi_crit float

Model will terminate (if enabled) or freeze volatiles (if freeze_volatiles) when global melt fraction drops below this value.
freeze_volatiles bool

When True, outgassing stops at crystallization (Phi_global < phi_crit) but the simulation continues. Dissolved volatiles are trapped in the solid mantle and preserved in the helpfile. The atmosphere retains its current composition. When False, outgassing continues regardless of melt fraction. Default True.

StopRadeqm

Parameters for radiative equilibrium stopping criteria.

Attributes:

Name Type Description
enabled bool

Enable criteria if True
atol float

Absolute tolerance on energy balance [W m-2].
rtol float

Relative tolerance on energy balance.

StopEscape

Parameters for escape stopping criteria.

Attributes:

Name Type Description
enabled bool

Enable criteria if True
p_stop float

Model will terminate when surface pressure is less than this value [bar].

StopDisint

Parameters for planet disintegration stopping criteria.

Attributes:

Name Type Description
enabled bool

Enable all planet disintegration criteria if True
roche_enabled bool

Disable Roche limit criterion
offset_roche float

Absolute correction (+/-) to (increase/decrease) calculated Roche limit [m].
spin_enabled bool

Disable Breakup period criterion
offset_spin float

Absolute correction (+/-) to (increase/decrease) calculated Breakup period [s].

StopClock

Parameters for maximum clock runtime stopping criteria.

Attributes:

Name Type Description
enabled bool

Enable criteria if True
maximum float

Model will terminate when runtime exceeds this value [s].

StopParams

Parameters for termination criteria.

Attributes:

Name Type Description
strict bool

Require termination criteria to be satisfied twice before the model exits.
iters StopIters

Parameters for iteration number criteria.
time StopTime

Parameters for maximum time criteria.
solid StopSolid

Parameters for solidification criteria.
radeqm StopRadeqm

Parameters for radiative equilibrium criteria.
escape StopEscape

Parameters for escape criteria.
disint StopDisint

Parameters for planet disintegration criteria.
clock StopClock

Parameters for maximum clock runtime criteria.

Params

Parameters for code execution, output files, time-stepping, convergence.

Attributes:

Name Type Description
out OutputParams

Parameters for data / logging output.
dt TimeStepParams

Parameters for time-stepping.
stop StopParams

Parameters for stopping criteria.

Stellar evolution

Mors

Module parameters for MORS module.

Attributes:

Name Type Description
rot_pcntle float

Rotation, as percentile of stellar population.
rot_period float

Rotation rate [days].
tracks str

Stellar evolution track to be used. Choices: 'spada', 'baraffe'.
age_now float

Observed estimated age of the star [Gyr].
star_name str

Name of the star, to find appropriate stellar spectrum. See documentation.
star_path str

Path to custom stellar spectra. If 'none', star_name will be used to find spectra in default locations.
spectrum_source str

Source of stellar spectra. Choices: 'solar', 'muscles', 'phoenix', 'none'.
phoenix_FeH float

Stellar metallicity [Fe/H] to be used for PHOENIX synthetic spectra, if spectrum_source is 'phoenix'.
phoenix_alpha float

Alpha-element enhancement [alpha/Fe] to be used for PHOENIX synthetic spectra, if spectrum_source is 'phoenix'.
phoenix_radius float

Stellar radius [R_sun]. If 'none', radius will be calculated using mors' stellar tracks, if spectrum_source is 'phoenix'.
phoenix_log_g float

Surface gravity [cgs]. If 'none', log g will be calculated will be calculated using mors' stellar tracks, if spectrum_source is 'phoenix'.
phoenix_Teff float

Effective temperature [K]. If 'none', Teff will be calculated will be calculated using mors' stellar tracks, if spectrum_source is 'phoenix'.

StarDummy

Dummy star module.

Attributes:

Name Type Description
radius float

Observed radius [R_sun].
calculate_radius bool

Calculate the radius using empirical mass-luminosity and mass-radius relation
Teff float

Observed effective temperature [K].

Star

Stellar parameters, model selection.

You can find useful reference data in the documentation.

Attributes:

Name Type Description
bol_scale float

Scale factor to increase the luminosity.
mass float

Stellar mass [M_sun]. Note that for Mors, it should be between 0.1 and 1.25 solar masses. Values outside of the valid range will be clipped.
age_ini float

Age of system at model initialisation [Gyr].
module str | None

Select star module to use.
mors Mors

Parameters for MORS module.
dummy StarDummy

Parameters for the dummy star module

Orbital evolution and tides

OrbitDummy

Dummy orbit/tidal heating module.

Uses a fixed tidal heating power density and love number.

Attributes:

Name Type Description
H_tide float

Fixed global heating rate from tides [W kg-1].
Phi_tide str

Inequality which, if locally true, determines in which regions tides are applied.
Imk2 float

Imaginary part of k2 Love number, which is usually negative.

Lovepy

Lovepy tides module.

Attributes:

Name Type Description
visc_thresh float

Minimum viscosity required for heating [Pa s].
ncalc int

Number of interpoltaed interior levels to use for solving tidal heating rates.

Orbit

Planetary and satellite orbital parameters.

Includes initial conditions, and options for enabling dynamical evolution.

Attributes:

Name Type Description
semimajoraxis float

Initial semi-major axis of the planet's orbit [AU].
eccentricity float

Initial Eccentricity of the planet's orbit.
instellation_method str

Whether to use the semi-major axis ('distance') or instellation flux ('inst') to define the planet's initial orbit
instellationflux float

Instellation flux initially received by the planet in Earth units.
zenith_angle float

Characteristic angle of incoming stellar radiation, relative to the zenith [deg].
s0_factor float

Scale factor applies to incoming stellar radiation to represent planetary rotation.
evolve bool

Allow the planet's orbit to evolve based on eccentricity tides?
axial_period float | None

Planet initial day length [hours], will use orbital period if value is None.
satellite bool

Model a satellite (moon) orbiting the planet and solve for its orbit?
semimajoraxis_sat float

Satellit initial semi-major axis [m]
module str | None

Select orbit module to use. Choices: 'none', 'dummy', 'lovepy'.

Interior structure

Zalmoxis

Parameters for Zalmoxis module.

Attributes:

Name Type Description
core_eos str

EOS for the core layer. Format: ":". Tabulated: "PALEOS:iron" (default), "Seager2007:iron". Analytic: "Analytic:iron", "Analytic:MgFeSiO3", etc.
mantle_eos str

EOS for the mantle layer. Format: ":". Tabulated: "PALEOS:MgSiO3" (default), "PALEOS-2phase:MgSiO3", "Seager2007:MgSiO3", "WolfBower2018:MgSiO3". Analytic: "Analytic:MgSiO3", "Analytic:MgFeSiO3", etc.
ice_layer_eos str or None

EOS for the ice/water layer (3-layer model). 'none' for 2-layer model (core + mantle only). Tabulated: "PALEOS:H2O", "Seager2007:H2O". Analytic: "Analytic:H2O".
mushy_zone_factor float

Cryoscopic depression factor controlling the width of the mushy zone (partially molten region) in the PALEOS unified EOS. Defines the solidus as T_sol = T_liq * mushy_zone_factor. 1.0 = sharp phase boundary (no mushy zone). 0.8 = solidus at 80% of the liquidus temperature, roughly matching the Stixrude+2014 cryoscopic depression for MgSiO3. Must be in [0.7, 1.0]. Only applies to PALEOS unified EOS; ignored for WolfBower2018 and RTPress100TPa (which use explicit melting curve files). This factor is applied consistently across Zalmoxis (density interpolation), SPIDER (phase boundaries), and the VolatileProfile phi-blending.
mantle_mass_fraction float

Fraction of the planet's interior mass corresponding to the mantle. Required for 3-layer models (with ice layer) and for T-dependent 2-layer models (WolfBower2018, RTPress100TPa) where it partitions mass between core and mantle layers.
num_levels int

Number of Zalmoxis radius layers.
solver_tol_outer float

Relative tolerance for mass convergence (outer loop).
solver_tol_inner float

Relative tolerance for density convergence (inner loop).
solver_max_iter_outer int

Max iterations for mass convergence (outer loop).
solver_max_iter_inner int

Max iterations for density convergence (inner loop).
lookup_nP int

Number of pressure points in SPIDER P-S tables generated from PALEOS.
lookup_nS int

Number of entropy points in SPIDER P-S tables generated from PALEOS.

Struct

Planetary structure (mass, radius).

Attributes:

Name Type Description
core_frac float

Fraction of the planet's interior radius corresponding to the core.
module str

Module for solving the planet's interior structure. Choices: 'dummy', 'spider', 'zalmoxis'.
zalmoxis Zalmoxis or None

Zalmoxis parameters if module is 'zalmoxis'.
core_frac_mode str

How core_frac is interpreted. 'radius': fraction of planet radius. 'mass': fraction of total planet mass. Only 'radius' is supported when module = 'spider'. The zalmoxis module always interprets core_frac as a mass fraction and ignores this flag (a warning is emitted at runtime if 'radius' is set with module = 'zalmoxis').
core_density float or str

Density of the planet's core [kg m-3]. Set to 'self' for self-consistent calculation by Zalmoxis (requires module = 'zalmoxis').
core_heatcap float or str

Specific heat capacity of the planet's core [J kg-1 K-1]. Set to 'self' for self-consistent calculation by Zalmoxis (requires module = 'zalmoxis').

Magma ocean and planetary interior

Spider

SPIDER-specific parameters.

solver_type is the SUNDIALS integrator choice. tolerance_rel is a deprecated alias for the top-level [interior_energetics].rtol; set rtol instead. matprop_smooth_width sets the smoothing width for material-property blending across the solidus/liquidus, read by both SPIDER and Aragog.

Attributes:

Name Type Description
solver_type str

SUNDIALS integrator choice. Choices: 'adams', 'bdf'.
tolerance_rel float

Deprecated alias for Interior.rtol. Set interior_energetics.rtol at the top level instead.
matprop_smooth_width float

Melt-fraction window width for smoothing material properties across the solidus/liquidus. Passed to SPIDER as -matprop_smooth_width and to Aragog via _PhaseMixedParameters.

Aragog

Aragog-specific parameters.

Attributes:

Name Type Description
mass_coordinates bool

Whether to use mass coordinates in the model. Default is True. Uses uniform spacing in mass coordinate space, giving larger cells at the surface where density is lower, matching SPIDER's mesh.
backend str

ODE backend selector. Default 'jax'. - 'jax' : CVODE with JAX-derived RHS and JAX analytic Jacobian (jax.jacrev). Recommended for production. - 'numpy' : CVODE with numpy RHS and CVODE finite-difference Jacobian. Available for development and SPIDER-parity comparisons; less robust than 'jax' at production resolution because the FD-Jacobian noise can trip Aragog's T_core-jump retry guard at tight tolerances. The diffrax direct-JAX integration path is research-only and gated on a code-level flag in proteus.interior_energetics.aragog.
atol_temperature_equivalent float

Effective temperature-scale absolute tolerance [K] for Aragog's CVODE integrator. Aragog's state variable is entropy (J/kg/K), but users think in Kelvin, so this is exposed as a temperature equivalent that Aragog converts internally via Cp/T. Default is 1e-8 K, matching SPIDER's atol=rtol=1e-8 setting; this tight tolerance eliminates the CVODE marginal-stability bifurcation at the first dt jump after equilibration.
core_bc str

Core-mantle boundary condition mode. Default 'energy_balance'. Valid values: - 'quasi_steady': alpha-factor heat-flux partition; gives about -19% T_core offset vs SPIDER. - 'energy_balance': SPIDER bit-parity BC with dSdr_cmb as a new state variable (mirrors SPIDER bc.c:76-131). - 'gradient': gradient-based state with two boundary entropies as state variables. - 'bower2018': experimental, do not use for production.

atol_temperature_equivalent = field(default=1e-08, validator=(gt(0))) class-attribute instance-attribute

Effective temperature-scale absolute tolerance [K] for Aragog's ODE integrator. Default 1e-8 matches SPIDER's atol=rtol=1e-8 setting; this tight tolerance avoids a marginal-stability bifurcation at the first dt jump after equilibration.

phase_smoothing = field(default='tanh', validator=(in_(('tanh', 'cubic_hermite')))) class-attribute instance-attribute

Phase-boundary smoothing for Jgrav and Jmix: 'tanh' (SPIDER parity) or 'cubic_hermite'.

solver_method = field(default='cvode', validator=(in_(('cvode', 'radau', 'bdf')))) class-attribute instance-attribute

ODE solver: 'cvode' (SUNDIALS, SPIDER parity), 'radau' (scipy), 'bdf' (scipy).

scalar_gravity_override = field(default=False) class-attribute instance-attribute

Scalar-gravity comparison knob. When True, the external mesh file that Zalmoxis writes has its gravity column overwritten with a uniform scalar (the surface value from hf_row['gravity']) before Aragog reads it, so Aragog's per-node gravity path interpolates to that scalar everywhere. False by default; set True only when running a paired scalar-gravity comparison.

phi_step_cap = field(default=0.0, validator=_step_cap_valid) class-attribute instance-attribute

Per-call melt-fraction step cap. When > 0 and any staggered cell is in or near the two-phase window at solve() entry, a CVODE root function (and the equivalent scipy event) returns control at the exact time the larger of the global mass-weighted |ΔΦ| and the maximum single-cell |Δφ| reaches this cap. The per-cell term bounds how far one deep cell may cross the mushy window in a single call, which removes the discontinuous core-temperature drop at crystallisation onset. Schema default 0.0, which the Aragog wrapper promotes to a non-zero default for the coupled zalmoxis interior stack; a positive value here overrides that. -1.0 is the single off sentinel that keeps the cap disabled even on zalmoxis; any other negative, NaN, or infinity is rejected at load.

temperature_step_cap = field(default=0.0, validator=_step_cap_valid) class-attribute instance-attribute

Per-call per-cell temperature step cap [K]. Shares the same root function as phi_step_cap and fires on the maximum single-cell |ΔT| since solve() entry. It bounds the core-temperature drop on the solid adiabat just below the solidus, where the melt-fraction cap goes blind because a fully solid cell's melt fraction can no longer move. Schema default 0.0, which the Aragog wrapper promotes to a non-zero default for the coupled zalmoxis stack; a positive value overrides that. -1.0 is the single off sentinel that keeps the cap disabled even on zalmoxis; any other negative, NaN, or infinity is rejected at load.

entropy_step_cap = field(default=0.0, validator=_step_cap_valid) class-attribute instance-attribute

Per-call per-cell entropy step cap [J/kg/K], in the native solver variable; same role as temperature_step_cap without an EOS lookup in the root function. Schema default 0.0, which the Aragog wrapper promotes to a non-zero default for the coupled zalmoxis stack; a positive value overrides that. -1.0 is the single off sentinel that keeps the cap disabled even on zalmoxis; any other negative, NaN, or infinity is rejected at load.

phase_boundary_entropy_margin = field(default=200.0, validator=(gt(0))) class-attribute instance-attribute

Phase-boundary proximity band [J/kg/K] within which a staggered cell counts as near a solidus or liquidus crossing, tightening the integrator max_step so CVODE resolves the stiff two-phase RHS across the boundary. This is a solver-accuracy control, not a cosmetic step-size setting: at the default it reproduces the fixed band and the converged trajectory is unchanged, but lowering it below the default can under-resolve a real phase crossing and shift the converged state, because CVODE's local error control can accept an over-large step across the near-discontinuous RHS. Keeping the default reproduces current behaviour, and modestly widening the band does not move a converged result because tighter steps only refine an adaptive integrator; but a value orders of magnitude above the default makes every cell count as near a boundary at all times, clamping the integrator to 1 yr steps (max_step = 1 yr, versus 100 yr otherwise) for the whole run and stalling it, so keep the band of order a few hundred J/kg/K. Default 200.0, matching Aragog's own default; a positive value is required (0 or negative is not a valid disabled state for a proximity band).

tolerance_struct = field(default=100.0, validator=(gt(0))) class-attribute instance-attribute

Absolute mass tolerance [kg] for the secant solver in determine_interior_radius. Default 100 kg; pairs with Spider's matching field so both backends drive the same outer-loop convergence criterion.

InteriorBoundary

Parameters for Boundary interior module. Default values taken from Schaefer et al. 2016 (https://iopscience.iop.org/article/10.3847/0004-637X/829/2/63/pdf).

Attributes:

Name Type Description
T_solidus float

Mantle solidus temperature [K].
T_liquidus float

Mantle liquidus temperature [K].
critical_rayleigh_number float

Critical Rayleigh number for onset of convection [-].
nusselt_exponent float

Nusselt-Rayleigh scaling exponent [-].
silicate_heat_capacity float

Silicate heat capacity [J/kg/K].
atm_heat_capacity_const bool

Always use fallback atmosphere heat capacity?
atm_heat_capacity float

Used as fallback for atmosphere heat capacity when layer-specific value is not available [J/kg/K].
silicate_density float

Silicate density [kg/m^3]. Default taken from Fei et. al. 2021 (https://ui.adsabs.harvard.edu/abs/2021NatCo..12..876F).
core_density float

Core density [kg/m^3].
thermal_conductivity float

Thermal conductivity [W/m/K].
thermal_diffusivity float

Thermal diffusivity [m^2/s].
thermal_expansivity float

Thermal expansivity [1/K].
viscosity_model int

Viscosity parameterisation model. Choices: 1 (constant), 2 (aggregate smooth transition), 3 (Arrhenius temperature-dependent).
dynamic_viscosity float

Reference dynamic viscosity [Pa s] for Arrhenius solid mantle model.
activation_energy float

Activation energy [J/mol] for Arrhenius solid mantle model.
creep_parameter float

Creep parameter [-] for Arrhenius solid mantle model.
viscosity_prefactor float

Viscosity prefactor [Pa s] for Vogel-Fulcher-Tammann magma ocean model.
viscosity_activation_temp float

Activation temperature [K] for Vogel-Fulcher-Tammann magma ocean model.
logging bool

Whether to create diagnostic CSV data files from boundary interior module.

InteriorDummy

Parameters for Dummy interior module.

Attributes:

Name Type Description
mantle_rho float

Mantle density [kg m-3] for the dummy density profile and the fallback mantle-mass estimate. When the interior structure provides the masses, the mantle mass is taken as M_int - M_core instead.
mantle_cp float

Mantle specific heat capacity [J kg-1 K-1]
mantle_tliq float

Mantle liquidus temperature [K]
mantle_tsol float

Mantle solidus temperature [K]
heat_internal float

Fixed internal heating rate (e.g. radiogenic) [W kg-1]. Tidal heating is handled separately via heat_tidal and is added on top of this value.

Interior

Magma ocean model selection and parameters.

Attributes:

Name Type Description
grain_size float

Crystal settling grain size [m].
flux_guess float

Initial heat flux guess [W m-2]. When < 0 (default), computed automatically as sigma * T_magma^4. Set to a positive value to prescribe a specific initial flux. Set to 0 for zero initial flux.
radio_tref float

Reference age for setting radioactive decay [Gyr].
radio_K float

Concentration (ppmw) of potassium-40 at reference age t=radio_tref.
radio_U float

Concentration (ppmw) of uranium at reference age t=radio_tref.
radio_Th float

Concentration (ppmw) of thorium-232 at reference age t=radio_tref.
heat_radiogenic bool

Include radiogenic heat production?
heat_tidal bool

Include tidal heating?
rfront_loc float

Centre of rheological transition in terms of melt fraction
rfront_wid float

Width of rheological transition in terms of melt fraction
module str

Module for simulating the magma ocean. Choices: 'spider', 'aragog', 'dummy'.
spider Spider

Parameters for running the SPIDER module.
aragog Aragog

Parameters for running the aragog module.
dummy Dummy

Parameters for running the dummy module.
Notes

The melting_dir and eos_dir fields live on the parent [interior_struct] section (class Struct in config/_struct.py), not here. They are shared across SPIDER, Aragog, and Zalmoxis and so belong with the structure config.

rtol = field(default=_TOL_UNSET, validator=_gt0_or_unset) class-attribute instance-attribute

Relative numerical tolerance for the interior ODE solver. SPIDER: -ts_sundials_rtol (used internally via atol_sf scaling). Aragog: scipy solve_ivp rtol. The deprecated aliases num_tolerance and [interior_energetics.spider].tolerance_rel copy into this field. Resolves to 1e-10 when left unset.

atol = field(default=1e-10, validator=(gt(0))) class-attribute instance-attribute

Absolute numerical tolerance for the interior ODE solver. SPIDER: -ts_sundials_atol (scaled by atol_sf at runtime). Aragog uses [interior_energetics.aragog].atol_temperature_equivalent instead because its state variable is entropy, not temperature, and a direct entropy-scale atol would be unintuitive to tune.

adams_williamson_rhos = field(default=4078.95095544, validator=(gt(0))) class-attribute instance-attribute

Adams-Williamson surface density [kg/m^3]. Matches SPIDER -adams_williamson_rhos and Aragog _MeshParameters.surface_density.

adams_williamson_beta = field(default=1.1115348931000002e-07, validator=(gt(0))) class-attribute instance-attribute

Adams-Williamson density gradient [1/m]. Matches SPIDER -adams_williamson_beta. Aragog derives its own via bulk modulus, so this value applies to SPIDER only.

adiabatic_bulk_modulus = field(default=260000000000.0, validator=(gt(0))) class-attribute instance-attribute

Adiabatic bulk modulus [Pa] used by Aragog's Adams-Williamson EOS (_MeshParameters.adiabatic_bulk_modulus). SPIDER derives its own.

melt_log10visc = field(default=2.0) class-attribute instance-attribute

log10 viscosity of molten silicate [Pa s]. Matches SPIDER -melt_log10visc (2.0 = 1e2 Pa s).

solid_log10visc = field(default=22.0) class-attribute instance-attribute

log10 viscosity of solid silicate [Pa s]. Matches SPIDER -solid_log10visc (22.0 = 1e22 Pa s). Shared by SPIDER and Aragog so both apply the same solid-phase rheology; a mis-set value diverges both solvers' solid-phase rheology by the same factor.

melt_cond = field(default=4.0, validator=(gt(0))) class-attribute instance-attribute

Thermal conductivity of molten silicate [W/m/K]. Matches SPIDER -melt_cond.

solid_cond = field(default=4.0, validator=(gt(0))) class-attribute instance-attribute

Thermal conductivity of solid silicate [W/m/K]. Matches SPIDER -solid_cond.

eddy_diffusivity_thermal = field(default=1.0) class-attribute instance-attribute

Multiplier on the internally-computed thermal eddy diffusivity. SPIDER: -eddy_diffusivity_thermal (1.0 default).

eddy_diffusivity_chemical = field(default=1.0) class-attribute instance-attribute

Multiplier on the internally-computed chemical eddy diffusivity. SPIDER: -eddy_diffusivity_chemical (1.0 default).

const_rho = field(default=4000.0, validator=(gt(0))) class-attribute instance-attribute

Constant density [kg/m3].

const_Cp = field(default=1000.0, validator=(gt(0))) class-attribute instance-attribute

Constant heat capacity [J/kg/K].

const_alpha = field(default=1e-05, validator=(gt(0))) class-attribute instance-attribute

Constant thermal expansivity [1/K].

const_cond = field(default=4.0, validator=(gt(0))) class-attribute instance-attribute

Constant thermal conductivity [W/m/K].

const_log10visc = field(default=2.0) class-attribute instance-attribute

Constant log10 dynamic viscosity [Pa.s].

const_T_ref = field(default=3500.0, validator=(gt(0))) class-attribute instance-attribute

Reference temperature for T(S) = T_ref * exp((S-S_ref)/Cp) [K].

const_S_ref = field(default=3000.0) class-attribute instance-attribute

Reference entropy for T(S) [J/kg/K]. No positivity constraint since entropy reference states can be zero or negative.

latent_heat_of_fusion = field(default=4000000.0, validator=(gt(0))) class-attribute instance-attribute

Latent heat of fusion of silicate [J/kg]. Aragog uses this as a scalar in _PhaseMixedParameters. SPIDER derives it per-(P,S) from dS * T_fus via the EOS tables; the SPIDER derivation is more physically correct but this scalar is good to ~10% at Earth-mantle conditions. TODO: switch Aragog to SPIDER's derivation once the EntropyEOS exposes a dS_fus(P) method.

phase_transition_width = field(default=0.1, validator=(gt(0), lt(1))) class-attribute instance-attribute

Width [fraction] of the mushy-zone transition in Aragog's _PhaseMixedParameters. Sets the width of the phase boundary in Aragog's mixed-phase blending (viscosity, thermal conductivity etc.). Distinct from [interior_energetics.spider].matprop_smooth_width which is SPIDER's analogous knob for its own solver.

core_tfac_avg = field(default=1.147, validator=(gt(0))) class-attribute instance-attribute

Core T_avg / T_cmb ratio from adiabatic gradient (Bower+2018 Table 2). Used by Aragog's _BoundaryConditionsParameters.tfac_core_avg. SPIDER derives its own internally.

write_flux_diagnostics = field(default=False) class-attribute instance-attribute

When True, Aragog's NetCDF output includes per-component flux decomposition (Jcond_b, Jconv_b, Jgrav_b, Jmix_b) and basic-node state variables (dSdr_b, eddy_diff_b, phi_basic_b, T/cp/rho_basic_b). Adds ~10 fields per snapshot; default False keeps output compact. Useful for diagnosing T_core and CMB-closure behaviour near phi=0. SPIDER path ignores this flag (uses SPIDER's own JSON output which already includes Jcond_b, Jconv_b, Jgrav_b, Jmix_b).

valid_interiorboundary(instance, attribute, value)

Validate Boundary backend's solidus/liquidus ordering.

Only fires when module == 'boundary'; otherwise the subclass is constructed with defaults and never exercised.

Source code in src/proteus/config/_interior.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
def valid_interiorboundary(instance, attribute, value):
    """Validate Boundary backend's solidus/liquidus ordering.

    Only fires when ``module == 'boundary'``; otherwise the subclass is
    constructed with defaults and never exercised.
    """
    if instance.module != 'boundary':
        return

    tsol = instance.boundary.T_solidus
    tliq = instance.boundary.T_liquidus
    if tliq <= tsol:
        raise ValueError(f'Boundary liquidus ({tliq}K) must be greater than solidus ({tsol}K)')

Atmosphere climate

Agni

AGNI atmosphere module (AGNI-specific parameters only).

Grid, spectral, and pressure parameters are shared with JANUS and live on the parent AtmosClim class.

Attributes:

Name Type Description
verbosity int

Logging and output verbosity for agni (0:none, 1:info, 2:debug).
surf_material str

Surface scattering material file. Set to 'greybody' to use surf_greyalbedo.
chemistry str | None

Atmospheric chemistry treatment. Choices: 'none', 'eq' (FastChem).
solve_energy bool

Solve for an energy-conserving atmosphere solution.
solution_atol float

Absolute tolerance on the atmosphere solution [W/m2].
solution_rtol float

Relative tolerance on the atmosphere solution.
surf_roughness float

Characteristic surface roughness scale [metres].
surf_windspeed float

Characteristic surface wind speed [m/s].
phs_timescale float

Relaxation timescale for phase changes (condensation/evaporation) [seconds].
evap_efficiency float

Efficiency of raindrop re-evaporation (0 to 1).
rainout bool

Enable volatile condensation and evaporation in the atmosphere.
oceans bool

Enable volatile ocean formation at the surface.
latent_heat bool

Account for latent heat from condense/evap when solving temperature profile. Requires condensation=true.
convection bool

Account for convective heat transport, using MLT.
conduction bool

Account for conductive heat transport, using Fourier's law.
sens_heat bool

Include sensible heat flux at surface
real_gas bool

Use real gas equations of state in atmosphere, where possible.
psurf_thresh float

Use the transparent-atmosphere solver when P_surf is less than this value [bar].
dx_max float

Nominal maximum step size to T(p) during the solver process, although this is dynamic.
dx_max_ini float

Initial maximum step size to T(p) when AGNI is called in the first few PROTEUS loops.
max_steps int

Maximum number of iterations before giving up.
perturb_all bool

Recalculate entire jacobian matrix at every iteration?
mlt_criterion str

Convection criterion. Options: (l)edoux, (s)chwarzschild.
fastchem_floor float

Minimum temperature allowed to be sent to FC
fastchem_maxiter_chem int

Maximum FC iterations (chemistry)
fastchem_maxiter_solv int

Maximum FC iterations (internal solver)
fastchem_xtol_chem float

FC solver tolerance (chemistry)
fastchem_xtol_elem float

FC solver tolerance (elemental)
ini_profile str

Shape of initial T(p) guess: 'loglinear', 'isothermal', 'dry_adiabat', 'analytic'.
ls_default int

Default linesearch method. 0: disabled, 1: goldensection, 2: backtracking.
fdo int

Numerical order of finite-difference for jacobian. 2 or 4.
spectral_file str | None

Path to AGNI spectral file, or 'greygas' to enable the grey-gas RT scheme. If None, will use atmos_clim.spectral_group and atmos_clim.spectral_bands.
grey_opacity_lw float

Grey longwave opacity [m2 kg-1], used when spectral_file='greygas'.
grey_opacity_sw float

Grey shortwave opacity [m2 kg-1], used when spectral_file='greygas'.

Janus

JANUS atmosphere module (JANUS-specific parameters only).

Grid, spectral, and pressure parameters are shared with AGNI and live on the parent AtmosClim class.

Attributes:

Name Type Description
F_atm_bc int

Outgoing flux boundary: 0 (TOA) or 1 (surface).
tropopause str | None

Tropopause scheme. Choices: 'none', 'skin', 'dynamic'.
cloud_alpha float

Condensate retention fraction (0 = full rainout, 1 = fully retained).
tmp_maximum float

Solver temperature ceiling [K].

Dummy

Dummy atmosphere module.

A parametrised model of the atmosphere designed for debugging. The greenhouse effect is captured by gamma which produces a transparent atmosphere when 0, and a completely opaque atmosphere when 1. The height of the atmosphere equals the scale height times the height_factor variable.

When fixed_flux is set to a positive value, the dummy module bypasses the grey-body calculation entirely and returns that constant flux as F_atm at every coupling step. This is useful for controlled parity comparisons between interior solvers where the surface BC must be identical.

Attributes:

Name Type Description
gamma float

Atmosphere opacity factor between 0 and 1.
height_factor float

A multiplying factor applied to the ideal-gas scale height.
fixed_flux float

If > 0, return this constant flux [W/m2] instead of computing it. Default -1 (disabled, use the grey-body calculation).

AtmosClim

Atmosphere parameters, model selection.

Attributes:

Name Type Description
module str

Which atmosphere module to use. Choices: 'agni', 'janus', 'dummy'.
spectral_group str

Spectral file group defining gas opacities. See https://proteus-framework.org/SOCRATES/Reference/proteus_spectral_file_reference.html
spectral_bands str

Number of wavenumber bands in k-table.
num_levels int

Number of vertical atmosphere levels.
p_top float

Top-of-atmosphere pressure [bar].
p_obs float

Observation pressure level [bar] (transit radius).
overlap_method str

Gas overlap method. Choices: 'ro', 'rorr', 'ee'.
surface_d float

Conductive skin thickness [m].
surface_k float

Conductive skin thermal conductivity [W m-1 K-1].
aerosols_enabled bool

Enable aerosol radiative effects.
cloud_enabled bool

Enable water cloud radiative effects (AGNI, JANUS only).
surf_state str

Surface energy balance scheme. Choices: 'mixed_layer', 'fixed', 'skin'.
surf_greyalbedo float

Grey surface albedo.
albedo_pl float | str

Planetary bond albedo. Can be float (0 to 1) or str (path to CSV lookup).
rayleigh bool

Include Rayleigh scattering (AGNI, JANUS only).
tmp_minimum float

Minimum temperature throughout the atmosphere [K] (AGNI, JANUS only).
agni Agni

Config parameters for AGNI atmosphere module.
janus Janus

Config parameters for JANUS atmosphere module.
dummy Dummy

Config parameters for dummy atmosphere module.

surf_state_int property

Return integer surface boundary condition for agni.

albedo_from_file property

Is albedo set by lookup table or not?

valid_aerosols_enabled(instance, attribute, value)

Aerosol scattering needs band-resolved RT.

Reuses the dummy guard from warn_if_dummy and rejects the AGNI grey-gas combination: grey gas has no spectral bands, so a Mie-scattering aerosol library is either silently ignored or crashes on the Julia side. The check fires only when aerosols are enabled (value is True).

Source code in src/proteus/config/_atmos_clim.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def valid_aerosols_enabled(instance, attribute, value):
    """Aerosol scattering needs band-resolved RT.

    Reuses the dummy guard from ``warn_if_dummy`` and rejects the
    AGNI grey-gas combination: grey gas has no spectral bands, so a
    Mie-scattering aerosol library is either silently ignored or
    crashes on the Julia side. The check fires only when aerosols
    are enabled (``value is True``).
    """
    if not value:
        return

    if instance.module == 'dummy':
        raise ValueError(f'Dummy atmos_clim module is incompatible with {attribute.name}=True')

    if instance.module == 'agni' and (str(instance.agni.spectral_file).lower() == 'greygas'):
        raise ValueError(
            'AGNI grey gas is incompatible with aerosols (band-resolved Mie '
            'scattering requires a real spectral file)'
        )

Atmospheric escape

Zephyrus

Parameters for Zephyrus module.

Attributes:

Name Type Description
Pxuv float

Pressure at which XUV radiation become opaque in the planetary atmosphere [bar]
efficiency float

Escape efficiency factor
tidal bool

Tidal contribution enabled

EscapeDummy

Dummy module.

Attributes:

Name Type Description
rate float

Bulk unfractionated escape rate [kg s-1]

EscapeBoreas

BOREAS escape module.

Attributes:

Name Type Description
fractionate bool

Enable elemental fractionation in outflow?
efficiency float

Energy efficiency factor.
sigma_H float

Absorption cross-section of H in XUV [cm2]
sigma_O float

Absorption cross-section of O in XUV [cm2]
sigma_C float

Absorption cross-section of C in XUV [cm2]
sigma_N float

Absorption cross-section of N in XUV [cm2]
sigma_S float

Absorption cross-section of S in XUV [cm2]
kappa_H2O float

Grey H2O opacity in IR [cm2 g-1]
kappa_H2 float

Grey H2 opacity in IR [cm2 g-1]
kappa_O2 float

Grey O2 opacity in IR [cm2 g-1]
kappa_CO2 float

Grey CO2 opacity in IR [cm2 g-1]
kappa_CO float

Grey CO opacity in IR [cm2 g-1]
kappa_CH4 float

Grey CH4 opacity in IR [cm2 g-1]
kappa_N2 float

Grey N2 opacity in IR [cm2 g-1]
kappa_NH3 float

Grey NH3 opacity in IR [cm2 g-1]
kappa_H2S float

Grey H2S opacity in IR [cm2 g-1]
kappa_SO2 float

Grey SO2 opacity in IR [cm2 g-1]
kappa_S2 float

Grey S2 opacity in IR [cm2 g-1]

Escape

Escape parameters and module selection.

Attributes:

Name Type Description
reservoir str

Escaping composition when not doing fractionation. Choices: bulk, outgas, pxuv.
module str | None

Escape module to use. Choices: None, "dummy", "zephyrus", "boreas".
zephyrus Zephyrus

Parameters for zephyrus module.
dummy EscapeDummy

Parameters for dummy escape module.
boreas EscapeBoreas

Parameters for BOREAS escape module.

xuv_defined_by_radius property

Does Rxuv define the escape level?

If the escape level is defined by constant Pxuv, then return False. This depends on the escape module used. BOREAS calculates both Pxuv and Rxuv, while the default assumes that Pxuv is constant, which is used to find Rxuv from the r(p) profile.

Atmospheric chemistry

Vulcan

VULCAN chemistry module.

Attributes:

Name Type Description
clip_fl float

Stellar flux floor [ergs cm-2 s-1 nm-1].
clip_vmr float

Neglect species with surface VMR < clip_vmr.
make_funs bool

Make functions from chemical network.
ini_mix str

Initial mixing ratios. Options: profile, outgas.
fix_surf bool

Fix the surface mixing ratios based on outgassed composition.
network str

Chemical network. Options: CHO, NCHO, SNCHO.
save_frames bool

Save simulation state as plots.
yconv_cri float

Steady state - max change in mixing ratio over test period
slope_cri float

Steady state - max rate of change of mixing ratio over test period

AtmosChem

Atmosphere chemistry parameters, model selection.

Attributes:

Name Type Description
module str

Chemistry module
vulcan Vulcan

VULCAN module options
when str

When to run the chemistry module. Options: manually, offline, online.
photo_on bool

Use photochemistry.
Kzz_on bool

Use Kzz.
Kzz_const float

Constant Kzz value [cm2/s]. If 'none', Kzz is read from NetCDF file.
moldiff_on bool

Use molecular diffusion.
updraft_const float

Updraft velocity [cm/s].

Volatile outgassing

Calliope

Module parameters for Calliope.

Attributes:

Name Type Description
include_H2O bool

If True, include H2O.
include_CO2 bool

If True, include CO2.
include_N2 bool

If True, include N2.
include_S2 bool

If True, include S2.
include_SO2 bool

If True, include SO2.
include_H2S bool

If True, include H2S.
include_NH3 bool

If True, include NH3.
include_H2 bool

If True, include H2.
include_CH4 bool

If True, include CH4.
include_CO bool

If True, include CO.
solubility bool

Enable solubility of volatiles into melt.
nguess int

Maximum number of initial-guess samples for the CALLIOPE equilibrium solver. Default 1000.
nsolve int

Maximum number of iterations of the CALLIOPE equilibrium solver per call. Default 3000.
p_guess_max float

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.

is_included(vol)

Helper method for getting flag if vol is included in outgassing.

Source code in src/proteus/config/_outgas.py 
89
90
91
def is_included(self, vol: str) -> bool:
    """Helper method for getting flag if `vol` is included in outgassing."""
    return getattr(self, f'include_{vol}')

Atmodeller

Module parameters for Atmodeller (Bower+2025, ApJ 995:59).

JAX-based volatile partitioning with real gas EOS, non-ideal solubility laws, and condensation. Replaces CALLIOPE for thermodynamically consistent magma-atmosphere equilibrium.

Attributes:

Name Type Description
solver_mode str

Root-finding mode: 'robust' (slower compile, better convergence) or 'basic' (faster compile, less robust).
solver_max_steps int

Maximum iterations for the root-finder.
solver_multistart int

Number of random restarts for the root-finder.
include_condensates bool

Enable condensate phases (graphite, etc.) in the equilibrium.
solubility_H2O str

Solubility law for H2O. See atmodeller.solubility.library.
solubility_CO2 str

Solubility law for CO2.
solubility_H2 str

Solubility law for H2.
solubility_N2 str

Solubility law for N2.
solubility_S2 str

Solubility law for S2.
solubility_CO str

Solubility law for CO. 'none' = no solubility.
solubility_CH4 str

Solubility law for CH4. 'none' = no solubility.
eos_H2O str

Real gas EOS for H2O. 'none' = ideal gas.
eos_CO2 str

Real gas EOS for CO2. 'none' = ideal gas.
eos_H2 str

Real gas EOS for H2. 'none' = ideal gas.
eos_CH4 str

Real gas EOS for CH4. 'none' = ideal gas.
eos_CO str

Real gas EOS for CO. 'none' = ideal gas.

Outgas

Outgassing parameters (fO2) and included volatiles.

Attributes:

Name Type Description
module str

Outgassing module to be used. Choices: 'calliope', 'atmodeller', 'dummy'.
fO2_shift_IW float

Oxygen fugacity relative to Iron-Wustite [log10 units].
mass_thresh float

Minimum threshold for element mass [kg]. Inventories below this are set to zero.
h2_binodal bool

Enable binodal-controlled H2 partitioning between atmosphere and magma ocean using the Rogers+2025 H2-MgSiO3 miscibility model.
T_floor float

Temperature floor [K]. The outgassing temperature is clamped to this value from below before the chemistry solve.
solver_rtol float

Relative tolerance for the volatile equilibrium solver.
solver_atol float

Absolute tolerance for the volatile equilibrium solver.
calliope Calliope

Parameters for CALLIOPE module.
atmodeller Atmodeller

Parameters for atmodeller module.

Elemental delivery and accretion

Accretion

Late accretion / delivery model selection.

Attributes:

Name Type Description
module str or None

Accretion module to use. Currently only None is supported.

Synthetic observations

PetitRADTRANS

Parameters for the petitRADTRANS module.

Attributes:

Name Type Description
line_opacity_mode str

Opacity treatment: 'c-k' (correlated-k) or 'lbl' (line-by-line).
include_rayleigh bool

Include Rayleigh scattering contributions.
include_cia bool

Include collision-induced absorption contributions.
silent bool

Suppress petitRADTRANS stdout/stderr during Radtrans initialization.
Note

Input data is discovered at runtime from dirs['fwl']/prt/input_data, where dirs['fwl'] is populated from the FWL_DATA environment variable during PROTEUS startup.

Observe

Synthetic observations.

module: str Module to use for calculating synthetic spectra. clip_vmr: float Minimum VMR to include a species in radiative transfer. reference_pressure: float Reference pressure for synthetic spectrum generation [bar]. source: str Composition source selection: 'all', 'outgas', 'profile', or 'offchem'. spectrum_type: str Synthetic spectrum products to compute: 'both', 'transit', or 'eclipse'. remove_one_gas: bool If True, generate additional leave-one-out spectra with each gas removed.

For developers: adding a new parameter

So, you are developing a new model and want to add some parameters? Follow these steps:

  1. Decide on a good parameter name (e.g. my_star_var), and under which section to place it (e.g. star). Add the new variable to the config submodule.
  2. Add the type for your variable, e.g. float, int, str. You can also add complex types, please check the code for inspiration.
  3. Add a validator! If your variable has a maximum value (e.g. 10), you can add a validator to make sure that any values above 10 are rejected: my_star_var: float = field(validator=attrs.validators.le(10))
  4. Add a description for your new variable under Attributes in the docstring. The documentation uses the description to generate this documentation.
  5. Update the example input configs. Proteus checks tests all input configs in this directory are valid.
  6. Use your parameter in your code, i.e.: config.star.my_star_var
src/proteus/config/_star.py
class Star:
    """Stellar parameters.

    Attributes
    ----------
    my_star_var: float
        Star variable, must be 10 or lower!
    """
    my_star_var: float = field(validator=attrs.validators.le(10))

Proteus uses attrs for its parameter handling. Please see the examples for more information how to work with attrs.