Infinite swapping in PyRETIS

This page documents PyRETIS’s asynchronous infinite-swapping sampler. The method originated in the upstream ∞RETIS repository and is now part of the unified PyRETIS path-sampling scheduler. The input TOML selects parallel infinite swapping via [simulation] task = "infinite_swapping" or a [runner] section. The old separate infretisrun command has been removed.

For the command and input overview, see README.rst. MERGE_TODO.md is the historical record of the completed source-tree merge.

What ∞RETIS adds on top of classical RETIS

∞RETIS is an extension of Replica Exchange Transition Interface Sampling (RETIS) that targets two specific 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. ∞RETIS replaces the 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.

References

If you use the ∞RETIS code path 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

@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/.