# 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:

```bash
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](https://doi.org/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.

```bibtex
@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](https://doi.org/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](https://doi.org/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](https://doi.org/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](https://doi.org/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/`.