Tutorial 1: Launching a REXEE simulation

In this tutorial, we will show how one can launch an ensemble of expanded ensemble simulations in parallel using functions in ensemble_md. To this end, we will at least need 4 files: one top file (sys.top) and one gro file (sys.gro) for the system of interest, one mdp file as the template for customizing mdp files for different replicas (expanded.mdp), and finally a yaml file speciying the REXEE-relevant parameters (params.yaml).

In our case, the system of interest is a linear model composed of 4 interaction sites, where the first and last atom have a charge of +0.2 and -0.2, respectively. In expanded.mdp, we define 9 alchemical states in total to decouple the van der Waals interactions and coulombic interactions. Our goal is to run an ensemble composed of 4 replicas of expanded ensemble, each of which sample 6 alchemical states, with the shift between adjacent replicas being 1 state. That is, we want replicas 0 to 3 to sample states 0 to 6, 1 to 7, 2 to 8, and 3 to 9, respectively. Each replica will be performed for 5 iterations, with the length of each iteration being 500 steps (i.e. 1 ps). We will use the Metropolis MC scheme to swap replicas, and use exponential averaging with histogram correction for combining weights of exchanging replicas. The histogram cutoff will be set as 1000 to avoid overcorrection and we will swap 2 pairs of replicas in each attempt when possible. All STDOUT will be redirected to results.txt.

To have all these settings, we should have a yaml file with the following content.

# User-defined parameters
parallel: True               # Whether the replicas of EXEE should be run in parallel or not
n_sim: 4                     # Number of replica simulations
n_iterations: 5              # Number of iterations
s: 1                         # Shift in λ ranges (e.g. s = 2 if λ_2 = (2, 3, 4) & λ_3 = (4, 5, 6))
nst_sim: 500                 # Number of simulation steps for each homogeneous replica
mdp: 'expanded.mdp'          # The MDP template that has the whole range of λ values
mc_scheme: 'metropolis'      # The method for swapping simulations. Choices include "same_state", "metropolis", and "metropolis-eq".
w_scheme: 'hist-exp-avg'     # The method for combining weights. Choices include "None" (unspecified), exp_avg, ...
N_cutoff: 1000               # The histogram cutoff. Only required if histo-exp-avg is used.
n_pairs: 2                   # Number of pairs of simulations to be swapped in each attempt.
outfile: 'results.txt'       # The output file for logging how replicas interact with each other.