InfRETIS in AMS¶

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.

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

• Index