The Runner section (infinite swapping)

The [runner] section configures the infinite-swapping sampler – the asynchronous, parallel reformulation of replica exchange described in the moves guide. It is only used by the infinite-swapping route; the in-process simulation flow ignores it.

This page documents how the two PyRETIS execution routes are selected from the input, the keywords of the [runner] section, and the environment variables that override the routing. For a worked example see the infinite-swapping tutorial and the runnable inputs under the per-engine examples/tutorials/path_sampling/<engine>/<system>/infinite_swapping/ cases.

Note

The infinite-swapping inputs use the TOML input format (pyretis run -i infswap.toml), not the classic .rst input. A complete annotated input is shipped at examples/tutorials/path_sampling/turtlemd/1D-double-well/infinite_swapping/infswap.toml.

The two execution routes

Every path-sampling run is driven through the single pyretis run command, and every one of them runs on the infinite-swapping scheduler: a central coordinator hands work to a pool of parallel workers. That holds for a TOML input with task = "tis", "retis", "explore", "pptis" or "repptis", with an explicit infinite-swapping task (task = "infinite_swapping" or "infswap"), or with a [runner] section, and for every engine. Without a [runner] section the scheduler runs one worker.

An input that asks for a combination the scheduler does not support is refused with an error; it is not run another way. From Python, a path-sampling run is driven the same way, with pyretis.simulation.scheduler.scheduler_cycles(). The worker count can be overridden with the environment variables below.

Keywords of the runner section

Example Runner section:

[runner]
workers = 4

This requests four parallel workers.

Table 36 Keywords for the runner section.

Keyword	Description
workers	Number of parallel workers in the scheduler pool.
files	Files pyretis tools init stages for each step.
wmdrun	Per-worker external-engine MD run commands.

Keyword workers

workers = integer

The number of parallel workers the scheduler drives. Each worker propagates one trajectory at a time and is handed new work as soon as it frees up. The coordinator takes the finished moves back one at a time and, where the engine can, recomputes the energies of every new path from its stored frames, so the wall-clock time falls close to linearly with the number of workers only while the coordinator spends little time on a move against the time a move takes; with the internal engines it spends about as long, which limits the gain from more workers. workers should not exceed the number of path ensembles (a worker per ensemble is the natural maximum).

A worker is an independent Python process with its own molecular- dynamics engine. The coordinator chooses an ensemble and one of the paths it holds, gives that trial to a free worker, and incorporates the returned accepted or rejected path. It is therefore closer to a laboratory assistant completing one trajectory assignment at a time than to a thread splitting a single trajectory. For an external engine, each worker launches its own LAMMPS / GROMACS / CP2K process; any MPI ranks or OpenMP threads used inside that engine are a separate level of parallelism and count in addition to the worker pool.

With pyretis run -p, the Monte Carlo bar reports completed sampling cycles while its live postfix reports the most recently advancing worker, ensemble, propagation leg and leg length, for example worker 2 | ensemble 004 | forward leg length 17 | cap <= 2000. maxlength is displayed as a cap rather than a percentage because a path normally stops at an interface before reaching it and regular variable-length shooting may draw a still smaller stochastic cap.

With several workers, the scheduler takes the finished moves back one at a time, in the order they finished. While it treats one move (taking in its accepted path or keeping the old one, updating the occupancies, writing its output and picking the next move), a move that finishes meanwhile waits with its ensembles locked. The time at which its paths return to the free ensembles then depends on the durations of the moves and, through them, on the paths, and the sampled occupancies deviate from the product measure. In small models solved exactly, the deviation is small when the coordinator spends little time on a move against the time a move takes, largest when the two times are comparable, and smaller again when the coordinator is much slower. The internal-engine tutorials run near a ratio of 1, the two turtlemd infinite-swapping tutorials at about 0.06 and 0.2. With two workers at most one finished move waits while the coordinator treats another; with three or more, several can. A run with one worker has none of this.

Default

The default is workers = 1 (a single-worker run, which reproduces the canonical RETIS loop).

Keyword files

files = list of strings

Read only by the automatic interface placement, pyretis tools init, which copies these files, resolved relative to the input file, into the directory of each of its short runs. The most common entry is a custom order-parameter module referenced from the orderparameter section, e.g. files = ["orderp.py"]. pyretis run refuses an input that carries this keyword.

Default

The default is an empty list (no auxiliary files are copied).

Keyword wmdrun

wmdrun = list of strings

For external MD engines (GROMACS / LAMMPS / CP2K), the per-worker command used to launch the engine. The list has one entry per worker and is indexed by the worker’s pin, so different workers can run on different devices or with different launch wrappers. It is not used by the internal in-process engines.

Default

The default is unset (the engine’s own run command is used).

Environment overrides

A few environment variables override the routing decision without editing the input file. They are reversible escape hatches, primarily for debugging and for plain-vs-scheduler reference comparisons:

Table 37 Environment variables controlling the route.

Variable	Effect
PYRETIS_WORKERS=N	Number of workers for the canonical retis scheduler route (default 1; the pre-rename spelling PYRETIS_NATIVE_WORKERS is still honoured).

Note

The permeability mirror / target swap moves route through the scheduler by default (at n_workers = 1); no opt-in is needed any more.

Output and analysis

The scheduler always writes the per-ensemble pathensemble.txt / order.txt / energy.txt files (in the numbered ensemble directories under the output data directory), so the standard pyretis analyse tooling and pyvisa can analyse a scheduler run exactly as they would a plain one. There is no native_compat setting any more (a retired legacy key) – this is the only output format.

Because the trajectories are shared fractionally across ensembles rather than collected from fixed, independent ones, the per-interface crossing probabilities and the final rate constant can also be combined with the Weighted Histogram Analysis Method (WHAM) rather than by simple per-ensemble averaging. WHAM reads the same information from the per-ensemble output (reconstructed on demand – the scheduler no longer writes a separate infswap_data.txt). See the analysis guide for how to run the WHAM crossing-probability analysis.