Skip to content

Execution and output

The [params] section controls code execution, output settings, time-stepping, and termination criteria. These parameters govern how the simulation runs, not what it simulates.

See also: Coupling loop for how time-stepping and convergence work in practice.

File format

Every config file declares the schema version it is written against.

Parameter Type Default Description
config_version str "3.0" Version of the configuration file format.

General [params]

Parameter Type Default Description
resume bool false Resume the simulation from the last archived state in the output folder, instead of starting from scratch.
offline bool false Run without network access; never download reference data, and fail if a required file is missing locally.

Output settings [params.out]

Parameter Type Default Description
path str "auto" 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 "INFO" Log verbosity. Choices: "INFO", "DEBUG", "ERROR", "WARNING".
plot_fmt str "png" Plotting output file format. Choices: "pdf", "png".
write_mod int 1 Write data iteration-interval trigger. 0: wait until completion. n: every n iterations. Must be >= 0.
dt_write_rel float 0.0 Write data time-interval trigger. Expressed as a fraction of the current simulation time. Set to 0 to disable. Must be >= 0.
plot_mod int or none 5 Plotting frequency. 0: wait until completion. n: every n iterations. None: never plot.
archive_mod int or none none Archive frequency. 0: wait until completion. n: every n iterations. None: never archive.
remove_sf bool false Remove SOCRATES spectral files after model terminates.

Time-stepping [params.dt]

PROTEUS supports three time-stepping methods. The adaptive method is recommended for production runs; proportional is useful for steady-state problems; maximum gives a fixed step. The atol/rtol/scale_*/window parameters apply to the adaptive method, propconst to the proportional method, and the mushy_*/hysteresis_* parameters cap the step during the solidification transition (melt fraction between phi_crit and mushy_upper) so the rapid phase change stays resolved.

Parameter Type Default Description
starspec float 100000000.0 Maximum interval at which to recalculate the stellar spectrum [yr]. Must be >= 0.
starinst float 100.0 Maximum interval at which to recalculate instellation flux [yr]. Must be >= 0.
method str "adaptive" Time-stepping method. Choices: "proportional", "adaptive", "maximum".
propconst float 52.0 Proportionality constant (proportional method). Must be > 0.
atol float 0.02 Absolute tolerance on time-step size (adaptive method) [yr]. Must be > 0.
rtol float 0.1 Relative tolerance on time-step size (adaptive method) [dimensionless]. Must be > 0.
scale_incr float 1.6 Scale factor to grow time-step on a successful adaptive step [dimensionless, must be >1]. Must be > 1.
scale_decr float 0.8 Scale factor to shrink time-step on a rejected adaptive step [dimensionless, in (0, 1)]. Must be > 0 and < 1.
window int 3 Number of previous steps to consider for adaptive-method comparison [dimensionless]. Must be >= 1.
minimum float 100.0 Minimum absolute time-step size [yr]; escape and the drain cap stop at minimum * escape.step_dt_floor_frac, and other caps, among them growth, evection, bolometric clamp, the final-time cap, solver retries, mushy-zone limiting, and impact landing steps, can go lower. Must be > 0.
minimum_rel float 1e-05 Minimum relative time-step size [dimensionless]. Must be > 0.
maximum float 10000000.0 Maximum time-step size [yr]. Must be > 0.
maximum_rel float 1.0 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. Must be >= 0.
initial float 30.0 Initial time-step size [yr]. Must be > 0.
mushy_maximum float 0.0 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. Must be >= 0.
mushy_upper float 0.99 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. Must be > 0 and < 1.
evection_maximum float or none none Ceiling on the time-step size [yr] while the planet-satellite system is inside, or approaching, the evection resonance band. Must be > 0 when set. Default 'none' (disables the whole mechanism). Must be > 0.
evection_target_rel_de float 0.05 Target maximum fractional change in eccentricity_sat per macro-step while inside/approaching the evection band. Obliqua's own adaptive mode-window selection is keyed on the eccentricity it is given at call time, and that window is then held fixed for the whole of the following macro-step, so a large fractional swing in e within one step risks needing modes outside that window. Default 0.05 (5%). Must be > 0.
evection_de_floor float 0.02 Floor on the eccentricity value used in the evection_target_rel_de ratio's denominator, so a tiny eccentricity right at capture onset does not make the allowed step blow up. Default 0.02. Must be > 0.
evection_rate_window int 2 Number of trailing accepted macro-steps used to estimate the SECULAR |de/dt| this cap bounds against (a least-squares linear fit for windows > 2, the plain two-point difference at the default of 2). Default 2, preserves the two-point behaviour. Must be >= 2.
evection_growth_factor float or none none Cap on the dt growth ratio between consecutive steps while the system is inside/approaching the evection band, or within evection_cooldown_iters steps of having left it. Separate from the global max_growth_factor (which most evection runs leave disabled, since it would also throttle ordinary bulk evolution for the rest of the run). Must be > 0 when set. Default 'none' (disabled). Must be > 0.
evection_cooldown_iters int or none none Number of PROTEUS iterations, after the system is no longer judged in/near the evection band, during which evection_growth_factor remains active. Refreshed to this value on every iteration the zone is active, so a long stay in the band does not exhaust it before exit. Must be > 0 when set. Default 'none' (no cooldown tail; growth limiting turns off the instant the zone is left). Must be > 0.
hysteresis_iters int 0 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. Must be >= 0.
hysteresis_sfinc float 1.1 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). Must be >= 1.0.
impact_maximum float 0.0 Ceiling [yr] for the step that reaches a scheduled giant impact. Such a step is otherwise clamped only to the time left before the impact, which after a long quiescent phase can itself be large. With the ceiling set, a reaching step longer than max(impact_maximum, dtfloor) (dtfloor = dt.minimum + dt.minimum_rel * Time) is cut to an equal fraction of the time left; later steps are evaluated again, and the step that lands is no longer than max(impact_maximum, dtfloor). Set to 0 (default) to disable. Independent of this setting, the step that lands on an impact can be shorter than dtfloor, a step ending at most 1e-3 yr short of an impact is extended onto it (unless the step already reaches stop.time.maximum), and an impact is applied at the end of the first step that reaches its time. Impacts each less than 1e-3 yr after the one before form a chain that the step aims at the last of, so an impact in a chain can be applied later than its time by up to the chain span; a chain spanning 1e-3 yr or more is logged as a warning. Must be >= 0.
max_growth_factor float 0.0 Cap on the dt growth ratio between consecutive steps [dimensionless]. Bounds dtswitch / dtprev, preventing large jumps that can wedge the interior solver; 0 (default) disables the cap. After a step that landed on a giant impact, dtprev is the larger of that step and min(dtfloor, last step that did not land on an impact), or dtfloor when there is no such step. Must be >= 0.

