4 Configuration reference

Modified

October 24, 2026

4.1 Configuration layers

The supported entry point is scripts/run_pmf.jl CONFIG.toml --output=RUN_DIR. The facade validates TOML tables, applies safe wrapper defaults, resolves named keys to MHD_* options, sets output paths, and finally applies [environment] overrides. The child process does not inherit unrelated shell MHD_* variables. Read resolved-environment.toml, not just your input file, when reviewing a run. ^{function run_environment}

--backend=cpu|metal|cuda overrides the named run.backend; use the matching active project. A conflicting low-level [environment] MHD_BACKEND override comes later, so avoid expressing the same choice in both places.

Unknown sections, named options, and unrecognized low-level option names are errors. Validation is not a science certification and does not replace review of units, mode support, or the runner’s additional runtime checks.

4.2 Shipped experiments

File	Purpose	Boundary
`examples/smoke.toml`	`16^3`, four-step MHD plus lattice gravity	Noncosmological, chemistry off
`examples/cosmology-smoke.toml`	Small full-physics installation check	Very short redshift interval, not converged
`examples/pmf-recombination.toml`	Editable recombination research setup	Requires the validation matrix; not a certified production prescription
`examples/convergence-suite.toml`	Serialized grid/timestep cases sharing a base config	Case definition, not measured certification

4.3 Named tables

These keys map to the public environment interface. The authoritative mapping and validation are in CONFIG_KEYS. ^CONFIG_KEYS

Table	Common keys	Meaning
`[run]`	`n`, `backend`, `precision`, `steps`, `max_cycles`, `cfl`	Grid, device, numerical budget; `cfl` must be in `(0, 0.25]` for GLM and `(0, 0.30]` for CT (measured limit)
`[run]`	`reconstruction`, `riemann`, `print_every`, `check_every`	Scheme and log/health cadence
`[run]`	`checkpoint_every`, `checkpoint_final`, `resume`	Checkpoint write/resume policy
`[run]`	`mhd_solver`	Divergence treatment: `"glm"` (default) or `"ct"` (constrained transport)
`[cosmology]`	`zstart`, `zend`, `h`, `omega_m`, `omega_b`, `omega_lambda`, `omega_r`	Expansion history
`[cosmology]`	`box_ckpc_h`, `max_dln_a`	Physical comoving box in ckpc/h, expansion step cap
`[magnetic]`	`initial_condition`, `b0_ng`, `brms_code`, `seed`	IC family, comoving nG or code amplitude
`[magnetic]`	`kmin`, `kcut`, `kmax`, `mode_lock_n`, `curl_symbol`, `curl_reference_n`	Band, discrete operator, shared modes
`[magnetic]`	`normalization`, `reference_kmax`, `reference_kcut`, `minimum_cells_per_wavelength`	Explicit amplitude band and resolution requirement
`[magnetic]`	`fixed_mode_power`, `mode_realization`, `realization_box`	Gaussian/fixed realization and physical hashing
`[chemistry]`	`mode`, `helium`, `coupling`, `expansion`	Network and operator split
`[chemistry]`	`smoothing`, `smoothing_sigma_cells`, `dt_fraction`, `hydrogen_storage`	Mixing approximation and integration controls
`[chemistry]`	`ionized_fast_zmin`, `velocity_unit_cms`, `x_hii_initial`, `x_h2_initial`, `nonlocal_table`	Ionized shortcut, physical conversion, initial abundances, table input
`[physics]`	`gravity`, `gas_gravity`, `compton_drag`, `drag_mode`, `photon_response`	Coupled physical model
`[physics]`	`fft`, `pressure`, `scaling`, `photon_max_dln_a`, `nonlinear_cfl`	Transforms, thermal normalization, clocks, response caps
`[physics]`	`glm_project_every`, `glm_ch_factor`, `particle_max_displacement_cells`	Divergence projection and trajectory controls
`[diagnostics]`	`redshifts`, `every`, `adaptive_fraction`	Requested outputs and adaptive histories
`[diagnostics]`	`spectrum_bins`, `angle_bins`, `pdf_bins`, `energy_ledger_every`	Estimator resolution and energy sampling

