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/infswap/turtlemd/double_well/ (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 load/ folder from the bundled load_copy/ and then calls pyretisrun -i infswap.toml.

  • Analyse: pyretisanalyse -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: infswap_data.txt with the swap statistics, and – when native_compat = true is set in the [output] section – the standard per-ensemble pathensemble.txt / order.txt / energy.txt files for the regular analysis tooling.

Selecting the route

Every RETIS-family run is driven through the single pyretisrun 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 native 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_NATIVE_WORKERS environment overrides.

Other engines

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

  • examples/infswap/gromacs/H2 and examples/infswap/gromacs/H2_multi_engine – GROMACS (requires gmx on the PATH).

  • examples/infswap/lammps/H2 – LAMMPS.

  • examples/infswap/cp2k/H2 – CP2K.

  • examples/infswap/ase/H2 – an ASE TOML reference.

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

Tested by

The infinite-swapping examples under examples/infswap/ are exercised by the integration suite in test/infswap/ and the native-via-scheduler round trip in test/integration/test_native_via_infswap.py. The cross-route rate equivalence (native 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