Configuration reference

A neoVULCAN simulation is configured by a single TOML file passed to vulcan.py with the -c flag (default: vulcan_cfg.toml next to vulcan.py). The file is parsed by tomllib (Python 3.11+) or tomli (Python 3.10) and validated against the Pydantic schema defined in src/neovulcan_config.py. Validation is strict: any unknown key, wrong type, or out-of-range value is rejected at load time with a precise error message rather than silently ignored.

The file is organised into ten sections. Each section maps to one of the Pydantic model classes (NetworkConfig, PathsConfig, ElementsConfig, AtmosphereConfig, PhotochemConfig, BoundaryConfig, CondensationConfig, SolverConfig, OutputConfig, PlottingConfig).

A machine-generated reference with every parameter and its default is shipped at vulcan_cfg_defaults.toml in the package root and in cfg_examples/. Treat it as documentation; do not edit it for production runs. To regenerate it after a schema change run:

python _gen_defaults_toml.py

CGS units (cm, g, s, K, dyn cm^-2, erg) are used throughout unless explicitly stated.

[network]

Chemical-reaction network and thermochemistry inputs. Schema: neovulcan_config.NetworkConfig.

Key	Type	Description
atom_list	list[str]	Required. Elements tracked for conservation (e.g. ["H", "O", "C", "N", "S", "He"]).
network	str	Required. Path to the network file (e.g. "thermo/SNCHO_photo_network_2025.txt").
gibbs_text	str	Index file listing the NASA-9 polynomial files used to build Gibbs free energies. Default "thermo/gibbs_text.txt".
com_file	str	Composition file with basic per-species properties (mass, charge, atomic content). Default "thermo/all_compose.txt".
cross_folder	str	Directory of photolysis cross-sections. Default "thermo/photo_cross/".
use_lowT_limit_rates	bool	Clip thermal rates to their low-temperature limits below the Arrhenius validity range. Default false.
remove_list	list[int]	Reaction indices to disable. Forward/reverse pairs should be removed together (e.g. [315, 316]). Default [].

[paths]

File-system paths for atmospheric input, stellar flux, boundary conditions, and output. Schema: neovulcan_config.PathsConfig.

When VulcanConfig.from_toml is called with absolutify_paths=True (used by the library API), relative paths are resolved against the base_dir argument (TOML’s directory by default); otherwise the values are passed through unchanged.

Key	Type	Description
fastchem_dir	str	FastChem element & rate-coefficient directory. Default "fastchem_input".
atm_file	str	Required. Temperature–pressure profile (and optional \(\Kzz\)).
sflux_file	str	Required. Stellar flux density at the stellar surface (\(\mathrm{erg\,cm^{-2}\,s^{-1}\,nm^{-1}}\)).
top_BC_flux_file	str	Top-of-atmosphere boundary-condition flux file. Default "atm/".
bot_BC_flux_file	str	Bottom-of-atmosphere boundary-condition flux file. Default "atm/".
vul_ini	str	Previous .vul file to initialise abundances from (only read when elements.ini_mix = "vulcan_ini"). Default "output/".
output_dir	str	Output directory for the pickle file. Default "output/".
plot_dir	str	Output directory for plots. Default "plot/".
movie_dir	str	Output directory for live-plot frames. Default "plot/movie/".
out_name	str	Required. Output file name (extension .vul).

[elements]

Elemental abundances and initial mixing-ratio mode. Schema: neovulcan_config.ElementsConfig.

Key	Type	Description
use_solar	bool	Use the solar abundances of Lodders (2009). If false the metal_abundances sub-table is used instead. Default false.
metal_abundances	dict[str, float]	Element-to-hydrogen number ratios (e.g. {O = 5.37e-4, C = 2.95e-4, He = 0.0838}). Empty by default; set in the sub-table [elements.metal_abundances].
ini_mix	str	Initial-condition mode: one of "EQ" (FastChem equilibrium), "const_mix", "vulcan_ini", "table". Default "const_mix".
fastchem_met_scale	float	Metallicity scaling factor passed to FastChem for the trace elements not in atom_list (e.g. Si, Mg). 1.0 is solar.
const_mix	dict[str, float]	Constant mixing ratios used when ini_mix = "const_mix" (e.g. {N2 = 0.78, O2 = 0.20, H2O = 1.0e-6}). Empty by default; set in the sub-table [elements.const_mix].

