# 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 |