Termination criteria [params.stop]

Each criterion can be independently enabled. The simulation terminates when any enabled criterion is satisfied. Set strict = true to require the criterion to be satisfied for two consecutive iterations before terminating.

Parameter Type Default Description
strict bool false Require termination criteria to be satisfied twice before the model exits.

Iteration limits [params.stop.iters]

Parameter Type Default Description
enabled bool true Enable criteria if True.
minimum int 5 Minimum number of iterations. Must be >= 0.
maximum int 9000 Maximum number of iterations.

Time limits [params.stop.time]

Parameter Type Default Description
enabled bool true Enable criteria if True.
maximum float 6000000000.0 Model will terminate when this time is reached [yr].
minimum float 1000.0 Model will absolutely not terminate until at least this time is reached [yr]. Must be >= 0.

Solidification [params.stop.solid]

Parameter Type Default Description
phi_crit float 0.01 Model will terminate (if enabled) or freeze volatiles (if freeze_volatiles) when global melt fraction drops below this value. Must be > 0 and < 1.
enabled bool true Enable termination at solidification if True.
freeze_volatiles bool false 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.

Radiative equilibrium [params.stop.radeqm]

Parameter Type Default Description
enabled bool true Enable criteria if True.
atol float 1.0 Absolute tolerance on energy balance [W m-2]. Must be > 0.
rtol float 0.001 Relative tolerance on energy balance. Must be >= 0.

Atmosphere escape [params.stop.escape]

Parameter Type Default Description
enabled bool true Enable criteria if True.
p_stop float 3.0 Model will terminate when surface pressure is less than this value [bar]. Must be > 0 and < 1000000.0.

Planetary disintegration [params.stop.disint]

Parameter Type Default Description
enabled bool false Enable all planet disintegration criteria if True.
roche_enabled bool true Disable Roche limit criterion.
offset_roche float 0 Absolute correction (+/-) to (increase/decrease) calculated Roche limit [m].
spin_enabled bool true Disable Breakup period criterion.
offset_spin float 0 Absolute correction (+/-) to (increase/decrease) calculated Breakup period [s].

Satellite disintegration [params.stop.disint_sat]

Parameter Type Default Description
enabled bool false Enable all planet disintegration criteria if True.
roche_enabled bool true Disable Roche limit criterion.
offset_roche float 0 Absolute correction (+/-) to (increase/decrease) calculated Roche limit [m].
spin_enabled bool true Disable Breakup period criterion.
offset_spin float 0 Absolute correction (+/-) to (increase/decrease) calculated Breakup period [s].

Satellite escape [params.stop.satellite]

Parameter Type Default Description
enabled bool false Enable criteria if True.
sma_max float 60 Maximum semi-major axis for the satellite [R_Earth].

Wall-clock limit [params.stop.clock]

Parameter Type Default Description
enabled bool true Enable criteria if True.
maximum float 604800 Model will terminate when runtime exceeds this value [s]. Must be > 0.

Unconverged atmosphere [params.stop.stall]

Parameter Type Default Description
enabled bool true Enable criteria if True.
maximum int 150 Model will terminate after this many consecutive iterations without a converged atmosphere solve, whatever the interior is doing. Sized on 27 stalled GJ 9827 d cases as they stood on 2026-08-08: the deepest streak a run recovered from is 126 and the deepest open one, which never converged, is 233. Raising it past the open streak defeats the criterion; lowering it below the recovered one ends runs that come back. Must be > 0.

Constraints

Cross-field constraints enforced when the config file loads:

  • Reject accretion runs with a stratified Aragog core_module core.
  • Reject accretion runs on an interior that cannot apply an impact.
  • Reject accretion.remelt = 'computed' without a module that reports a melt fraction.
  • Reject accretion runs that also vapourise rock into the atmosphere.
  • Reject an Aragog core_module core that its structure or solver cannot serve.
  • Check that required external packages are importable for the selected modules.
  • The maximum must exceed the minimum on the same section.
  • Reject giant impacts with the parameterized star-planet model.