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 examples/infswap/.

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/infswap/turtlemd/double_well/infswap.toml.

The two execution routes

Every RETIS-family run is driven through the single pyretis run command. PyRETIS inspects the input TOML and selects one of two routes:

• The infinite-swapping scheduler – a central coordinator hands work to a pool of parallel workers and combines the result with the WHAM analysis. It is selected when the input carries a [runner] section or an explicit infinite-swapping task (task = "infinite_swapping", "infswap" or "infretis").

• The native in-process loop – the classic single-process PathSimulation loop, used for everything else.

As of the current release a native task = "retis" TOML with an internal (in-process) MD engine is also run through the scheduler at a single worker, because the infinite-swapping scheduler reproduces the native RETIS loop one-to-one for that family. Native task = "tis", "explore", "pptis" and "repptis", the external-engine retis runs, and any retis config that hits a scheduler port gap keep the in-process loop. These routing decisions can be overridden with the environment variables below.

Keywords of the runner section

Example Runner section:

[runner]
workers = 4
files = ["orderp.py"]

This requests four parallel workers and copies the custom order-parameter module orderp.py into each worker’s run directory.

Table 33 Keywords for the runner section.

Keyword	Description
workers	Number of parallel workers in the scheduler pool.
files	Auxiliary files copied into every worker directory.
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, so the wall-clock time scales close to linearly with the number of workers. workers should not exceed the number of path ensembles (a worker per ensemble is the natural maximum).

Default

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

Keyword files

files = list of strings

Auxiliary files that each worker needs in its run directory, resolved relative to the input file. The most common entry is a custom order-parameter module referenced from the orderparameter section, e.g. files = ["orderp.py"].

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 native-vs-scheduler reference comparisons:

Table 34 Environment variables controlling the route.

Variable	Effect
PYRETIS_NATIVE_LOOP=1	Force native tis / retis to keep the in-process loop instead of the scheduler.
PYRETIS_NATIVE_WORKERS=N	Number of workers for the native retis scheduler route (default 1).

Note

The permeability mirror / target swap moves now route through the scheduler by default (at n_workers = 1); the former PYRETIS_NATIVE_VIA_INFSWAP opt-in is gone.

Output and analysis

The scheduler always writes the native 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 native one. There is no native_compat setting any more – 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 native 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.