InfRETIS in AMS
***************

InfRETIS is a Python-based path sampling tool for studying rare events
in molecular simulations, such as chemical reactions, conformational
changes, or diffusion processes. It implements the Replica Exchange
Transition Interface Sampling (RETIS) method with high-efficiency
moves like Wire Fencing, combined with asynchronous replica exchange
parallelization for optimal computational performance.

InfRETIS is integrated with the AMS molecular dynamics (MD) driver and
can work with any of the AMS engines (e.g., ForceField, ReaxFF, DFTB,
MOPAC, ADF, BAND). By placing interfaces along a reaction coordinate
(order parameter), InfRETIS efficiently samples rare transitions that
would be impractical to observe with conventional molecular dynamics.

See also:

  * Example: Water dimer dissociation documentation (complete working
    example)

  * Detailed InfRETIS tutorial on GitHub

  * Original InfRETIS publication: Highly parallelizable path sampling
    with minimal rejections using asynchronous replica exchange and
    infinite swaps


Installation
============

InfRETIS is installed via the AMS package manager. From the command
line:

   $AMSBIN/amspackages install infretis

Or through the AMSpackages GUI: **SCM → Packages** menu in AMSjobs.

This installs InfRETIS and the "inftools" analysis package into an
isolated Python environment managed by AMS.


Overview of a Path Sampling Calculation
=======================================

An InfRETIS calculation consists of three main steps:

1. **Preparation**: Run unbiased MD to characterize the stable states
   (A and B) and determine appropriate interface placement along the
   order parameter.

2. **Initialization**: Generate initial reactive paths connecting
   states A and B. This can be done using the "inftools" InfInit tool
   or by other methods such as biased MD with PLUMED (as included in
   AMS).

3. **Production**: Run the RETIS simulation to sample paths and
   compute reaction rates using the Weighted Histogram Analysis Method
   (WHAM).


Input Files
===========

An InfRETIS simulation requires the following input files:

infretis.toml
   The main configuration file defining simulation parameters,
   interfaces, order parameter, and engine settings.

ams_inp/
   Directory containing the AMS engine input file "ams.inp" and
   initial geometry "initial.rkf".

load/
   Directory containing initial trajectories for each ensemble. These
   can be obtained from the initialization step.


Running InfRETIS
================

The "infretisrun" command is executed through the AMS "uv_scm"
wrapper:

   export NSCM=1                    # MPI ranks per InfRETIS worker
   export OMP_NUM_THREADS=1          # OpenMP threads per MPI rank
   $AMSBIN/uv_scm run infretis exec infretisrun -i infretis.toml

For analysis using the Weighted Histogram Analysis Method (WHAM):

   $AMSBIN/uv_scm run infretis exec inft wham


Configuration File (infretis.toml)
==================================

The "infretis.toml" file is the central configuration for an InfRETIS
simulation. Key sections include:

**Simulation settings:**

   [simulation]
   interfaces = [0.30, 0.35, 0.40, 0.45, 0.50]  # Values defining interfaces along order parameter
   steps = 100                                   # Number of RETIS moves (Monte Carlo steps)
   seed = 0                                      # Random number seed (0 = use random seed)
   load_dir = 'load'                             # Directory containing initial path(s)
   shooting_moves = ['sh', 'sh', 'wf', 'wf', 'wf']  # Move type for each ensemble

The "interfaces" array defines the values of the order parameter that
separate different ensembles. With N interfaces, there are N+1
ensembles (labeled [0-], [0+], [1], [2], etc.). The "shooting_moves"
list specifies the type of shooting move for each ensemble: "sh" for
standard shooting or "wf" for Wire Fencing moves.

**TIS settings:**

   [simulation.tis_set]
   maxlength = 20000      # Maximum path length in number of MD steps
   aimless = true         # Use aimless shooting (randomize velocities at shooting point)
   allowmaxlength = false # If true, accept paths that reach maxlength; if false, reject them
   zero_momentum = true   # Remove center-of-momentum momentum after generating velocities
   temperature = 300      # Target temperature in Kelvin

