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 (pyretisrun -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 pyretisrun 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 32 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 33 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).
PYRETIS_NATIVE_VIA_INFSWAP=1	Opt a native config into the scheduler for the permeability (mirror / target swap) moves, whose references are not yet regenerated for the scheduler route.

Output and analysis

The scheduler writes its swap statistics to infswap_data.txt in the output data directory. Setting native_compat = true in the [output] section additionally makes the coordinator emit the native per-ensemble pathensemble.txt / order.txt / energy.txt files, so the standard pyretisanalyse tooling can analyse a scheduler run exactly as it would a native one.

Because the trajectories are no longer collected from fixed, independent ensembles, the per-interface crossing probabilities and the final rate constant are combined with the Weighted Histogram Analysis Method (WHAM) rather than by simple per-ensemble averaging. See the analysis guide for how to run the WHAM crossing-probability analysis.