n must be even and at least 8. The facade requires finite zstart > zend >= 0, a positive physical box, and a positive comoving b0_ng for cosmological configs. Some transform paths impose additional size/factorization restrictions.

4.4 Selecting the MHD solver

run.mhd_solver = "glm" | "ct" (environment MHD_SOLVER) selects how \nabla\cdot\mathbf B is controlled. "glm" is the default and the research baseline; leaving the key out gives exactly the previous behavior. "ct" selects the face-staggered constrained-transport scheme of the physics chapter, for example examples/cosmology-smoke-ct.toml as the counterpart of examples/cosmology-smoke.toml. The choice is recorded in metadata.toml (mhd_solver, plus ct_initial_* numbers for CT), in the CONFIG log line, in performance.tsv (mhd_solver), and in the checkpoint fingerprint.

For CT the facade changes these defaults and rejects options that cannot work, before any state is allocated (both in the TOML validation and again in the driver):

Option	With `mhd_solver = "ct"`
`MHD_INTEGRATOR`	Default `ref` on every backend; an explicit `cube` is an error
`physics.drag_mode`	`terminal` and `hybrid` are supported (face-staggered terminal induction, still `MHD_ALLOW_UNCERTIFIED_TERMINAL=1`). Errors: `MHD_TERMINAL_INDUCTION=ssprk2`, and `MHD_TERMINAL_PRESSURE_IMPLICIT=1` with an induction other than `ct` (cell-centred B writers)
`physics.glm_project_every`	Default `0` (GLM radiation runs default to projecting every cycle); a value above zero is an error
`physics.glm_ch_factor`, `MHD_GLM_CR`	The explicit step is not limited by the GLM speed `ch`; `dt` is the plain CFL step. `glm_ch_factor` only scales the radiation positivity wave-speed limit (next rows); `MHD_GLM_CR` is unused
`backend`	CPU and Metal; CUDA is not run
`MHD_RADIATION_MAGNETIC_COMPENSATION`	`1` also makes the radiation-coupled steps sum the CT face updates with Kahan compensation (GLM: cell `B`); the face remainders are checkpointed as `ct_residual_1..3`. Use it for strong-guide-field, Float32 cases (the native-mode case sets it)
`MHD_RADIATION_POSITIVITY_*`, `MHD_RADIATION_CHECKPOINT_FALLBACK`	Honoured for CT as for GLM `cube` (trial check, restore, minmod-PLM/HLL retry, subdivision, checkpoint error), at the cost of 6 extra `N^3` face-snapshot arrays. `MHD_RADIATION_POSITIVITY_WAVE_GROWTH_LIMIT` is multiplied by `MHD_GLM_CH_FAC` for CT (so the absolute limit equals GLM’s); GLM `ref` has no such protection
Checkpoints	A checkpoint without an `mhd_solver` key is a GLM checkpoint. GLM and CT checkpoints cannot be resumed as one another; CT checkpoints store the face fields (and, with compensation, the face remainders)

Consequently a CT and a GLM run at equal cfl do not take identical steps whenever the CFL step, rather than a cosmological or source cap, is the limit. See comparing CT and GLM runs.

4.5 Defaults are context-dependent

The facade’s short-run defaults differ intentionally from invoking the extracted runner directly:

Choice	Facade behavior
Device / precision	CPU / Float32 unless specified
Grid / fixed-time budget	`n=16`, four steps, `cfl=0.2`
Warmup	Zero, including cosmological runs
Restart / final checkpoint	Disabled unless requested
FFT	`auto`, selected per backend
Cosmological pressure / magnetic clock	`pressure="auto"`, `scaling="jedamzik"`
Cosmological drag / photons	Full-MHD radiation, `moments_exponential`
Cosmological chemistry	Full mixing with helium, centered H storage, expansion on, Strang half-steps
Ionized shortcut	Off: `MHD_CHEM_IONIZED_FAST_ZMIN=0`
Gaussian smoothing	Eight cells unless configured
Nonlinear response CFL	`0.1` for cosmological facade defaults

