∞RETIS — the infretis-flavour method in PyRETIS

This page documents the infretis-flavour code path that lives alongside pyretis-native inside this repository. The implementation was ported from the upstream ∞RETIS repository and is now driven by the single pyretis CLI (see pyretis/bin/cli.py): the input TOML selects the infinite-swapping sampler via [simulation] task = "infinite_swapping" or a [runner] section. The old separate infretisrun command has been removed.

For background on the broader pyretis-native code path, see README.rst. For the ongoing alignment roadmap between the two implementations, see MERGE_TODO.md.

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/_tis_inf.py.

  • The REPEX_state 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 infretis-flavour 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); the input TOML decides which code path 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 classical TOML for single-worker RETIS / TIS / MD-flux runs, custom Python order parameters, MD-only ensembles, or any of the existing tutorials under examples/tutorials/.

Both paths are installed by the same pip install pyretis and run through the same pyretis run. They share types where it makes sense and diverge where the algorithmic needs differ; today they are not fully unified — see MERGE_TODO.md §3 (type alignment) and §5 (promoting inf-only features into pyretis-native namespace).

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/infswap/ — 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/.