PyRETIS TOML configuration schema

This document lists the keys of the scheduler configuration, grouped by section: the configuration the scheduler builds in memory from a canonical input (task = "retis", [tis], …). The scheduler configuration is set up by pyretis.simulation.setup.setup_config. No file PyRETIS writes holds it: the run file output.toml records the canonical input (see [current] below).

The deprecated legacy-runner schema (a [runner] section, the path-sampling settings under [simulation.tis_set], no [simulation] task) is an input of this shape. PyRETIS 4 converts such an input to its canonical form when it reads it, with a deprecation notice, and PyRETIS 5 will not read it. pyretis run, pyretis analyse, the scheduler set-up of a programmatic run and the interface optimiser convert it the same way (pyretis/tools/convert_legacy_schema.py): each key goes to its input key (the table below), the canonical form is parsed as every canonical input is, and the conversion is checked against the scheduler configuration of the input, a difference stopping it with the settings that differ. python -m pyretis.tools.convert_legacy_schema <file> writes the canonical form to a file once, with the same check.

A canonical input reaches these keys through the declared key table, pyretis.inout.key_table: one entry per scheduler path names the input keys it is read from. The keys whose name or section differ:

Scheduler key	Input key
[simulation.tis_set] <key>	[tis] <key>
[simulation.tis_set] lambda_minus_one	[simulation] zero_left
[simulation.tis_set] permeability	[simulation] permeability
[simulation] shooting_moves	[tis] shooting_moves, else [tis] shooting_move for every ensemble
[simulation] zeroswap	[retis] swapfreq (a repptis run that sets none takes 0.5)
[simulation] relative_shoots	[retis] relative_shoots
[simulation] noswap, repptis, explore, single_tis, pptis_no_minus, pptis_no_zero_plus, repptis_memory	[simulation] task (with zero_left, flux, zero_ensemble, [pptis] memory, [repptis] memory)
[output] order_file, energy_file	[output] order-file, energy-file

A message of pyretis run names a setting by its input key, e.g. [simulation] zero_left. The run file output.toml records the canonical input, not this configuration (see [current] below).

An input key either takes effect on the run or the input is refused: pyretis/inout/key_table.py:NO_EFFECT declares the input keys and sections that take no effect on a run, with the runs they take none on, and the settings parse of a canonical input refuses each one the input gives, naming the key and, for a key whose value another key sets, that key ([simulation] zeroswap names [retis] swapfreq; [simulation] relative_shoots and [tis] relative_shoots name [retis] relative_shoots; [simulation] restart names [initial-path] method = "restart"). The table of these keys is in the input reference (docs/user/section/sections.rst, “Keywords that take no effect on a run”). The canonical form of a legacy-runner input is refused the same way, and the message names each key in the canonical input and in the legacy-runner input, e.g. [tis] nullmoves ([simulation.tis_set] nullmoves of the legacy-runner input) = true. The conversion gives [simulation] zeroswap its input key, [retis] swapfreq of a retis run (a tis or explore run, which attempts no swap, leaves it out with a warning), and leaves out the [output] keys of the in-process output, with a warning.

---