[atmosphere]

Atmospheric structure: vertical grid, T–P profile, eddy diffusion, molecular diffusion, advection, planet/star geometry. Schema: neovulcan_config.AtmosphereConfig.

Key	Type	Description
atm_base	str	Bulk gas. One of "H2", "N2", "O2", "CO2". Selects the binary molecular-diffusion and thermal-diffusion tables. Default "N2".
rocky	bool	true for rocky planets (surface gravity is used); false for gas giants. Default true.
nz	int	Required. Number of vertical layers (> 0).
P_b	float	Required. Pressure at the bottom of the model (dyn cm-2, > 0).
P_t	float	Required. Pressure at the top of the model (dyn cm-2, > 0). Must satisfy P_t < P_b (the validator enforces this).
use_Kzz	bool	Include eddy diffusion. Default true.
use_moldiff	bool	Include molecular diffusion (with thermal-diffusion drift). Default true. Required for solver.ode_solver = "Rodas3".
use_vm_mol	bool	Alternative mixing-length parameterisation in place of molecular diffusion. Default false.
use_vz	bool	Include vertical advection. Default false.
atm_type	str	How \(T(P)\) is specified: "isothermal", "analytical", "file", "vulcan_ini", or "table". Default "file".
Kzz_prof	str	How \(\Kzz(P)\) is specified: "const", "file", or "Pfunc" (constant below K_p_lev and \(P^{-0.4}\) above). Default "file".
K_max	float	Plateau value of \(\Kzz\) (cm2s-1) used with Kzz_prof = "Pfunc". Default 1.0e5.
K_p_lev	float	Transition pressure (bar) where Kzz_prof = "Pfunc" switches from constant to \(P^{-0.4}\) scaling. Default 0.1.
K_deep	float, optional	Lower-atmosphere plateau value used by some Kzz_prof extensions. Omit to disable.
vz_prof	str	"const" or "file". Default "const".
gs	float	Required. Surface gravity (cm s-2).
Tiso	float	Isothermal temperature (K), only read when atm_type = "isothermal". Default 1000.0.
para_warm	list[float]	\((T_\mathrm{int}, T_\mathrm{irr}, \kappa_L, \kappa_S, \beta_S, \beta_L)\) parameters for the analytical T–P profile of Heng et al. (2014). Six elements; default [120, 1500, 0.1, 0.02, 1, 1].
para_anaTP	list[float], optional	Same six parameters used when atm_type = "analytical". If omitted it is aliased to para_warm.
const_Kzz	float	Constant \(\Kzz\) (cm2s-1) used when Kzz_prof = "const". Default 1.0e10.
const_vz	float	Constant vertical wind (cm s-1) used when vz_prof = "const". Default 0.0.
update_frq	int	Number of steps between updates of \(\mathrm{d}z\) and \(\mathrm{d}z_i\) due to changes in the mean molecular weight. Default 100.
r_star	float	Stellar radius in \(R_\odot\). Default 1.0.
Rp	float	Required. Planetary radius (cm).
orbit_radius	float	Planet–star distance (AU). Default 1.0.
sl_angle_deg	float	Solar zenith angle in degrees (the conventional dayside average is 58°). Default 58. The radian value sl_angle = math.radians(sl_angle_deg) is exposed as a derived property on the config object for convenience.
f_diurnal	float	Diurnal-averaging factor applied to all photolysis rates (0.5 for an Earth-like rotator, 1.0 for a tidally-locked planet). Default 0.5.

[photochemistry]

