MMTSB
Tool Set Documentation

Difference between revisions of "aarex.pl"

From MMTSB
Jump to: navigation, search
(eKkoavHMxkGCDcpGO)
 
(176 intermediate revisions by 74 users not shown)
Line 1: Line 1:
dummy
+
__NOTOC__
 +
== Usage ==
 +
 
 +
<mmtsbToolUsage cmd="aarex.pl"></mmtsbToolUsage>
 +
 
 +
== Description ==
 +
 
 +
This script is used to run replica exchange simulations. In most parallel
 +
environments it will start the replica exchange server automatically. The
 +
options <B>-n</B>, <B>-par</B>, <B>-temp</B>, <B>-condfile</B>, <B>-ens</B>,
 +
<B>-ensdir</B> are available as in [[rexserver.pl]].<BR>
 +
 
 +
Alternatively, it can connect to an external replica exchange server
 +
if its address, port, and ID are given with <B>-rserv</B>. In that case
 +
<B>-jobs</B> may be used to run only some of the temperature windows instead
 +
of all windows if multiple clients are launched on different machines.<BR>
 +
 
 +
For shared memory environments the option <B>-cpus</B> can be used
 +
to specify a smaller number of CPUs than temperature windows if necessary
 +
due to computational restraints. A host file can be given with
 +
<B>-hosts</B> for automatic remote submission in a distributed environment.
 +
(see [[calcprop.pl]] for a more detailed explanation).<BR>
 +
 
 +
In order to contact the server from an external program (e.g. for monitoring
 +
purposes) the server ID is required. The option
 +
<B>-saveid</B> is available to write this server information to a file.
 +
<BR>
 +
 
 +
The intial input PDB files for each MD simulation are expected either as
 +
the last command line arguments or from an external file that is given with
 +
<B>-f</B>.<BR>
 +
 
 +
The remaining parameters are used to control the MD simulations. Parameters
 +
that can be given with <B>-mdpar</B> are shown [[CHARMM_Parameters|here]].<BR>
 +
 
 +
The option <B>-l</B> is available to provide a list of residues and
 +
a template PDB structure for loop modeling. Please note that with this
 +
option RMSD values that are automatically calculated if a reference PDB structure
 +
is given are also limited to only these residues.<BR>
 +
 
 +
Further options given with
 +
<B>-mdopt</B> control whether a trajectory or restart file is written out
 +
