4. User guide¶
In this section we will describe how to run REMD simulations with RepEx on your local system.
To run examples of this section you must have Amber installed on your system.
If you don’t have Amber installed please download it from: http://ambermd.org/antechamber/download.html
and install it using instructions at: http://ambermd.org/
4.1. T-REMD example (peptide ala10) with Amber kernel¶
We will take a look at Temperature-Exchange REMD example using peptide ala10 system with Amber simulations kernel.
This guide assumes that you have already installed RepEx, if not please go back to installation section. To obtain input files, please clone repex-examples repository:
git clone https://github.com/antonst/repex.examples.git
Next you need to cd into directory where input files recide:
cd repex.examples/examples/amber
Amongst other things in this directory are present:
t_remd_inputs
- input files for T-REMD simulationst_remd_ala10.json
- REMD input file for Temperature-Exchnage example using peptide ala10 systemlocal.json
- resource configuration file to run on local system (your laptop)
4.1.1. Run locally¶
To run this example locally you need to make appropriate changes to local.json
resouce configuration file. You need to open this file in your favorite text editor (vim
in this case):
vim local.json
By default this file looks like this:
{
"target": {
"resource": "local.localhost",
"username" : "octocat",
"runtime" : "30",
"cleanup" : "False",
"cores" : "4"
}
}
You need to modify only two parameters in this file:
username
- this should be your username on your laptopcores
- change this parameter to number of cores supported by your laptop
Next you need to verify if parameters specified in t_remd_ala10.json
REMD input file satisfy
your requirements. By default t_remd_ala10.json
file looks like this:
{
"remd.input": {
"re_pattern": "S",
"exchange": "T-REMD",
"number_of_cycles": "4",
"number_of_replicas": "8",
"input_folder": "t_remd_inputs",
"input_file_basename": "ala10_remd",
"amber_input": "ala10.mdin",
"amber_parameters": "ala10.prmtop",
"amber_coordinates": "ala10_minimized.inpcrd",
"replica_mpi": "False",
"replica_cores": "1",
"min_temperature": "300",
"max_temperature": "600",
"steps_per_cycle": "4000",
"download_mdinfo": "True",
"download_mdout" : "True"
}
}
In comparison with general REMD input file format discussed above this input file contains some additional parameters:
min_temperature
- minimal temperature value to be assigned to replicasmax_temperature
- maximal temperature value to be assigned to replicas (we use geometrical progression for temperature assignment)
To run this example, all you need to do is to specify path to sander
executable on your laptop. To do that please add amber_path
parameter under remd.input
. For example:
"amber_path": "/home/octocat/amber/amber14/bin/sander"
To get notified about important events during the simulation please specify in terminal:
export RADICAL_REPEX_VERBOSE=info
Now you can run this simulation by:
repex-amber --input='t_remd_ala10.json' --rconfig='local.json'
4.1.2. Verify output¶
If simulation has successfully finished, last three lines of terminal log should be similar to:
2015:10:11 18:49:59 6600 MainThread radical.repex.amber : [INFO ] Simulation successfully finished!
2015:10:11 18:49:59 6600 MainThread radical.repex.amber : [INFO ] Please check output files in replica_x directories.
2015:10:11 18:49:59 6600 MainThread radical.repex.amber : [INFO ] Closing session.
You should see nine new directories in your current path:
- eight
replica_x
directories- one
shared_files
directory
If you want to check which replicas exchanged configurations during each cycle you can cd into
shared_files
directory and check each of four pairs_for_exchange_x.dat
files. In these files are recorded indexes of replicas exchanging configurations during each cycle.
If you want to check .mdinfo or .mdout files for some replica, you can find those files in
corresponding replica_x
directory. File format is ala10_remd_i_c.mdinfo
where:
- i is index of replica
- c is current cycle
4.2. US-REMD example using Alanine Dipeptide system with Amber kernel¶
In addition to T-REMD simulations, RepEx also supports Umbrella Sampling (biasing potentials) and Salt Concentration (ionic strength) one-dimensional REMD simulations with Amber kernel. In this section we will take a look at Umbrella Sampling - US-REMD example.
For the example we will use Alanine Dipeptide (Ace-Ala-Nme) system. To run this example locally you must have Amber installed on your system. If you don’t have Amber installed please download it from: http://ambermd.org/antechamber/download.html
and install it using instructions at: http://ambermd.org/
This guide assumes that you currently are in repex.examples/examples/amber
directory, if not
please cd into that directory:
cd repex.examples/examples/amber
Amongst other things in this directory are present:
us_remd_inputs
- input files for US-REMD simulationsus_remd_ace_ala_nme.json
- REMD input file for Umbrella Sampling REMD example using Alanine Dipeptide systemlocal.json
- resource configuration file to run on local system (your laptop)
4.2.1. Run locally¶
To run this example locally you need to make appropriate changes to local.json
resouce configuration file. We assume that you have already done this in getting started section.
Next you need to verify if parameters specified in us_remd_ace_ala_nme.json
REMD input file satisfy your requirements. By default us_remd_ace_ala_nme.json
file looks like this:
{
"remd.input": {
"re_pattern": "S",
"exchange": "US-REMD",
"number_of_cycles": "4",
"number_of_replicas": "8",
"input_folder": "us_remd_inputs",
"input_file_basename": "ace_ala_nme_remd",
"amber_input": "ace_ala_nme.mdin",
"amber_parameters": "ace_ala_nme.parm7",
"amber_coordinates_folder": "ace_ala_nme_coors",
"same_coordinates": "True",
"us_template": "ace_ala_nme_us.RST",
"replica_mpi": "False",
"replica_cores": "1",
"us_start_param": "120",
"us_end_param": "160",
"init_temperature": "300.0",
"steps_per_cycle": "2000",
"download_mdinfo": "True",
"download_mdout" : "True"
}
}
In comparison with general REMD input file format discussed in getting-started section this input file contains some additional parameters:
same_coordinates
- specifies if each replica should use an individual coordinates file. Options are:True
orFalse
. IfTrue
is selected, inamber_coordinates_folder
must be provided coordinate files for each replica. Format of coordinates file is:filename.inpcrd.x.y
, wherefilename
can be any valid python string,inpcrd
is required file extension,x
is index of replica in 1st dimension andy
is index of replica in second dimension. For one-dimensional REMD,y = 0
must be provided
us_template
- name of Restraints template fileus_start_param
- starting value of Umbrella intervalus_end_param
- ending value of Umbrella intervalinit_temperature
- initial temperature to use
To run this example, all you need to do is to specify path to sander
executable on your laptop. To do that please add amber_path
parameter under remd.input
. For example:
"amber_path": "/home/octocat/amber/amber14/bin/sander"
To get notified about important events during the simulation please specify in terminal:
export RADICAL_REPEX_VERBOSE=info
Now you can run this simulation by:
repex-amber --input='us_remd_ace_ala_nme.json' --rconfig='local.json'
4.2.2. Verify output¶
If simulation has successfully finished, last three lines of terminal log should be similar to:
2015:10:11 18:49:59 6600 MainThread radical.repex.amber : [INFO ] Simulation successfully finished!
2015:10:11 18:49:59 6600 MainThread radical.repex.amber : [INFO ] Please check output files in replica_x directories.
2015:10:11 18:49:59 6600 MainThread radical.repex.amber : [INFO ] Closing session.
You should see nine new directories in your current path:
- eight
replica_x
directories- one
shared_files
directory
If you want to check which replicas exchanged configurations during each cycle you can cd into
shared_files
directory and check each of four pairs_for_exchange_x.dat
files. In these files are recorded indexes of replicas exchanging configurations during each cycle.
If you want to check .mdinfo or .mdout files for some replica, you can find those files in
corresponding replica_x
directory. File format is ala10_remd_i_c.mdinfo
where:
- i is index of replica
- c is current cycle
4.3. TUU-REMD example (alanine dipeptide) with Amber kernel¶
In addition to one-dimensional REMD simulations, RepEx also supports multi-dimensional REMD simulations. For the Amber Kernel, we currently support two three-dimensional scenarios:
- TSU-REMD with one Temperature, one Salt Concentraiton and one Umbrella restraint dimension
- TUU-REMD with one Temperature dimension and two Umbrella restraint dimensions
For this example we will use Alanine Dipeptide (Ace-Ala-Nme) system. To run this example locally you must have Amber installed on your system.
This guide assumes that you currently are in repex.examples/examples/amber
directory, if not
please cd into that directory:
cd repex.examples/examples/amber
Amongst other things in this directory are present:
tuu_remd_inputs
- input files for TUU-REMD simulationstuu_remd_ace_ala_nme.json
- REMD input file for TUU-REMD usecase using Alanine Dipeptide systemlocal.json
- resource configuration file to run on local system (your laptop)
4.3.1. Run locally¶
To run this example locally you need to make appropriate changes to local.json
resouce configuration file. We assume that you have already done this in getting started section.
Next you need to verify if parameters specified in tuu_remd_ace_ala_nme.json
REMD input file satisfy your requirements. By default tuu_remd_ace_ala_nme.json
file looks like this:
{
"remd.input": {
"re_pattern": "S",
"exchange": "TUU-REMD",
"number_of_cycles": "4",
"input_folder": "tuu_remd_inputs",
"input_file_basename": "ace_ala_nme_remd",
"amber_input": "ace_ala_nme.mdin",
"amber_parameters": "ace_ala_nme.parm7",
"amber_coordinates_folder": "ace_ala_nme_coors",
"us_template": "ace_ala_nme_us.RST",
"replica_mpi": "False",
"replica_cores": "1",
"steps_per_cycle": "6000"
},
"dim.input": {
"umbrella_sampling_1": {
"number_of_replicas": "2",
"us_start_param": "0",
"us_end_param": "360"
},
"temperature_2": {
"number_of_replicas": "2",
"min_temperature": "300",
"max_temperature": "600"
},
"umbrella_sampling_3": {
"number_of_replicas": "2",
"us_start_param": "0",
"us_end_param": "360"
}
}
}
In comparison to REMD simulation input files used previously, this file has the following additional parameters:
dim.input
- under this key must be specified parameters and names of individual dimensions for all multi-dimensional REMD simulations.umbrella_sampling_1
- indicates that first dimension is Umbrella potentialtemperature_2
- indicates that second dimension is Temperatureumbrella_sampling_1
- indicates that third dimension is Umbrella potentialnumber_of_replicas
- indicates number of replicas in this dimension
To run this example, all you need to do is to specify path to sander
executable on your laptop. To do that please add amber_path
parameter under remd.input
. For example:
"amber_path": "/home/octocat/amber/amber14/bin/sander"
To get notified about important events during the simulation please specify in terminal:
export RADICAL_REPEX_VERBOSE=info
Now you can run this simulation by:
repex-amber --input='tuu_remd_ace_ala_nme.json' --rconfig='local.json'
4.3.2. Verify output¶
If simulation has successfully finished, last three lines of terminal log should be similar to:
2015:10:11 18:49:59 6600 MainThread radical.repex.amber : [INFO ] Simulation successfully finished!
2015:10:11 18:49:59 6600 MainThread radical.repex.amber : [INFO ] Please check output files in replica_x directories.
2015:10:11 18:49:59 6600 MainThread radical.repex.amber : [INFO ] Closing session.
You should see nine new directories in your current path:
- eight
replica_x
directories- one
shared_files
directory
If you want to check which replicas exchanged configurations during each cycle you can cd into
shared_files
directory and check each of four pairs_for_exchange_x.dat
files. In these files are recorded indexes of replicas exchanging configurations during each cycle.
If you want to check .mdinfo or .mdout files for some replica, you can find those files in
corresponding replica_x
directory. File format is ala10_remd_i_c.mdinfo
where:
- i is index of replica
- c is current cycle