Photochemistry and the radiative-transfer backend used to compute the actinic flux. Schema: neovulcan_config.PhotochemConfig.

Key	Type	Description
use_photo	bool	Include photochemistry. Default false.
use_ion	bool	Include photoionisation chemistry. Requires use_photo = true (the validator rejects use_ion = true otherwise). Default false.
scat_sp	list[str]	Bulk gases that contribute Rayleigh scattering (e.g. ["H2", "He"] for hot Jupiters, ["N2", "O2"] for Earth). Empty by default.
T_cross_sp	list[str]	Species for which temperature-dependent UV cross-sections are loaded. Currently available: CO2, H2O, NH3, SH, H2S, SO2, S2, COS, CS2. Start-up cost is noticeably higher when this list is non-empty.
edd	float	First Eddington coefficient \(\epsilon\) used by the two-stream backend to convert the diffuse flux to actinic units. Default 0.5.
dbin1	float	Wavelength bin width in the VUV (nm), below dbin_12trans. Default 0.1.
dbin2	float	Wavelength bin width in the MUV/NUV (nm), above dbin_12trans. Default 2.0.
dbin_12trans	float	Transition wavelength (nm) where the bin width changes from dbin1 to dbin2. Default 240.0.
ini_update_photo_frq	int	Number of time steps between actinic-flux updates while the chemistry is still evolving rapidly. Default 100.
final_update_photo_frq	int	Number of time steps between actinic-flux updates once the chemistry is near steady state. Default 5.
rt_scheme	str	Radiative-transfer backend. "two-stream" (default) uses the delta-Eddington solver; "disort" uses the DisORT++ Python bindings. See Numerical methods.
surface_albedo	float	Lambertian surface albedo at the lower boundary. Only honoured by the DisORT++ backend. Default 0.0.
disort_nstr	int	Number of streams (Gauss–Legendre points) used by the DisORT++ backend. Higher = more accurate angular discretisation but \(\mathcal{O}(n_\mathrm{str}^{\,3})\) more expensive per layer. Default 8.

[boundary_conditions]

Top and bottom boundary conditions. Schema: neovulcan_config.BoundaryConfig.

Key	Type	Description
use_topflux	bool	Apply a top-of-atmosphere flux from paths.top_BC_flux_file. Default false.
use_botflux	bool	Apply a surface flux from paths.bot_BC_flux_file. Default false.
use_fix_sp_bot	dict[str, float]	Fixed mixing ratios at the bottom boundary (e.g. { H2O = 0.0143, CO2 = 4.0e-4 }).
diff_esc	list[str]	Species treated with the diffusion-limited escape flux at the top boundary. Default ["H"].
max_flux	float	Upper limit (cm-2s-1) for the escape flux. Default 1.0e13.
use_sat_surfaceH2O	bool	Use a surface-temperature-controlled water saturation as the bottom boundary for H2O. Default false.
use_fix_H2He	bool	Pin the H2/He ratio at the lower boundary. Useful for deep hot-Jupiter columns where the H2/He inventory must not drift. Default false.
loss_ex	list[str]	Species excluded from the element-conservation diagnostic (useful for surface sinks that legitimately consume mass). Default [].

[condensation]

Condensation, evaporation and particle settling. Schema: neovulcan_config.CondensationConfig.