**InfRETIS engine configuration for AMS:**

   [engine]
   class = 'ams'         # Engine class identifier (always 'ams' for AMS)
   engine = 'ams'        # Engine name
   timestep = 0.001      # MD timestep in ps; must match TimeStep in ams.inp
   input_path = 'ams_inp'  # Directory containing ams.inp and initial.rkf
   subcycles = 5         # Number of MD steps per InfRETIS subtrajectory

The "timestep" value must match the "TimeStep" specified in your
"ams.inp" file (converted to picoseconds; 1 fs = 0.001 ps). The
"subcycles" setting determines how many MD steps are executed between
checks of the order parameter.

**Order parameter:**

   [orderparameter]
   class = 'Distance'    # Order parameter type
   index = [0, 3]        # Atom indices (0-based) defining the order parameter
   periodic = false      # Whether to apply minimum image convention for periodic systems

Available built-in order parameters include "Distance", "Angle",
"Dihedral", and more. Custom Python-based order parameters are also
supported.

**Parallel execution settings:**

   [runner]
   workers = 2           # Number of parallel workers (asynchronous tasks)

The "workers" setting controls how many trajectories are generated in
parallel. The optimal number is typically around half of the number of
ensembles.


AMS Engine Input
================

The "ams_inp/ams.inp" file contains standard AMS input defining the
system and selecting the engine. MD settings are specified in the
"MolecularDynamics" block. The "TimeStep" must match the "timestep" in
"infretis.toml" (note the unit conversion - femtoseconds in ams.inp,
picoseconds in TOML):

   MolecularDynamics
       TimeStep 1.0                              # in fs; matches timestep=0.001 in TOML
       Thermostat Type=none
       InitialVelocities Type=Random Temperature=300
   End

   System
       Atoms [A]
          ...
       End
   End

   Engine ForceField
       Type GAFF
   EndEngine

The engine can be any AMS engine (ForceField, ReaxFF, DFTB, MOPAC,
ADF, BAND, etc.).


Parallel Execution
==================

InfRETIS uses asynchronous replica exchange to parallelize path
sampling. Each worker runs trajectories independently, and accepted
paths are exchanged between ensembles. Each worker can itself be
parallelized using MPI (for most engines) and/or OpenMP (for the
ReaxFF engine only). The parallelism is controlled by:

   [runner]
   workers = 2           # Number of InfRETIS workers

   export NSCM=1             # Number of MPI ranks of AMS per worker
   export OMP_NUM_THREADS=1  # OpenMP threads per MPI rank


Analysis with inftools
======================

The "inftools" package provides analysis utilities for InfRETIS
simulations.

**Calculate rate constants with WHAM:**

   $AMSBIN/uv_scm run infretis exec inft wham

This produces crossing probabilities and rate constants in the "wham/"
directory:

* "wham/Pcross.txt" – Crossing probabilities between interfaces

* "wham/pathlengths.txt" – Average path lengths per ensemble


Getting Started
===============

A minimal workflow for running InfRETIS consists of:

1. **Prepare inputs**: Create "ams_inp/ams.inp" with your system and
   engine settings, and place "initial.rkf" in "ams_inp/".

2. **Configure**: Create "infretis.toml" with appropriate interfaces,
   order parameter, and settings matching your ams.inp.

3. **Initialize**: Generate initial paths for the "load/" directory
   using InfInit or other initialization methods.

4. **Run simulation**:

      export NSCM=1
      $AMSBIN/uv_scm run infretis exec infretisrun -i infretis.toml

5. **Analyze results**:

      $AMSBIN/uv_scm run infretis exec inft wham

For a complete working example, see the water dimer dissociation
example.


Examples
========

This section contains worked examples showing how to run InfRETIS path
sampling calculations.

* Examples


References
==========

If you use InfRETIS in your research, please cite:

D.T. Zhang, L. Baldauf, S. Roet, A. Lervik, T.S. 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
