.. _examples-infswap:

Infinite swapping (parallel replica exchange)
=============================================

This example shows how to run the **infinite-swapping** sampler -- the
asynchronous, highly parallel reformulation of replica exchange of Zhang,
Baldauf, Roet, Lervik and van Erp [1]_. Instead of attempting swaps
between fixed neighbouring path-ensemble pairs at a synchronisation
point, a central coordinator records swap statistics over the running
stream of completed trajectories and a pool of **workers** draws its next
task from the resulting distribution. This keeps the wall-clock time
scaling close to linearly with the number of workers over a far wider
range than synchronous replica exchange allows, which is what makes it
the route of choice for large, parallel rate-constant calculations.

The input keywords used here -- the ``[runner]`` section and the two
execution routes -- are documented in the
:ref:`runner section reference <user-section-runner>`. The sampler itself
is introduced in :ref:`the moves guide <user-guide-path-move-types>`.

**Verification status:** smoke -- see :ref:`example-test-status`.


Tutorial quick start
--------------------

* **Best starting point:**
  :file:`examples/infswap/turtlemd/double_well/` (the internal TurtleMD
  engine, so no external MD installation is required).
* **Edit first:** the ``workers`` count in the ``[runner]`` section and
  the ``interfaces`` / ``shooting_moves`` lists in the ``[simulation]``
  section. Wire Fencing (``"wf"``) pairs naturally with this sampler
  because it keeps acceptance high on the long paths that aggressive
  parallel sampling produces.
* **Run:** ``bash runner.sh`` from the tutorial folder -- it seeds the
  ``load/`` folder from the bundled ``load_copy/`` and then calls
  ``pyretisrun -i infswap.toml``.
* **Analyse:** ``pyretisanalyse -i infswap.toml`` after the run, which
  combines the per-interface crossing probabilities with the **WHAM**
  analysis [2]_ rather than per-ensemble averaging.
* **Expected output:** ``infswap_data.txt`` with the swap statistics, and
  -- when ``native_compat = true`` is set in the ``[output]`` section --
  the standard per-ensemble ``pathensemble.txt`` / ``order.txt`` /
  ``energy.txt`` files for the regular analysis tooling.


Selecting the route
-------------------

Every RETIS-family run is driven through the single ``pyretisrun``
command; |pyretis| reads the input TOML and picks the route:

* An input with a ``[runner]`` section -- or an explicit
  ``[simulation] task = "infinite_swapping"`` -- runs through the
  **infinite-swapping scheduler** with the requested number of workers.
* A native ``task = "retis"`` input with an internal engine is also run
  through the scheduler, at a single worker, so a plain RETIS input and
  its parallel infinite-swapping counterpart differ only by the
  ``[runner]`` section.

The minimal addition that turns a single-worker RETIS run into a
four-worker infinite-swapping run is therefore just:

.. code-block:: toml

   [runner]
   workers = 4
   files = ["orderp.py"]   # custom order-parameter module each worker needs

See the :ref:`runner section reference <user-section-runner>` for the full
keyword list and for the ``PYRETIS_NATIVE_LOOP`` / ``PYRETIS_NATIVE_WORKERS``
environment overrides.


Other engines
-------------

The same input shape drives the external engines. Ready-to-read
references ship alongside the TurtleMD example:

* :file:`examples/infswap/gromacs/H2` and
  :file:`examples/infswap/gromacs/H2_multi_engine` -- GROMACS (requires
  ``gmx`` on the ``PATH``).
* :file:`examples/infswap/lammps/H2` -- LAMMPS.
* :file:`examples/infswap/cp2k/H2` -- CP2K.
* :file:`examples/infswap/ase/H2` -- an ASE TOML reference.

A minimal programmatic driver that runs the asyncrunner without the CLI
is at :file:`examples/infswap/basic/basic_runner.py`.


Tested by
---------

The infinite-swapping examples under :file:`examples/infswap/` are
exercised by the integration suite in :file:`test/infswap/` and the
native-via-scheduler round trip in
:file:`test/integration/test_native_via_infswap.py`. The cross-route rate
equivalence (native loop vs. scheduler) is checked by the validation
study under :file:`examples/validation/`. Use those fixtures as the short
regression checks and this page as the user-facing guide.


References
----------

.. [1] D. T. Zhang, L. Baldauf, S. Roet, A. Lervik and T. S. van Erp,
   *Highly parallelizable path sampling with minimal rejections using
   asynchronous replica exchange and infinite swaps*, Proc. Natl. Acad.
   Sci. U.S.A. **121**, e2318731121 (2024),
   https://doi.org/10.1073/pnas.2318731121

.. [2] S. Kumar, J. M. Rosenberg, D. Bouzida, R. H. Swendsen and
   P. A. Kollman, *The weighted histogram analysis method for
   free-energy calculations on biomolecules. I. The method*, J. Comput.
   Chem. **13**, 1011-1021 (1992), https://doi.org/10.1002/jcc.540130812