(<font color=#508060>[no]trajout</font> and <font color=#508060>[no]restout</font>), how many MD steps
 +
are used (default: 1) for averaging the energy score used in the replica exchange
 +
Metropolis criteria (<font color=#508060>avgener</font>), whether the rest of protein is
 +
restrained outside the loop (<font color=#508060>[no]conslim</font>), and the maximum
 +
restraint force (<font color=#508060>limforce</font>) and type of restrained atoms (<font color=#508060>limsel</font>)
 +
in this case. Other restraints may be specified with <B>-cons</B>.<BR>
 +
 
 +
The simulation protocol can be further customized by providing CHARMM commands
 +
through external files. This can be done with <B>-custom</B> which expects a keyword
 +
and a file name as arguments. The keyword is used to specify when the custom
 +
command sequence should be inserted in the standard protocol. If <font color=#508060>setup</font>
 +
is used the commands will be sent to CHARMM only once during the initial setup
 +
phase. If the keywords <font color=#508060>pre</font> or <font color=#508060>post</font> the commands will
 +
be executed before or after the dynamics command, respectively. These keywords
 +
can be further qualified with <font color=#508060>:init</font>, <font color=#508060>:equi</font>, and <font color=#508060>:prod</font>
 +
corresponding to the replica exchange cycle modes to allow custom equilibration
 +
protocols.<BR>
 +
 
 +
The option <B>-log</B> is available to request a server log file. A CHARMM
 +
log file is generated for each client if <B>-charmmlog</B> is given, an
 +
energy log file is generated with <B>-elog</B>.
 +
 
 +
== Options ==
 +
 
 +
; -help : usage information
 +
; -n runs : specifies the number of replica exchange cycles
 +
; -par key=value[....] : replica exchange simulation parameters
 +
; -temp nwin&#58;min&#58;max : number of replicas followed by the minimum and maximum temperatures
 +
; -condfile file : replica exchange [[Replica Exchange Condition File Examples|condition file]]
 +
; -f file : list of starting structures
 +
; -mdpar CHARMMparams : use specified [[CHARMM_Parameters]].  It should be noted that the default CHARMM parameter values for aarex.pl may be different for those of mdCHARMM.pl (i.e. cutnb, cuton, cutoff).  Thus it is always better to specify your CHARMM parameters.
 +
; -mdopt key=value[,...] : CHARMM simulation options
 +
; -l refPDB min&#58;max[=min&#58;max] : limit sampling to specified residue range while restraining structure to reference PDB otherwise
 +
; -cons [ca|cb|cab|heavy ref|self min&#58;max[_force][=...] : apply a harmonic restraint to all specified atoms in a given range
 +
; -opt file : options file
 +
; -custom setup|pre|post[&#58;init|equi|prod] file : provide custom files to be loaded by CHARMM at different steps of the replica exchange run
 +
; -dir directory : data directory
 +
; -ens tag : store structures in an ensemble using the given tag name
 +
; -ensdir dir : store structures in an ensemble using the given directory name
 +
; -mpirun -n hosts mpirunexec : for parallel CHARMM executables using mpirun, specify the number of CPUs per replica, a host file, and the path to mpirun
 +
; -charmmexec charmmexec : use CHARMM executable specified in given path
 +
; -openmpi n openmpirunexec : for parallel CHARMM executables compiled using openMPI, specify the number of CPUs per replica and the path to mpirun
 +
; -log file : generate replica exchange log file
 +
; -elog file : generate CHARMM energy log file
 +
; -charmmlog file : generate CHARMM log file
 +
 
 +
== Examples ==
 +
 
 +
<mmtsbToolExample cmd="aarex.pl" set="/apps/mmtsb/bench/aarex.pl-test/test1"></mmtsbToolExample>
 +
 
 +
<mmtsbToolExample cmd="aarex.pl" set="/apps/mmtsb/bench/aarex.pl-test/test2"></mmtsbToolExample>
 +
 
 +
<mmtsbToolExample cmd="aarex.pl" set="/apps/mmtsb/bench/aarex.pl-test/test3"></mmtsbToolExample>
 +
 
 +
<mmtsbToolExample cmd="aarex.pl" set="/apps/mmtsb/bench/aarex.pl-test/test4"></mmtsbToolExample>
 +
 
 +
<mmtsbToolExample cmd="aarex.pl" set="/apps/mmtsb/bench/aarex.pl-test/test5"></mmtsbToolExample>
 +
 
 +
<mmtsbToolExample cmd="aarex.pl" set="/apps/mmtsb/bench/aarex.pl-test/test6"></mmtsbToolExample>
 +
 
 +
<mmtsbToolExample cmd="aarex.pl" set="/apps/mmtsb/bench/aarex.pl-test/test7"></mmtsbToolExample>
 +
The condition file looks the following:
 +
<pre>
 +
bias rg
 +
298 force=1.25,target=18.0
 +
298 force=0.60,target=9.0
 +
298 force=0.60,target=13.0
 +
298 force=0.75,target=14.0
 +
</pre>
 +
 
 +
<mmtsbToolExample cmd="aarex.pl" set="/apps/mmtsb/bench/aarex.pl-test/test8"></mmtsbToolExample>
 +
with the following condition file:
 +
<pre>
 +
bias rg
 +
298 force=1.00,target=15.0
 +
298 force=0.60,target=12.0
 +
320 force=0.60,target=12.0
 +
320 force=1.00,target=15.0
 +
</pre>
 +
 
 +
<mmtsbToolExample cmd="aarex.pl" set="/apps/mmtsb/bench/aarex.pl-test/test9"></mmtsbToolExample>
 +
 
 +
<mmtsbToolExample cmd="aarex.pl" set="test10"></mmtsbToolExample>
 +
 
 +
with [[gbsw_setup.str]], [[phmd-g5.in]] and a <b>hostlist</b> file that contains the names of available nodes.

Latest revision as of 02:37, 31 July 2009

Usage

usage:   aarex.pl [options] [files]
options: [-n runs]
         [-par initruns=value,equilruns=value,
               [no]save,savebestfreq=value,archive
               ensmode=add|replace,natpdb=file,psf=file
               arcmode=add|replace,[no]removecons]
         [-temp nwin:min:max]
         [-condfile file]
         [-f listfile]
         [-mdpar CHARMMparams]
         [-mdopt [no]trajout,[no]restout,[no]conslim,
                 limforce=value,limsel=ca|cb|cab|heavy]
         [-l refPDB min:max[=min:max ...]]
         [-cons [ca|cb|cab|heavy] ref|self min:max[_force][=...]]
         [-opt optionsfile]
         [-custom setup|pre|post[:init|equi|prod] file]
         [-dir workdir]
         [-ens tag] [-ensdir dir]
         [PARALLELoptions]
         [-mpirun n hosts mpirunexec]
         [-ibrun n mpirunexec]
         [-charmmexec charmmexec]
         [-openmpi n openmpirunexec]
         [-gpu n]
         [-log file] [-elog file] [-charmmlog file]

Show source


Description

This script is used to run replica exchange simulations. In most parallel environments it will start the replica exchange server automatically. The options -n, -par, -temp, -condfile, -ens, -ensdir are available as in rexserver.pl.

Alternatively, it can connect to an external replica exchange server if its address, port, and ID are given with -rserv. In that case -jobs may be used to run only some of the temperature windows instead of all windows if multiple clients are launched on different machines.

For shared memory environments the option -cpus can be used to specify a smaller number of CPUs than temperature windows if necessary due to computational restraints. A host file can be given with -hosts for automatic remote submission in a distributed environment. (see calcprop.pl for a more detailed explanation).

In order to contact the server from an external program (e.g. for monitoring purposes) the server ID is required. The option -saveid is available to write this server information to a file.

The intial input PDB files for each MD simulation are expected either as the last command line arguments or from an external file that is given with -f.

The remaining parameters are used to control the MD simulations. Parameters that can be given with -mdpar are shown here.

The option -l is available to provide a list of residues and a template PDB structure for loop modeling. Please note that with this option RMSD values that are automatically calculated if a reference PDB structure is given are also limited to only these residues.

Further options given with -mdopt control whether a trajectory or restart file is written out ([no]trajout and [no]restout), how many MD steps are used (default: 1) for averaging the energy score used in the replica exchange Metropolis criteria (avgener), whether the rest of protein is restrained outside the loop ([no]conslim), and the maximum restraint force (limforce) and type of restrained atoms (limsel) in this case. Other restraints may be specified with -cons.

The simulation protocol can be further customized by providing CHARMM commands through external files. This can be done with -custom which expects a keyword and a file name as arguments. The keyword is used to specify when the custom command sequence should be inserted in the standard protocol. If setup is used the commands will be sent to CHARMM only once during the initial setup phase. If the keywords pre or post the commands will be executed before or after the dynamics command, respectively. These keywords can be further qualified with :init, :equi, and :prod corresponding to the replica exchange cycle modes to allow custom equilibration protocols.

The option -log is available to request a server log file. A CHARMM log file is generated for each client if -charmmlog is given, an energy log file is generated with -elog.

Options

-help 
usage information
-n runs 
specifies the number of replica exchange cycles
-par key=value[....] 
replica exchange simulation parameters
-temp nwin:min:max 
number of replicas followed by the minimum and maximum temperatures
-condfile file 
replica exchange condition file
-f file 
list of starting structures
-mdpar CHARMMparams 
use specified CHARMM_Parameters. It should be noted that the default CHARMM parameter values for aarex.pl may be different for those of mdCHARMM.pl (i.e. cutnb, cuton, cutoff). Thus it is always better to specify your CHARMM parameters.
-mdopt key=value[,...] 
CHARMM simulation options
-l refPDB min:max[=min:max] 
limit sampling to specified residue range while restraining structure to reference PDB otherwise
-cons [ca|cb|cab|heavy ref|self min:max[_force][=...] 
apply a harmonic restraint to all specified atoms in a given range
-opt file 
options file
-custom setup|pre|post[:init|equi|prod] file 
provide custom files to be loaded by CHARMM at different steps of the replica exchange run
-dir directory 
data directory
-ens tag 
store structures in an ensemble using the given tag name
-ensdir dir 
store structures in an ensemble using the given directory name
-mpirun -n hosts mpirunexec 
for parallel CHARMM executables using mpirun, specify the number of CPUs per replica, a host file, and the path to mpirun
-charmmexec charmmexec 
use CHARMM executable specified in given path
-openmpi n openmpirunexec 
for parallel CHARMM executables compiled using openMPI, specify the number of CPUs per replica and the path to mpirun
-log file 
generate replica exchange log file
-elog file 
generate CHARMM energy log file
-charmmlog file 
generate CHARMM log file

Examples

aarex.pl -n 8 -mdpar dynsteps=100,param=22,gb,nocut -par initruns=2,equilruns=2,natpdb=1vii.exp.pdb -temp 4:298:400 1vii.sample.{1,2,3,4}.pdb
runs 8 replica exchange MD simulation cycles with four exponentially spaced temperature windows from 298 to 400K. The first 2 runs are considered initialization runs, the next 2 runs are equilibration runs. The native PDB structure is given as reference for calculation RMSD values. MD parameters are set to run 100 steps for each cycle, use CHARMM22 parameters with GB implicit solvent and no electrostatic cutoffs. Initial conformations are taken from the files 1vii.sample.?.pdb.


aarex.pl -n 4
runs 4 additional cycles continuing a previous replica exchange simulation run


aarex.pl -n 5 -par initruns=2,equilruns=0,nosave -temp 4:298:400 -ensdir data -ens rex -mdpar dynsteps=200,gb,nocut 1vii.sample.{1,2,3,4}.pdb
runs 5 replica exchange simulation runs with 2 initialization and no equilibration runs. The conformation from the lowest temperature at each run is saved under the rex tag in an ensemble in the directory data. No other conformations during the simulation are saved.


aarex.pl -n 6 -par initruns=2,equilruns=2,natpdb=1vii.exp.pdb -temp 4:298:400 -cpus 2 -mdpar dynsteps=200,gb -l 1vii.exp.pdb 10:21 -mdopt conslim,limforce=5.0,limsel=ca -log server.log -charmmlog charmm.log -f init.files
runs a replica exchange simulation runs for loop modeling. The loop residues are located at 10 through 21, the rest of the protein is restrained at C-alpha atoms with a force constant of up to 5 kcal/mol. This run has 4 temperature windows but uses only 2 CPUs at a time. A server log file and for each client a CHARMM log file are written out. The intial input files are taken from init.files.


aarex.pl -n 8 -mdpar dynsteps=100,gb,nocut -par initruns=2,equilruns=2 -temp 4:298:400 -hosts sgi.workstations 1vii.sample.{1,2,3,4}.pdb
runs a replica exchange simulation across distributed workstations


aarex.pl -n 8 -mdpar dynsteps=100,gb,nocut -par initruns=2,equilruns=2 -temp 4:298:400 -mp -hosts sgi.local 1vii.sample.1.pdb
runs a replica exchange simulation across distributed workstations with local directories. All temperature windows are started from the same initial file.


aarex.pl -n 10 -mdpar dynsteps=100,gb,nocut -par initruns=2,equilruns=0,natpdb=1vii.exp.pdb -condfile conditions 1vii.sample.{1,2,3,4}.pdb
replica exchange simulation with all replicas at the same temperature but with different radius of gyration umbrella potentials

The condition file looks the following:

bias rg
298 force=1.25,target=18.0
298 force=0.60,target=9.0
298 force=0.60,target=13.0
298 force=0.75,target=14.0

aarex.pl -n 10 -mdpar dynsteps=100,gb -par initruns=2,equilruns=0,natpdb=1vii.exp.pdb -condfile conditions -log server.log -charmmlog charmm.log 1vii.sample.{1,2,3,4}.pdb
2D replica exchange with two temperatures and two different radius of gyration umbrellas

with the following condition file:

bias rg
298 force=1.00,target=15.0
298 force=0.60,target=12.0
320 force=0.60,target=12.0
320 force=1.00,target=15.0

aarex.pl -charmmlog clog -n 8 -mdpar dynsteps=100,param=19,nogb -custom setup acesetup.inp -custom pre ace.inp -par initruns=2,equilruns=0,natpdb=1vii.exp.pdb -temp 4:298:350 1vii.sample.2.pdb
runs a replica exchange simulation with a customized potential function. Through the files acesetup.inp and ace.inp the ACE solvation model is used instead of the default Generalized Born model.


aarex.pl -mp -hosts hostlist -n 1000 -charmmlog logfile -par archive,natpdb=init.pdb -temp 24:298:450 -dir phmd_ph3 -mdpar param=22x,xpar=par_all22_prot_cmap_phmd.inp -mdpar xtop=top_all22_prot_cmap_phmd.inp -mdpar lang,langfbeta=5 -mdpar dynoutfrq=1000,dyntrfrq=1000,dynsteps=1000 -mdpar gb=gbsw,gbswsgamma=0.005,scalerad=nina -mdpar cutnb=24.0,cutoff=20.0,cuton=20.0 -mdpar blocked,nter=ace,cter=ct3 -mdpar patch=ASPP2:PROA.20_ASPP2:PROA.25_GLUP2:PROA.19_GLUP2:PROA.26_ DISU:PROA.18:PROA.66_ASPP2:PROB.20_ASPP2:PROB.25_ASPP2:PROB.43 -mdpar phmdpar=phmd-g5.in -mdpar phmdpri=1000,phmdph=3.0 -custom setup setup.str init.pdb
This example runs constant-pH MD with replica-exchange (REX-PHMD) for a 2-chain protein. For a full PHMD study, you should have a simulation for every pH, indicated by the phmdph value in the -mdpar option. Pay attention to titrate the sites correctly; you have to specify the number of the residues to titrate and the chain (for example, ASPP2:PROA.20 indicates that ASPP2 is the titration option, proa is the chain and 20 is the number of the residue to be titrated. If you have more than one residue you have to type the "_". For example, ASSP2:PROA.20_GLUP2:PROB.46) At the end of every simulation you should have a set of folders called aa1, aa2, , aan where n is the number of exchange steps or conditions that you selected.


with gbsw_setup.str, phmd-g5.in and a hostlist file that contains the names of available nodes.