# ∞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](https://github.com/infretis/infretis) 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](https://doi.org/10.1073/pnas.2318731121)

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