The recombination example sets some of these explicitly and can differ from wrapper defaults, including GLM projection cadence. Inspect the resolved run before comparing experiments. A smoothing width in cells changes physically when n changes; scale it for fixed-physical-width convergence tests.

4.6 Escape hatch

[environment]
MHD_PK_KMAX = 100.53096491487338
MHD_RADIATION_FREE_STREAM_TOL = 0.0
MHD_PMF_NORMALIZATION_Z = 10000.0
MHD_PMF_HIGH_MODE_LOCK_N = 128

These override named mappings and facade defaults. Paths are resolved by the launched process, so use explicit paths for imported initial states and response tables. Keep runs launched from the repository root. Numerical options with special encodings should follow their parser, not a guessed boolean conversion. MHD_GRAVITY, for example, uses true/false.

Do not enable terminal or hybrid as an automatic speed optimization. They require MHD_ALLOW_UNCERTIFIED_TERMINAL=1 and remain legacy comparisons. Neither a larger source cadence nor a nonzero free-streaming tolerance is a free accuracy improvement; validate them against a tighter reference.

4.7 Complete driver option index

This index is generated from get(ENV, "MHD_...", ...) calls in the actual extracted driver. Each link opens its parsing/default logic in the local source snapshot. A default can depend on other options; the curated tables above and the resolved environment describe the public facade.