Key	Type	Description
use_condense	bool	Enable condensation/evaporation reactions. Default false.
use_settling	bool	Apply Stokes settling to condensed species. Default false.
use_relax	list[str]	Species advanced by implicit relaxation instead of the global Rosenbrock step (typically ["H2O", "H2SO4"]). Default [].
humidity	float	Relative humidity for water vapour. Default 1.0.
r_p	dict[str, float]	Particle radius (cm) keyed by condensate species (e.g. { H2O_l_s = 1.0e-2 }). Set in sub-table [condensation.r_p].
rho_p	dict[str, float]	Particle density (g cm-3) keyed by condensate species. Set in sub-table [condensation.rho_p].
start_conden_time	float	Simulation time (s) at which condensation is switched on. Default 0.0.
stop_conden_time	float	Simulation time (s) after which condensation is switched off. Default 5.0e8.
condense_sp	list[str]	Condensable gas species. Default [].
non_gas_sp	list[str]	Names of the corresponding condensate species (e.g. ["H2O_l_s", "H2SO4_l"]). Default [].
fix_species	list[str]	Species frozen after fix_species_time. Default [].
fix_species_time	float, optional	Simulation time (s) after which the species in fix_species are pinned at their current values. If omitted, aliased to stop_conden_time.
fix_species_from_coldtrap_lev	bool	Only pin species below the cold-trap level. Default true.
use_ini_cold_trap	bool	Apply a cold trap to the initial state. Default true.

[solver]

ODE integrator, step-size controller, convergence diagnostics, optional Newton finisher. Schema: neovulcan_config.SolverConfig.

Key	Type	Description
ode_solver	str	"Ros2", "Rodas3" or "ODESolver" (case-sensitive). Default "Ros2". "Rodas3" requires atmosphere.use_moldiff = true.
use_pi_controller	bool	Use a PI step-size controller instead of the default integrating controller. Default false.
use_print_prog	bool	Print a progress line every print_prog_num steps. Default true.
use_print_delta	bool	Print the per-step truncation error. Default false.
print_prog_num	int	Progress-print frequency in steps. Default 500.
dttry	float	Initial time step (s). Default 1.0e-10.
trun_min	float	Minimum total integration time (s). Default 1.0e2.
runtime	float	Maximum total integration time (s). Default 1.0e22.
dt_min	float	Hard lower bound on the time step (s). Default 1.0e-14.
dt_max	float, optional	Hard upper bound on the time step (s). If omitted, derived as runtime * 1e-5.
dt_var_max	float	Maximum per-step time-step growth factor. Default 2.0.
dt_var_min	float	Minimum per-step time-step shrink factor. Default 0.5.
count_min	int	Minimum number of steps before convergence checks fire. Default 120.
count_max	int	Hard upper bound on the number of steps. Default 40000.
atol	float	Absolute tolerance (cm-3). Number densities below this are excluded from the error norms. Default 0.1.
mtol	float	Relative-tolerance floor used by the step-size controller. Default 1.0e-22.
mtol_conv	float	Relative-tolerance floor used by the convergence check. Default 1.0e-16.
pos_cut	float	Clip small positive values to zero. Default 0.0.
nega_cut	float	Threshold below which negative updates trigger a step rejection. Default -1.0.
loss_eps	float	Element-conservation tolerance used by the adaptive rtol controller. Default 1.0e12.
yconv_cri	float	Relative change \(\Delta\hat n\) threshold (the \(\delta\) in Numerical methods). Default 0.01.
slope_cri	float	\(\Delta\hat n / \Delta\tau\) threshold (the \(\epsilon\) in Numerical methods). Default 1.0e-4.
yconv_min	float	Relaxed alternative for yconv_cri. Default 0.1.
flux_cri	float	Relative change of the actinic flux threshold. Default 0.1.
flux_atol	float	Absolute tolerance for the actinic flux (photons cm-2s-1nm-1). Default 1.0.
st_factor	float	Fraction of the integration time used for the steady-state window (default 0.5 means the last half is examined).
conv_step	int	Hard cap on the number of past steps used in the convergence check. Default 500.
conver_ignore	list[str]	Species excluded from the convergence diagnostic (used for species whose noise level dominates the dominant-\(\Delta\) test but does not matter for the result). Default [].
rtol	float	Relative tolerance \(\mathcal{T}\) for the step-size controller. Default 1.0.
post_conden_rtol	float	Value of rtol switched to after fix_species_time. Default 0.05.
use_adapt_rtol	bool	Adapt rtol dynamically based on element-conservation drift. Default true.
rtol_min	float	Lower bound for the adaptive rtol. Default 0.02.
rtol_max	float	Upper bound for the adaptive rtol. Default 2.5.
use_newton_finisher	bool	Enable the optional damped-Newton tail described in Numerical methods. Default false.
newton_switch_dy	float	Per-step fractional change below which the Newton finisher takes over. Default 1.0.
newton_cooldown	int	Number of Rosenbrock steps that must elapse between successive Newton firings. Default 200.
newton_max_iter	int	Maximum number of Newton iterations per firing. Default 20.
newton_res_tol	float	Residual norm at which the Newton finisher considers itself converged. Default 1.0e-6.
newton_alpha_min	float	Smallest damping factor allowed by the line-search inside the Newton finisher. Default 1.0e-3.

