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 – 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, the interfaces list in the [simulation] section and the shooting_moves list in the [tis] section. Wire Fencing ("wf") pairs naturally with this sampler because it keeps acceptance high on the long paths that aggressive parallel sampling produces.

  • Run: pyretis run -i infswap.toml from the tutorial folder (bash runner.sh runs the same command). The input sets [initial-path] method = "kick": the run generates its initial paths by kicking from the initial configuration, and keeps the live trajectories of each ensemble in <ensemble>/<load_dir>/<path number> ([simulation] load_dir, default accepted). The bundled load_copy/, which runner.sh copies to load/, is not read by this input. A new run stops when the folder holds the output of an earlier run that sampled cycles: remove that output with pyretis tools clean first (runner.sh does not).

  • Analyse: pyretis analyse -i infswap.toml after the run. It gives the crossing probability of each ensemble and their product, as for any RETIS run; to combine the ensembles with the WHAM analysis [2] instead, add [analysis] method = "wham" to the input ("both" gives the two).

  • Expected output: the per-ensemble pathensemble.txt / order.txt / energy.txt files that every path-sampling run writes, so the regular analysis tooling and pyvisa work on an infinite-swapping run as on any other.

Selecting the route

Every path-sampling run (task = "tis", "retis", "explore", "pptis" or "repptis") is started with the single pyretis run command and runs on the infinite-swapping scheduler, with any engine. Without a [runner] section the scheduler runs one worker, so a plain RETIS input and its parallel infinite-swapping counterpart differ only by the [runner] section. A canonical input that sets task = "infinite_swapping" (or "infswap" or "infretis") is refused: set the path-sampling task, e.g. task = "retis" (see Migration guide: legacy commands and inputs to the unified CLI).

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

[runner]
workers = 4

The workers load the order-parameter module that [orderparameter] module names; nothing else needs to be listed ([runner] files is a keyword of pyretis tools init, and a run refuses it). See the runner section reference for the full keyword list and for the PYRETIS_WORKERS environment override.

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); the second one is an engine pool: the [0^-] ensemble runs with [engine0], and the [0^+] and [1^+] ensembles with [engine1], one engine section per ensemble in [simulation] ensemble_engines.

  • 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.

examples/tutorials/extending/basic_runner.py shows the worker pool of the scheduler on its own, handing a toy task to five workers from Python.

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/. The validation study under examples/validation/ checks that the sampling strategies, the random-number generators, several workers and infinite swapping analysed with WHAM give the same rate on one system. Use those fixtures as the short regression checks and this page as the user-facing guide.

References