# 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 | `"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 | *required* | Maximum allowed path length |
| `allowmaxlength` | bool | *required* | 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`) |
| `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 |
| `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 |

## `[current]` (managed internally)

Written to `output.toml` by the scheduler -- the single, atomically
written run file that carries the resolved config plus the running
`[current]` state. Not normally edited by users, but useful for
inspection and restart. An existing on-disk `restart.toml` is still
accepted as a legacy name on 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 |