Infinite swapping in PyRETIS

This page documents PyRETIS’s asynchronous infinite-swapping sampler. It is part of the unified PyRETIS path-sampling scheduler, and the input TOML selects parallel infinite swapping via [simulation] task = "infinite_swapping" or a [runner] section.

For the command and input overview, see README.rst.

Asynchronous infinite swapping and classical RETIS

Asynchronous infinite swapping extends Replica Exchange Transition Interface Sampling (RETIS) to address two bottlenecks of the classical algorithm:

  1. Acceptance rate of long subtrajectory moves. Classical RETIS relies on shooting moves whose acceptance falls off sharply as the path length grows. The wire-fencing move replaces the single shooting point with a coordinated multi-point reshape that keeps acceptance high even on long paths.

  2. Wall-clock cost of replica exchange. The standard REPEX swap is a synchronisation point — every worker must finish its current trajectory before swaps can be evaluated. The asynchronous scheme replaces synchronous swap with an asynchronous infinite-swap scheme: the central coordinator records swap acceptance statistics over a running stream of completed trajectories, lets each worker draw its next task from the resulting distribution, and dispatches work as soon as a worker frees up. Wall-clock scaling with the number of workers stays close to linear over a much wider range than synchronous REPEX allows.

In PyRETIS these two ideas show up as:

  • wf shooting moves in simulation.shooting_moves (the wire-fencing implementation), implemented in pyretis/core/moves.py.

  • The InfSwapState coordinator in pyretis/simulation/repex.py, together with the asyncio runner in pyretis/simulation/async_runner.py.

  • The [runner] and [simulation.tis_set] sections of the runner TOML schema (see test/infswap/simulations/data/wf.toml for an exemplar config).

When to reach for it

There is a single CLI, pyretis (the run sub-command), and one path-sampling scheduler. The input TOML decides how that scheduler runs.

  • Select the infinite-swapping path (TOML with [simulation] task = "infinite_swapping" or a [runner] section) when you need parallel sampling, want infinite-swap REPEX, or want the wf shooting move. The multi-engine pool API (see assign_engines in pyretis/engines/factory.py) is part of this path.

  • Use a canonical TOML for single-worker RETIS / TIS runs, custom Python order parameters, or the existing tutorials under examples/tutorials/. Non-path MD and flux tasks use their dedicated in-process runners.

Both input dialects are installed by the same pip install pyretis, run through pyretis run, and produce the same per-ensemble output format.

Migration and archival compatibility

PyRETIS can translate runner-style TOML inputs created for earlier infRETIS workflows, as well as older PyRETIS .rst inputs, to the current PyRETIS TOML schema. For a reusable production input, convert it explicitly and retain the converted file with the simulation record:

python -m pyretis.tools.convert_legacy_dialect input.toml
python -m pyretis.tools.convert_settings input.rst

The converters validate the translated configuration before writing it. The analysis tools also recognise archived infinite-swapping output under its earlier filename, so previously completed simulations remain analysable. The :doc:migration guide <examples/examples-migration> gives the mapping between the input forms.

References

If you use PyRETIS infinite swapping in your research, please cite:

  • Zhang, Baldauf, Roet, Lervik, van Erp, Highly parallelizable path sampling with minimal rejections using asynchronous replica exchange and infinite swaps, PNAS 121, e2318731121 (2024). doi:10.1073/pnas.2318731121

For a calculation translated from an earlier implementation, cite this method paper and the PyRETIS software paper below, and report the PyRETIS version and translated input used for the production run.

@article{zhang_highly_2024,
    title   = {Highly parallelizable path sampling with minimal rejections
               using asynchronous replica exchange and infinite swaps},
    volume  = {121},
    url     = {https://www.pnas.org/doi/10.1073/pnas.2318731121},
    doi     = {10.1073/pnas.2318731121},
    number  = {7},
    journal = {Proceedings of the National Academy of Sciences},
    author  = {Zhang, Daniel T. and Baldauf, Lukas and Roet, Sander
               and Lervik, Anders and van Erp, Titus S.},
    year    = {2024},
}

Foundational papers on the methods themselves:

  • van Erp, Moroni, Bolhuis, A novel path sampling method for the calculation of rate constants, J. Chem. Phys. 118, 7762 (2003) — the original TIS paper. doi:10.1063/1.1562614

  • van Erp, Reaction Rate Calculation by Parallel Path Swapping, Phys. Rev. Lett. 98, 268301 (2007) — the original RETIS paper. doi:10.1103/PhysRevLett.98.268301

  • Zhang, Riccardi, van Erp, Enhanced path sampling using subtrajectory Monte Carlo moves, J. Chem. Phys. 158, 024113 (2023) — wire-fencing move. doi:10.1063/5.0127249

  • Lervik, Riccardi, van Erp, PyRETIS: A well-done, medium-sized python library for rare events, J. Comput. Chem. 38, 2439 (2017) — original PyRETIS paper. doi:10.1002/jcc.24900

Examples

Runnable examples for the infinite-swapping path live under examples/tutorials/path_sampling/<engine>/<system>/infinite_swapping/ — each engine (turtlemd, gromacs, lammps, cp2k, ase) has its own sub-directory with an infswap.toml config and a small driver script. The TurtleMD examples need no external MD installation and are the recommended starting point.

For aggregate-observable comparisons against canonical references, see test/infswap/simulations/.