[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. The name is relative, and the first component of the name, after os.path.normpath, may not be generate, archive, rejected or engine_logs (directories the run writes in each ensemble directory), pyretis-cp2k-wfn (the wavefunction store of the streaming CP2K engine in the run directory), the name of an ensemble directory (000, 001, …), . or ..: such a name stops the run with a TOMLConfigError before it writes a file. A resume reads its active paths from the store its load_dir names and stops with a FileNotFoundError naming each missing traj.txt
zeroswap	float	0.5	Probability of a swap move: in a retis run, the swap of the [0^-] and [0^+] paths when a move picks one of them and the other is free; in a repptis run, a swap with an adjacent ensemble. The input key is [retis] swapfreq
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. The input key is [retis] relative_shoots
priority_shooting	bool	false	Weights the per-ensemble pick toward the ensembles with fewer submitted moves (weight n_max - n + 1; a zero swap counts for both ensembles); the path is drawn from the chosen ensemble as usual. The counts are kept in [current] moves_submitted over restarts. Cannot be combined with pick_scheme or relative_shoots
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	false	Reset the centre-of-mass momentum after every velocity draw: shooting and the kicks of the initial-path search, in every engine. GROMACS with velocity_generation = "engine" (gen_vel) and AMS (GenerateVelocities; RandomVelocitiesMethod Gromacs and Exact, the AMS default, while Boltzmann is not checked) remove the net linear momentum of the velocities they generate, so they require true; lammps_steps with velocity_generation = "engine" writes the mom keyword of velocity create from it (mom yes / mom no), and lammps draws the velocities in PyRETIS and resets the momentum as it selects. A continuation with [initial-path] method = "restart" is refused when it draws the shooting velocities differently from the run it continues, and a resume of an output.toml without [current.provenance] velocity_draw_rule (pyretis run -i output.toml) is refused when the settings it records draw differently from the engine of that run (see the restart method in docs/user/section/initial.rst)
rescale_energy	float or bool	false	The total energy the shooting velocities are re-scaled to; false, or a number that is not positive, leaves the energy of the draw. The internal integrators, OpenMM and cp2k_steps re-scale in PyRETIS, and lammps_steps with velocity_generation = "engine" in LAMMPS (to pe + ke as LAMMPS evaluates them, per atom under thermo_modify norm yes); every other engine stops with an error at its first shooting draw for a positive value. The internal integrators and OpenMM also re-scale the kicks of the initial-path search. A continuation and a resume compare it as they compare zero_momentum
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 between two stored frames of a path; an internal integrator of [engine] takes it in the in-process kick initiation as well
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	10	Cycles between two progress reports of the scheduler in the log (0 writes none); the input key [output] screen
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	Read by the in-process tasks (md, md-flux) only; the canonical input of a path-sampling run refuses it, and the conversion of a legacy-runner input leaves it out
backup	str	'append'	Read by the in-process tasks (md, md-flux) only; the canonical input of a path-sampling run refuses it, and the conversion of a legacy-runner input leaves it out
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, pyretis run writes output.toml in the run directory. That generated file is the run record: it contains the sections of the canonical input, under the names of the input and with every default the run takes resolved (the zero-swap probability as [retis] swapfreq), and a [current] section recording the latest restartable scheduler state. It holds none of the settings the input parse derives (the engine type, the input_files the GROMACS and CP2K checkers find, the exe_path of the run directory, the per-ensemble copies of the sections), and none of the keys and sections that take no effect on the run (pyretis/inout/key_table.py:NO_EFFECT): the settings parse refuses each one an input gives, and the record leaves out the value the parse gives such a key (the [simulation] restart it derives from method = "restart", the [engine0] of a run that runs no [engine0] engine, [simulation] rgen, and the rgen of [tis], [engine] and [system] for a run whose initiation kicks no path in process). It records [output] screen. The scheduler builds its configuration from those sections with the key table, when the run starts and when it resumes. pyretis run -i output.toml resumes the run, and pyretis analyse -i output.toml analyses it as its input would. The output.toml of an earlier PyRETIS that holds keys of no effect is read without them (pyretis/inout/run_record.py:load_run): silently when the value is the one the settings parse gives, named in a warning otherwise; [simulation] zeroswap is read as [retis] swapfreq, and [tis] relative_shoots as [retis] relative_shoots when the file sets none there.

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. The output.toml and restart.toml of an earlier PyRETIS hold the scheduler configuration of this document, with its [simulation.tis_set] table, and the [current] state. A continuation with [initial-path] method = "restart" reads such a state file and compares its settings with the continuation’s; pyretis run -i refuses it and names that route. pyretis analyse -i reads its settings under the names of the input, through the inverse of the key table (pyretis/inout/key_table.py:canonical_items), and refuses the state file of a tis run of one ensemble, whose analysis counts a crossing at [tis] detect when the input gives [tis] ensemble_number, which the scheduler configuration does not say.

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