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 10000.0 Minimum absolute time-step size [yr]. 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.
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.
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. 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].

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:

  • Check that required external packages are importable for the selected modules.
  • The maximum must exceed the minimum on the same section.