Replica exchange simulations

The lib/replica/ directory contains Tcl scripts that implement replica exchange both for parallel tempering (temperature exchange) and umbrella sampling (exchanging collective variable biases). This replaces the old Tcl server and socket connections driving a separate NAMD process for every replica used in the simulation.

A NAMD build based on Charm++ 6.5.0 or later using one of the ``LRTS'' (low-level runtime system) machine layers is required! Current LRTS machine layers include mpi, netlrts, verbs (for InfiniBand), gemini_gni-crayxe, gni-crayxc, and pamilrts-bluegeneq.

Only temperature-exchange simulations are described below. To employ replicas for umbrella sampling you will need to understand this material, collective variable-based calculations (Sec. 10), and basic Tcl programming to adapt the examples in lib/replica/umbrella/ and lib/replica/umbrella2d/ until further documentation and a tutorial are available.

This implementation is designed to be modified to implement exchanges of parameters other than temperature or via other temperature exchange methods. The scripts should provide a good starting point for any simulation method requiring a number of loosely interacting systems.

Replica exchanges and energies are recorded in the .history files written in the output directories. These can be viewed with, e.g., ``xmgrace output/*/*.history'' and processed via awk or other tools. There is also a script to load the output into VMD and color each frame according to replica index. An example simulation folds a 66-atom model of a deca-alanine helix in about 10ns.

replica.namd is the master script for replica temperature-exchange simulations. To run:

          cd example
          mkdir output
          (cd output; mkdir 0 1 2 3 4 5 6 7)
          mpirun namd2 +replicas 8 job0.conf +stdout output/%d/job0.%d.log
          mpirun namd2 +replicas 8 job1.conf +stdout output/%d/job1.%d.log

The number of MPI ranks must be a multiple of the number of replicas (+replicas). Be sure to increment jobX for +stdout option on command line.

show_replicas.vmd is a script for loading replicas into VMD; first source the replica exchange conf file and then this script, then repeat for each restart conf file or for example just do ``vmd -e load_all.vmd''. This script will likely destroy anything else you are doing in VMD at the time, so it is best to start with a fresh VMD. clone_reps.vmd provides the clone_reps commmand to copy graphical representation from the top molecule to all other molecules.

sortreplicas, found in the namd2 binary directory, is a program to un-shuffle replica trajectories to place same-temperature frames in the same file. Usage:

  sortreplicas <job_output_root> <num_replicas> <runs_per_frame> [final_step]

where job_output_root is the job specific output base path, including %s or %d for separate directories as in output/%s/fold_alanin.job1 This will be extended with .%d.dcd .%d.history for input files and .%d.sort.dcd .%d.sort.history for output files. The optional final_step parameter will truncate all output files after the specified step, which is useful in dealing with restarts from runs that did not complete. Colvars trajectory files are similarly processed if they are found.

A replica exchange config file should define the following Tcl variables:

• num_replicas, the number of replica simulations to use,
• min_temp, the lowest replica target temperature,
• max_temp, the highest replica target temperature,
• steps_per_run, the number of steps between exchange attempts,
• num_runs, the number of runs before stopping (should be divisible by runs_per_frame $\times$ frames_per_restart).
• runs_per_frame, the number of runs between trajectory outputs,
• frames_per_restart, the number of frames between restart outputs,

• namd_config_file, the NAMD config file containing all parameters, needed for the simulation except seed, langevin, langevinTemp, outputEnergies, outputname, dcdFreq, temperature, bincoordinates, binvelocities, or extendedSystem, which are provided by replica.namd,

• output_root, the directory/fileroot for output files, optionally including a ``%s'' that is replaced with the replica index to use multiple output directories,

• psf_file, the psf file for show_replicas.vmd,
• initial_pdb_file, the initial coordinate pdb file for show_replicas.vmd,
• fit_pdb_file, the coodinates that frames are fit to by show_replicas.vmd (e.g., a folded structure),

The lib/replica/example/ directory contains all files needed to fold a 66-atom model of a deca-alanine helix:

• alanin_base.namd, basic config options for NAMD,
• alanin.params, parameters,
• alanin.psf, structure,
• unfolded.pdb, initial coordinates,
• alanin.pdb, folded structure for fitting in show_replicas.vmd,
• fold_alanin.conf, config file for replica_exchange.tcl script,
• job0.conf, config file to start alanin folding for 10ns,
• job1.conf, config file to continue alanin folding another 10ns, and
• load_all.vmd, load all output into VMD and color by replica index.

The fold_alanin.conf config file contains the following settings:

set num_replicas 8
set min_temp 300
set max_temp 600
set steps_per_run 1000
set num_runs 10000
# num_runs should be divisible by runs_per_frame * frames_per_restart
set runs_per_frame 10
set frames_per_restart 10
set namd_config_file "alanin_base.namd"
set output_root "output/%s/fold_alanin" ; # directories must exist

# the following used only by show_replicas.vmd
set psf_file "alanin.psf"
set initial_pdb_file "unfolded.pdb"
set fit_pdb_file "alanin.pdb"