infRETIS TOML configuration schema

This document lists every key that pyretis run reads from a TOML input file selecting the infinite-swapping sampler ([simulation] task = "infinite_swapping" or a [runner] section), grouped by section. The schema matches 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	"load"	Directory with initial trajectory data
zeroswap	float	0.5	Probability of zero-plus swaps in REPEX
pick_scheme	int	0	Ensemble picking scheme (0 = uniform)
ensemble_engines	list[list[str]]	auto	Engine keys per interface

[simulation.tis_set]

Key	Type	Default	Description
maxlength	int	required	Maximum allowed path length
allowmaxlength	bool	required	Accept paths exactly at max length
zero_momentum	bool	required	Reset centre-of-mass momentum after shooting
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

[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)
infretis_genvel	bool	GROMACS	Generate velocities in Python (inf-flavour key; the native GROMACS/LAMMPS engines use velocity_generation = "engine" | "maxwell" instead — see the engine section docs)
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 sim.log
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	optional	Backup directory for old trajectories
delete_old	bool	false	Delete superseded trajectories
delete_old_all	bool	false	Delete all old trajectories
keep_maxop_trajs	bool	false	Keep trajectories with highest OP
keep_traj_fnames	list[str]	[]	Trajectory file patterns to always keep

[current] (managed internally)

Written to restart.toml by the scheduler. Not normally edited by users, but useful for inspection and restart.

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