Infinite swapping (parallel replica exchange)

This example shows how to run the infinite-swapping sampler – the asynchronous, highly parallel reformulation of replica exchange of Zhang, Baldauf, Roet, Lervik and van Erp [1]. Instead of attempting swaps between fixed neighbouring path-ensemble pairs at a synchronisation point, a central coordinator records swap statistics over the running stream of completed trajectories and a pool of workers draws its next task from the resulting distribution. This keeps the wall-clock time scaling close to linearly with the number of workers over a far wider range than synchronous replica exchange allows, which is what makes it the route of choice for large, parallel rate-constant calculations.

The input keywords used here – the [runner] section and the two execution routes – are documented in the runner section reference. The sampler itself is introduced in the moves guide.

Verification status: smoke – see Example test status.

Tutorial quick start

  • Best starting point: examples/tutorials/path_sampling/turtlemd/1D-double-well/infinite_swapping/ (the internal TurtleMD engine, so no external MD installation is required).

  • Edit first: the workers count in the [runner] section and the interfaces / shooting_moves lists in the [simulation] section. Wire Fencing ("wf") pairs naturally with this sampler because it keeps acceptance high on the long paths that aggressive parallel sampling produces.

  • Run: bash runner.sh from the tutorial folder – it seeds the starting paths from the bundled load_copy/ and then calls pyretis run -i infswap.toml. A run keeps its live trajectories in a per-ensemble archive (<ensemble>/<load_dir>/<path number>, load_dir defaulting to accepted); a flat, top-level staged load directory (the historical layout the bundled load_copy/ mirrors) is still read as input via the legacy-layout fallback.

  • Analyse: pyretis analyse -i infswap.toml after the run, which combines the per-interface crossing probabilities with the WHAM analysis [2] rather than per-ensemble averaging.

  • Expected output: the standard per-ensemble pathensemble.txt / order.txt / energy.txt files (this is the only output format the scheduler writes; there is no native_compat setting any more), so the regular analysis tooling and pyvisa work on an infinite-swapping run exactly as they would on a native one.

Selecting the route

Every RETIS-family run is driven through the single pyretis run command; PyRETIS reads the input TOML and picks the route:

  • An input with a [runner] section – or an explicit [simulation] task = "infinite_swapping" – runs through the infinite-swapping scheduler with the requested number of workers.

  • A canonical task = "retis" input with an internal engine is also run through the scheduler, at a single worker, so a plain RETIS input and its parallel infinite-swapping counterpart differ only by the [runner] section.

The minimal addition that turns a single-worker RETIS run into a four-worker infinite-swapping run is therefore just:

[runner]
workers = 4
files = ["orderp.py"]   # custom order-parameter module each worker needs

See the runner section reference for the full keyword list and for the PYRETIS_NATIVE_LOOP / PYRETIS_WORKERS environment overrides.

Other engines

The same input shape drives the external engines. Ready-to-read references ship alongside the TurtleMD example:

  • examples/tutorials/path_sampling/gromacs/H2/infinite_swapping and examples/tutorials/path_sampling/gromacs/H2/infinite_swapping_multi_engine – GROMACS (requires gmx on the PATH).

  • examples/tutorials/path_sampling/lammps/H2/infinite_swapping – LAMMPS.

  • examples/tutorials/path_sampling/cp2k/H2/infinite_swapping – CP2K.

  • examples/tutorials/path_sampling/ase/H2/infinite_swapping – an ASE TOML reference.

A minimal programmatic driver that runs the asyncrunner without the CLI is at examples/tutorials/extending/basic_runner.py.

Tested by

The per-engine infinite-swapping examples (examples/tutorials/path_sampling/<engine>/<system>/infinite_swapping/) are exercised by the integration suite in test/infswap/ and the native-via-scheduler round trip in test/integration/test_via_scheduler.py. The cross-route rate equivalence (in-process loop vs. scheduler) is checked by the validation study under examples/validation/. Use those fixtures as the short regression checks and this page as the user-facing guide.

References