[output]

Pickle file and evolution-history options. Schema: neovulcan_config.OutputConfig.

Key	Type	Description
output_humanread	bool	Also write a human-readable text dump of the final state. Default false.
use_shark	bool	Easter egg.
save_evolution	bool	Store the abundance and time history in the output file. Default false.
save_evo_frq	int	Number of steps between evolution-history samples. Default 10.
y_time_freq	int	Number of steps between snapshots stored in the evolution arrays. Default 1.

[plotting]

Live-plot, end-of-run plot, and movie options. Schema: neovulcan_config.PlottingConfig.

Key	Type	Description
plot_TP	bool	Plot the T–P profile at the start of the run. Default false.
use_live_plot	bool	Show a live matplotlib plot of mixing-ratio profiles during integration. Default false.
use_live_flux	bool	Show a live plot of the actinic flux. Default false.
use_plot_end	bool	Plot mixing ratios after the integration finishes. Default false.
use_plot_evo	bool	Plot the time evolution at each layer at the end. Default false.
use_save_movie	bool	Save the live-plot frames to paths.movie_dir for later assembly into a movie. Default false.
use_flux_movie	bool	Save live-flux frames. Default false.
plot_height	bool	Use the altitude (cm) instead of pressure on the vertical axis. Default false.
use_PIL	bool	Use the Pillow library to composite live plots; fall back to a simpler renderer if Pillow is unavailable. Default true.
live_plot_frq	int	Number of steps between live-plot updates. Default 10.
save_movie_rate	int, optional	Number of steps between movie-frame saves. If omitted, aliased to live_plot_frq.
plot_spec	list[str]	Species to include in live plots. Default [].

Cross-section validators

A small number of consistency rules are enforced after every load and after every programmatic override:

• atmosphere.P_t < atmosphere.P_b — the top pressure must be strictly smaller than the bottom one.

• atmosphere.para_warm and atmosphere.para_anaTP must each have exactly six elements.

• photochemistry.use_ion = true requires photochemistry.use_photo = true.

• solver.ode_solver = "Rodas3" requires atmosphere.use_moldiff = true.

These are all expressed as Pydantic validators in src/neovulcan_config.py; their error messages identify the offending field on failure.

Practical advice

• Start from one of the example configurations in cfg_examples/ rather than from scratch; the boundary conditions, network choice, and \(\Kzz\) profile of a working setup are difficult to guess.

• For hot atmospheres (\(T \gtrsim 1000\) K), the default elements.ini_mix = "EQ" together with the SNCHO photo network is the recommended starting point.

• For terrestrial atmospheres, set atmosphere.rocky = true, choose atmosphere.atm_base to match the bulk gas, use elements.ini_mix = "const_mix" with realistic surface mixing ratios, and switch on condensation.

• If the solver oscillates between accepting and rejecting steps, reduce solver.atol (a smaller absolute tolerance is more permissive in this code, because trace species below atol are not used to judge the step size).

• If the run terminates with end_case != 1 even after solver.count_max steps, the most common causes are (i) a poorly conditioned boundary condition, (ii) a missing reaction in the network that should close a fast cycle, or (iii) a \(\Kzz\) profile with very large gradients that interact badly with the finite-difference stencil.