Environment variable	Parsing and defaults
`MHD_ADAPTIVE_DIAG_REL`	runner source
`MHD_ADAPTIVE_DIAG_ZMAX`	runner source
`MHD_ADAPTIVE_DIAG_ZMIN`	runner source
`MHD_ALFVEN_BGUIDE`	runner source
`MHD_ALFVEN_BPERT`	runner source
`MHD_ALFVEN_BPERT_FRAC`	runner source
`MHD_ALLOW_NON_MPS_FFT`	runner source
`MHD_ALLOW_UNCERTIFIED_TERMINAL`	runner source
`MHD_BACKEND`	runner source
`MHD_BOXSIZE`	runner source
`MHD_CFL`	runner source
`MHD_CHECKPOINT_ALLOW_CFL_CHANGE`	runner source
`MHD_CHECKPOINT_ALLOW_NONLOCAL_TABLE_CHANGE`	runner source
`MHD_CHECKPOINT_AT_CYCLE`	runner source
`MHD_CHECKPOINT_DISABLE_WRITES`	runner source
`MHD_CHECKPOINT_EVERY`	runner source
`MHD_CHECKPOINT_FINAL`	runner source
`MHD_CHECKPOINT_PATH`	runner source
`MHD_CHECKPOINT_READ_PATH`	runner source
`MHD_CHECKPOINT_RESET_ENERGY_LEDGER`	runner source
`MHD_CHECKPOINT_RESUME`	runner source
`MHD_CHECKPOINT_WRITE_PATH`	runner source
`MHD_CHECK_EVERY`	runner source
`MHD_CHEM`	runner source
`MHD_CHEM_ADVECT_SPECIES`	runner source
`MHD_CHEM_ALLOW_LOCAL_MIXING`	runner source
`MHD_CHEM_COUPLING`	runner source
`MHD_CHEM_DENSITY_UNITS`	runner source
`MHD_CHEM_DTFRAC`	runner source
`MHD_CHEM_EXPANSION`	runner source
`MHD_CHEM_FALPHA`	runner source
`MHD_CHEM_FH`	runner source
`MHD_CHEM_FUSED_ANALYTIC`	runner source
`MHD_CHEM_FUSED_MIXING`	runner source
`MHD_CHEM_HELIUM`	runner source
`MHD_CHEM_H_STORAGE`	runner source
`MHD_CHEM_IONIZED_FAST_ZMIN`	runner source
`MHD_CHEM_ITCAP`	runner source
`MHD_CHEM_LENGTH_UNITS`	runner source
`MHD_CHEM_MEAN_EVERY`	runner source
`MHD_CHEM_NONLOCAL_SCALE`	runner source
`MHD_CHEM_NONLOCAL_TABLE`	runner source
`MHD_CHEM_NSMEAN`	runner source
`MHD_CHEM_PROFILE`	runner source
`MHD_CHEM_RATE_TABLES`	runner source
`MHD_CHEM_RECFAST_FUDGE`	runner source
`MHD_CHEM_RECFAST_HSWITCH`	runner source
`MHD_CHEM_SMOOTH`	runner source
`MHD_CHEM_SMOOTH_SIGMA_CELLS`	runner source
`MHD_CHEM_TIME_UNITS`	runner source
`MHD_CHEM_VUNIT`	runner source
`MHD_CHEM_XE_MEAN`	runner source
`MHD_COMPTON_DRAG`	runner source
`MHD_COSMOLOGICAL_MHD_SCALING`	runner source
`MHD_CYCLE_PRINT_EVERY`	runner source
`MHD_DEBUG_DIV_EVERY`	runner source
`MHD_DEBUG_PHASE_CYCLE_MIN`	runner source
`MHD_DEBUG_PHASE_FINITE`	runner source
`MHD_DEBUG_PHASE_RHO_MIN`	runner source
`MHD_DEBUG_PHASE_ZMAX`	runner source
`MHD_DEBUG_RADIATION_CORRECTION_CFL`	runner source
`MHD_DEBUG_RADIATION_CYCLE_MIN`	runner source
`MHD_DEBUG_RADIATION_RHO_MIN`	runner source
`MHD_DEBUG_RECON_OVERRIDE`	runner source
`MHD_DEBUG_RIEMANN_OVERRIDE`	runner source
`MHD_DEBUG_STOP_CYCLE`	runner source
`MHD_DENSITY_FRAME_DIR`	runner source
`MHD_DENSITY_FRAME_FIELD`	runner source
`MHD_DENSITY_FRAME_ZS`	runner source
`MHD_DIAG_CLEAR_FFT`	runner source
`MHD_DRAG_DT_BOOST`	runner source
`MHD_DRAG_DT_MODE`	runner source
`MHD_DRAG_HELIUM_ELECTRONS`	runner source
`MHD_DRAG_MAX_IMPULSE`	runner source
`MHD_DRAG_RATE_CODE`	runner source
`MHD_DRAG_VX0`	runner source
`MHD_DRAG_VY0`	runner source
`MHD_DRAG_VZ0`	runner source
`MHD_DRAG_XE`	runner source
`MHD_FB`	runner source
`MHD_FFT`	runner source
`MHD_FINAL_B_DIR`	runner source
`MHD_FINAL_DIAG`	runner source
`MHD_GLM_CH_FAC`	runner source
`MHD_GLM_CR`	runner source
`MHD_GLM_PROJECT_EVERY`	runner source
`MHD_GRAVITY`	runner source
`MHD_GRAVITY_1BUF`	runner source
`MHD_GRAVITY_DRAG_MAX_IMPULSE`	runner source
`MHD_GRAVITY_DT_BOOST`	runner source
`MHD_GRAVITY_GAS_KICK`	runner source
`MHD_GRAVITY_MIDPOINT_SOURCE`	runner source
`MHD_GRAVITY_PHI_INTERP`	runner source
`MHD_GRAVITY_SOURCE`	runner source
`MHD_GRAVITY_SUBCYCLES`	runner source
`MHD_H`	runner source
`MHD_HISTORY_TSV`	runner source
`MHD_HYBRID_AWARE_DT_FACTOR`	runner source
`MHD_HYBRID_CHECK_EVERY`	runner source
`MHD_HYBRID_CONFIRM_CHECKS`	runner source
`MHD_HYBRID_ENTER_DRAG_OVER_OMEGA`	runner source
`MHD_HYBRID_EXIT_DRAG_OVER_OMEGA`	runner source
`MHD_HYBRID_HANDOFF_ALPHA`	runner source
`MHD_HYBRID_HANDOFF_DIAG_EVERY`	runner source
`MHD_HYBRID_HANDOFF_DISPLACEMENT_TOL`	runner source
`MHD_HYBRID_HANDOFF_ERROR_TOL`	runner source
`MHD_HYBRID_HANDOFF_STEPS`	runner source
`MHD_HYBRID_MIN_DRAG_OVER_OMEGA`	runner source
`MHD_HYBRID_MIN_VA_CS`	runner source
`MHD_HYBRID_REENTER_TERMINAL`	runner source
`MHD_INITIAL_B_DIR`	runner source
`MHD_INITIAL_B_IMPORT_DIR`	runner source
`MHD_INITIAL_B_RESCALE_TO_PMF`	runner source
`MHD_INITIAL_HISTORY`	runner source
`MHD_INITIAL_PK`	runner source
`MHD_INITIAL_STATE_DIR`	runner source
`MHD_INIT_TERMINAL_MOMENTA`	runner source
`MHD_INTEGRATOR`	runner source
`MHD_LLF_DMIN`	runner source
`MHD_LLF_PMIN`	runner source
`MHD_MAXEXP`	runner source
`MHD_MAX_CYCLES`	runner source
`MHD_MEANFIELD_BGUIDE`	runner source
`MHD_MEANFIELD_BPERT`	runner source
`MHD_MEANFIELD_PERT_FRAC`	runner source
`MHD_MEANFIELD_POLARIZATION`	runner source
`MHD_MEANFIELD_THETA`	runner source
`MHD_MEMPROBE`	runner source
`MHD_MODE_HISTORY_TSV`	runner source
`MHD_OB`	runner source
`MHD_OL`	runner source
`MHD_OM`	runner source
`MHD_OR`	runner source
`MHD_OUT_TSV`	runner source
`MHD_P0`	runner source
`MHD_PARTICLE_LATTICE_DISPLACEMENTS`	runner source
`MHD_PARTICLE_MAX_DISP_CELLS`	runner source
`MHD_PARTICLE_WRAP`	runner source
`MHD_PDF_LOGRHO_MAX`	runner source
`MHD_PDF_LOGRHO_MIN`	runner source
`MHD_PDF_NBINS`	runner source
`MHD_PDF_TSV`	runner source
`MHD_PFLOOR`	runner source
`MHD_PK_AXIS`	runner source
`MHD_PK_EVERY`	runner source
`MHD_PK_KMAX`	runner source
`MHD_PK_NBINS`	runner source
`MHD_PK_NMU`	runner source
`MHD_PK_TSV`	runner source
`MHD_PK_ZS`	runner source
`MHD_PMF_B0_NG`	runner source
`MHD_PMF_B0_ZREF`	runner source
`MHD_PMF_BRMS`	runner source
`MHD_PMF_COMOVING_CLOCK`	runner source
`MHD_PMF_CURL_REFERENCE_N`	runner source
`MHD_PMF_CURL_SYMBOL`	runner source
`MHD_PMF_FIXED_MODE_POWER`	runner source
`MHD_PMF_HIGH_MODE_LOCK_N`	runner source
`MHD_PMF_INIT`	runner source
`MHD_PMF_INVARIANT_AXIS`	runner source
`MHD_PMF_KCUT`	runner source
`MHD_PMF_KMAX`	runner source
`MHD_PMF_KMIN`	runner source
`MHD_PMF_KMODE`	runner source
`MHD_PMF_MIN_CELLS_PER_WAVELENGTH`	runner source
`MHD_PMF_MODE_LOCK_N`	runner source
`MHD_PMF_MODE_REALIZATION`	runner source
`MHD_PMF_N`	runner source
`MHD_PMF_NORMALIZATION_KIND`	runner source
`MHD_PMF_NORMALIZATION_Z`	runner source
`MHD_PMF_PRESERVE_LOW_KCUT`	runner source
`MHD_PMF_PRESERVE_LOW_KMAX`	runner source
`MHD_PMF_REALIZATION_BOX`	runner source
`MHD_PMF_SEED`	runner source
`MHD_PMF_SINGLE_MODE_NORMALIZATION`	runner source
`MHD_PMF_TILE_BOXSIZE`	runner source
`MHD_PMF_TILE_N`	runner source
`MHD_PRECISION`	runner source
`MHD_PRINT_EVERY`	runner source
`MHD_PROFILE_SKIP_CYCLES`	runner source
`MHD_RADIATION_BRIDGE_Q2`	runner source
`MHD_RADIATION_CHECKPOINT_FALLBACK`	runner source
`MHD_RADIATION_ENERGY_LEDGER_EVERY`	runner source
`MHD_RADIATION_FREE_STREAM_TOL`	runner source
`MHD_RADIATION_HIGHZ_MAX_DLNA`	runner source
`MHD_RADIATION_HIGHZ_ZMIN`	runner source
`MHD_RADIATION_LONG_VISCOSITY`	runner source
`MHD_RADIATION_MAGNETIC_COMPENSATION`	runner source
`MHD_RADIATION_MAX_DLNA`	runner source
`MHD_RADIATION_NONLINEAR_CFL`	runner source
`MHD_RADIATION_NYQUIST_GUARD`	runner source
`MHD_RADIATION_PHOTON_ADIABATIC`	runner source
`MHD_RADIATION_PHOTON_COMOVING`	runner source
`MHD_RADIATION_POSITIVITY_FALLBACK`	runner source
`MHD_RADIATION_POSITIVITY_MAX_FALLBACK_PASSES`	runner source
`MHD_RADIATION_POSITIVITY_MAX_SUBDIVISIONS`	runner source
`MHD_RADIATION_POSITIVITY_WAVE_GROWTH_LIMIT`	runner source
`MHD_RADIATION_RESPONSE_MODEL`	runner source
`MHD_RECON`	runner source
`MHD_RIEMANN`	runner source
`MHD_SOLVER`	runner source
`MHD_SOURCE_MAX_DT_FACTOR`	runner source
`MHD_STEPS`	runner source
`MHD_STREAMING_TSV`	runner source
`MHD_TERMINAL_ACCURACY_CFL`	runner source
`MHD_TERMINAL_ACCURACY_PRESSURE`	runner source
`MHD_TERMINAL_B_REL_LIMIT`	runner source
`MHD_TERMINAL_DEDICATED_SCRATCH`	runner source
`MHD_TERMINAL_DIFF_CFL`	runner source
`MHD_TERMINAL_GAMMA_CODE`	runner source
`MHD_TERMINAL_GAMMA_SCALE`	runner source
`MHD_TERMINAL_IMPLICIT_DIFFUSE`	runner source
`MHD_TERMINAL_IMPLICIT_DIFFUSE_FAC`	runner source
`MHD_TERMINAL_INDUCTION`	runner source
`MHD_TERMINAL_INDUCTION_CFL`	runner source
`MHD_TERMINAL_INDUCTION_DISSIPATION`	runner source
`MHD_TERMINAL_INDUCTION_DISSIPATION_ORDER`	runner source
`MHD_TERMINAL_INDUCTION_MAX_SUBCYCLES`	runner source
`MHD_TERMINAL_KEFF`	runner source
`MHD_TERMINAL_LBOX_CKPC`	runner source
`MHD_TERMINAL_LBOX_CM`	runner source
`MHD_TERMINAL_MAX_DISP_CELLS`	runner source
`MHD_TERMINAL_PRESSURE_COEFF`	runner source
`MHD_TERMINAL_PRESSURE_IMPLICIT`	runner source
`MHD_TERMINAL_PROJECT_B`	runner source
`MHD_TERMINAL_RHO_REL_LIMIT`	runner source
`MHD_TERMINAL_SPLIT`	runner source
`MHD_TERMINAL_VCAP`	runner source
`MHD_TERMINAL_VSMOOTH`	runner source
`MHD_TFINAL`	runner source
`MHD_WARMUP`	runner source
`MHD_XH2_INIT`	runner source
`MHD_XHII_INIT`	runner source
`MHD_ZEND`	runner source
`MHD_ZSTART`	runner source