PyRETIS TOML configuration schema

This document lists the TOML keys read by pyretis run, grouped by section. The scheduler-backed configuration is parsed by pyretis.simulation.setup.setup_config.

---

[runner]

Key	Type	Default	Description
workers	int	required	Number of parallel REPEX workers
wmdrun	list[str]	[]	Per-worker MD run commands (optional)

[simulation]

Key	Type	Default	Description
interfaces	list[float]	required	Sorted interface values for TIS ensembles
steps	int	required	Total number of RETIS cycles
shooting_moves	list[str]	required	Move type per interface: "sh" (shooting) or "wf" (wire-fencing)
seed	int	0	RNG seed for reproducibility
load_dir	str	"accepted"	Name of the per-ensemble operational trajectory store (<ensemble>/<load_dir>/<path number>); a user-staged flat top-level directory of this name is still read as input via the legacy-layout fallback
zeroswap	float	0.5	Probability of zero-plus swaps in REPEX
pick_scheme	int	0	Ensemble picking scheme (0 = uniform)
relative_shoots	list[float] or null	null	Relative per-ensemble move-selection frequencies (one weight per ensemble, interface order, [0^-] first). The scheduler weights its per-ensemble pick by these; reallocates sampling effort without biasing the rate. Native [retis] relative_shoots is carried here by the adapter
ensemble_engines	list[list[str]]	auto	Engine keys per interface

[simulation.tis_set]

Key	Type	Default	Description
maxlength	int	20000	Maximum allowed path length. The default is a deliberately generous cap so an input need not set it; a run that falls back to it logs that it did, and records the value it used. Set it explicitly for systems with long paths — a cap that is too small biases the sampling
allowmaxlength	bool	false	Accept paths exactly at max length
zero_momentum	bool	optional	Reset centre-of-mass momentum after shooting. When the key is absent each engine’s own default applies: most engines leave it False (no change), but the continuous CP2K engine defaults it to True (zeroes COM motion). Only carried through / honoured when set explicitly
n_jumps	int	required	Velocity reassignment jumps per shooting move
quantis	bool	false	Use quantIS variant (per-ensemble engines)
lambda_minus_one	bool/int	false	Create a minus interface below the first
accept_all	bool	false	Accept all paths unconditionally
interface_cap	float	optional	Upper interface cap for flux collection
perm_threshold	int	12	Max ensemble block size for which the exact matrix permanent is computed (larger blocks use the stochastic approximation)
perm_n_samples	int	10000	Sample count for the stochastic permanent approximation used above perm_threshold
exact_perm_only	bool	false	Forbid the stochastic fallback (raise instead of approximating a block larger than perm_threshold)

[engine]

Multiple engines can be defined as [engine], [engine0], [engine1], etc.

Key	Type	Default	Description
class	str	required	Engine type: turtlemd, cp2k, gromacs, lammps, ase, ams
engine	str	required	Backend name (for logging)
timestep	float	required	MD timestep in engine’s native units
subcycles	int	required	MD steps per TIS move
temperature	float	required	Simulation temperature
boltzmann	float	required	Boltzmann constant (kB)
input_path	str	external only	Path to external engine input files
cp2k	str	CP2K only	CP2K executable name
gmx	str	GROMACS only	GROMACS executable (e.g. gmx_mpi)
lmp	str	LAMMPS only	LAMMPS executable (e.g. lmp_mpi)
masses	list/str	GROMACS	Particle masses or path to masses.txt

[engine.integrator]

Key	Type	Description
class	str	Integrator class: LangevinInertia, LangevinOverdamped, VelocityVerlet, Verlet

[engine.integrator.settings]

Keys vary by integrator. Examples for Langevin:

Key	Type	Description
gamma	float	Friction coefficient
beta	float	Inverse temperature: 1 / (kB * T)

[engine.potential]

Key	Type	Description
class	str	Potential class: DoubleWell, LennardJones, DoubleWellPair

[engine.potential.settings]

Keys vary by potential. Examples for DoubleWell:

Key	Type	Description
a	float	Quartic coefficient
b	float	Quadratic coefficient
c	float	Constant offset

[engine.particles]

Key	Type	Description
mass	list[float]	Mass of each particle
name	list[str]	Name/symbol of each particle
pos	list[list[float]]	Initial position of each particle

[engine.box]

Key	Type	Description
periodic	list[bool]	Periodicity per dimension

[orderparameter]

Key	Type	Default	Description
class	str	required	Order parameter class
index	list[int]	required	Particle indices for the OP
periodic	bool	required	Apply PBC to OP calculation
module	str	external	Path to Python file with custom OP class

[output]

Key	Type	Default	Description
data_dir	str	required	Output directory
screen	int	1	Print frequency to the screen/console output
pattern	int/bool	false	Print frequency of ensemble distribution
order-file	int	optional	Order parameter output frequency
energy-file	int	optional	Energy output frequency
trajectory-file	int	optional	Trajectory output frequency (-1 = never)
backup	str	'append'	What to do with an already-existing output file: 'append' (default), 'overwrite', or 'backup' (rename it to _XXX first)
archive_every	int	1	Long-term archive cadence: a superseded path MOVES from its per-ensemble operational store (<ens>/accepted/<pn>) to the per-ensemble long-term store (<ens>/archive/<pn>), but only every N-th one is kept (path number a multiple of N), so the archive holds ~1 trajectory per N accepted moves; 1 keeps every one. Bounds disk the way the classic trajectory-file frequency did. (The former delete_old / delete_old_all / keep_maxop_trajs deletion keys are retired.)
keep_traj_fnames	list[str]	[]	Extra trajectory file patterns the archiver carries along when moving a path
log_file	str	'pyretis.log'	Run-log file name; also used by the worker processes, which append to the same file (an explicit pyretis run -f wins for the main process only — set the keyword for parallel runs)
log_mode	str	'append'	Start-of-run treatment of an existing run log: 'append' keeps it growing (a restart continues the same file), 'backup' rotates it to pyretis.log_000… first, 'overwrite' truncates it
engine_log	str/int	'last'	Per-trajectory engine-log retention: each finished trajectory’s engine logs (engine.log/engine.err, stdout.txt/stderr.txt, *.log/*.screen) move from the ensemble generate/ scratch to <ens>/engine_logs/<seq>/, zeroing the live log for the next trajectory; keep 'last' (only the most recent), 'all', or the N most recent. A failed generation leaves its logs in the scratch for inspection

[current] (scheduler-generated run state)

Do not add this section to the input file you write. When a run starts, the scheduler resolves that input configuration and writes output.toml in the run directory. That generated file is the run record: it contains both the resolved configuration and a [current] section recording the latest restartable scheduler state.

The scheduler rewrites output.toml atomically at checkpoints, so it is safe to inspect between updates. Treat it as output, however: changing it by hand can make the stored state inconsistent with trajectories and other run files. To change a simulation, edit the original input and start a new run; to continue an interrupted one, restart from its run directory and let PyRETIS read output.toml.

restart.toml is the older name for the same kind of generated state file. It is read only as a fallback when output.toml is absent, so previously created runs remain restartable.

Key	Type	Description
cstep	int	Current RETIS cycle
traj_num	int	Total trajectory count
size	int	Number of ensembles
active	list[int]	Active path indices
rng_state	dict	NumPy Generator state for restart
provenance	dict	Version/env metadata (P7.3)
restarted_from	int	Previous cstep on restart