Update documentation for RAMD 72/4572/2
authorDavid Hardy <dhardy@ks.uiuc.edu>
Thu, 13 Sep 2018 17:42:07 +0000 (12:42 -0500)
committerDavid Hardy <dhardy@ks.uiuc.edu>
Fri, 14 Sep 2018 22:37:06 +0000 (17:37 -0500)
Documentation provided by Stefan Richter.

Removed make_distribution.sh file.

The example has been removed due to its size.  The plan is to post the
example on NAMD's website.  We will then need to update the User Guide
and the README file accordingly.

Change-Id: Ice8564b8a4555808f2caca7ecdb942827d9140f3

lib/ramd-5.0.4/make_distribution.sh [deleted file]
ug/ug.bib
ug/ug_accel.tex

diff --git a/lib/ramd-5.0.4/make_distribution.sh b/lib/ramd-5.0.4/make_distribution.sh
deleted file mode 100755 (executable)
index 183e535..0000000
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/bin/bash
-#To extract a release, do the following:
-export SUBREL=5.0.4
-rm -rf ../ramd-${SUBREL}*
-git archive --format=tar --prefix=ramd-${SUBREL}/ master | gzip -9 > ../ramd-${SUBREL}.tgz
-cd .. &&  rm -rf tmp && mkdir tmp && cd tmp
-tar xf ../ramd-${SUBREL}.tgz
-rm -r ramd-${SUBREL}/TRJ-Analysis-R
-zip -rm ../ramd-only-${SUBREL}.zip ramd-${SUBREL}
-cd .. && rmdir tmp
index 6ca3d97..3485238 100644 (file)
--- a/ug/ug.bib
+++ b/ug/ug.bib
@@ -1054,3 +1054,101 @@ annote={}
 }
 
 
+% begin RAMD references
+
+@article{ludemann2000substrates,
+  title={How do substrates enter and products exit the buried active site of cytochrome {P}450cam? 1. Random expulsion molecular dynamics investigation of ligand access channels and mechanisms},
+  author={L{\"u}demann, Susanna K and Lounnas, Val{\`e}re and Wade, Rebecca C},
+  journal={Journal of Molecular Biology},
+  volume={303},
+  number={5},
+  pages={797--811},
+  year={2000},
+  publisher={Elsevier}
+}
+
+@article{winn2002comparison,
+  title={Comparison of the dynamics of substrate access channels in three cytochrome {P}450s reveals different opening mechanisms and a novel functional role for a buried arginine},
+  author={Winn, Peter J and L{\"u}demann, Susanna K and Gauges, Ralph and Lounnas, Val{\`e}re and Wade, Rebecca C},
+  journal={Proceedings of the National Academy of Sciences},
+  volume={99},
+  number={8},
+  pages={5361--5366},
+  year={2002},
+  publisher={National Acad Sciences}
+}
+
+@article{schleinkofer2005mammalian,
+  title={Do mammalian cytochrome {P}450s show multiple ligand access pathways and ligand channelling?},
+  author={Schleinkofer, Karin and Winn, Peter J and L{\"u}demann, Susanne K and Wade, Rebecca C and others},
+  journal={EMBO Reports},
+  volume={6},
+  number={6},
+  pages={584--589},
+  year={2005},
+  publisher={EMBO Press}
+}
+
+@article{carlsson2006unbinding,
+  title={Unbinding of retinoic acid from the retinoic acid receptor by random expulsion molecular dynamics},
+  author={Carlsson, Peter and Burendahl, Sofia and Nilsson, Lennart},
+  journal={Biophysical Journal},
+  volume={91},
+  number={9},
+  pages={3151--3161},
+  year={2006},
+  publisher={Elsevier}
+}
+
+@article{vashisth2008ligand,
+  title={Ligand escape pathways and (un) binding free energy calculations for the hexameric insulin-phenol complex},
+  author={Vashisth, Harish and Abrams, Cameron F},
+  journal={Biophysical Journal},
+  volume={95},
+  number={9},
+  pages={4193--4204},
+  year={2008},
+  publisher={Elsevier}
+}
+
+@article{kokh2018estimation,
+author = {Kokh, Daria B. and Amaral, Marta and Bomke, Joerg and Gr{\"a}dler, Ulrich and Musil, Djordje and Buchstaller, Hans-Peter and Dreyer, Matthias K. and Frech, Matthias and Lowinski, Maryse and Vallee, Francois and Bianciotto, Marc and Rak, Alexey and Wade, Rebecca C.},
+title = {Estimation of Drug-Target Residence Times by $\tau$-Random Acceleration Molecular Dynamics Simulations},
+journal = {Journal of Chemical Theory and Computation},
+volume = {14},
+number = {7},
+pages = {3859-3869},
+year = {2018},
+doi = {10.1021/acs.jctc.8b00230},
+note ={PMID: 29768913},
+URL = { https://doi.org/10.1021/acs.jctc.8b00230},
+eprint = { https://doi.org/10.1021/acs.jctc.8b00230}
+}
+
+@article{biedermannova2012single,
+author={Biedermannov{\'a}, Lada and Prokop, Zbynek and Gora, Artur and Chovancov{\'a}, Eva and Kov{\'a}cs, Mih{\'a}ly and Damborsky, Jiri and Wade, Rebecca C},
+title = {A Single Mutation in a Tunnel to the Active Site Changes the Mechanism and Kinetics of Product Release in Haloalkane Dehalogenase LinB},
+volume = {287}, 
+number = {34}, 
+pages = {29062-29074}, 
+year = {2012}, 
+doi = {10.1074/jbc.M112.377853}, 
+URL = {http://www.jbc.org/content/287/34/29062.abstract}, 
+eprint = {http://www.jbc.org/content/287/34/29062.full.pdf+html}, 
+journal = {Journal of Biological Chemistry} 
+}
+
+@article{cojocaru2012multiple,
+author = {Cojocaru, Vlad  and Winn, Peter  J. and Wade, Rebecca  C.},
+title =  {Multiple, Ligand-dependent Routes from the Active Site of Cytochrome {P}450 2{C}9},
+volume = {13},
+journal = {Current Drug Metabolism},
+number = {2},
+pages = {143-154},
+year = {2012},
+doi = {10.2174/138920012798918462},
+URL = {http://www.eurekaselect.com/node/75602/article}
+}
+
+% end RAMD references
+
index d7383d6..c457964 100644 (file)
@@ -632,89 +632,75 @@ set fit_pdb_file "alanin.pdb"
 
 \subsection{Random acceleration molecular dynamics simulations}
 
-The "lib/ramd" directory stores the tcl scripts and the example files for the implementation of the Random Acceleration Molecular Dynamics (RAMD) simulation method in NAMD. 
-The RAMD method can be used to carry out molecular dynamics (MD) simulations with an additional randomly oriented acceleration applied to the center of mass of one group of atoms (referred below as "ligand") in the system. 
+The ``lib/ramd" directory stores the tcl scripts and the example files for the implementation of the Random Acceleration Molecular Dynamics (RAMD) simulation method in NAMD. 
+The RAMD method can be used to carry out molecular dynamics (MD) simulations with an additional randomly oriented acceleration applied to the center of mass of one group of atoms (referred to below as ``ligand") in the system. 
 It can, for example, be used to identify egress routes for a ligand from a buried protein binding site. 
-Since its original implementation in the ARGOS (ref 1, 2) program, the method has been also implemented in AMBER 8 (ref 3), and CHARMM (ref 4)
-The first implementation of RAMD in NAMD using a tcl script (available as supplementary material in ref 6) provided only limited functionality compared to the AMBER 8 implementation. 
+Since its original implementation in the ARGOS \mycite{L{\"u}demann \ETAL, 2000}{ludemann2000substrates,winn2002comparison} program, the method has been implemented in AMBER 8 \mycite{Schleinkofer \ETAL, 2005}{schleinkofer2005mammalian}, and CHARMM \mycite{Carlsson \ETAL, 2006}{carlsson2006unbinding}
+The first implementation of RAMD in NAMD using a tcl script (available as supplementary material in \mycite{Vashisth \ETAL, 2008}{vashisth2008ligand}) provided only limited functionality compared to the AMBER 8 implementation and was followed with an implementation of RAMD and RAMD--MD in NAMD \mycite{}{cojocaru2012multiple,biedermannova2012single}. Recently the RAMD method was improved in speed by using NAMD vector implementations and streamlining the code. The current implementation is now focused on the RAMD simulation and was used in the $\tau$RAMD procedure for the estimation of relative drug-target residence times \mycite{Kokh \ETAL, 2018}{kokh2018estimation}.
 
-In the current implementation, the RAMD method can be performed in 2 flavors: (i) "pure RAMD simulations" in which the randomly-oriented acceleration is applied continuously, and (ii) "combined RAMD-MD simulations" in which RAMD steps alternate with standard MD steps. 
-Additional information is found in the README file in the "lib/ramd" directory. 
+Additional information is found in the README file in the ``lib/ramd" directory. 
 The user is encouraged to carefully read this information before starting production runs.
 
-The three required scripts are stored in "lib/ramd/scripts": (i) ramd--4.0.tcl defines the simulation parameters and passes them from the NAMD configuration file to the main script, (ii) "ramd--4.0\_script.tcl" adds the randomly oriented force and performs all related computations, and  (iii) "vectors.tcl" was borrowed from VMD and defines the vector operations used.
+The two required scripts are stored in ``lib/ramd/scripts": (i) ramd--5.tcl defines the simulation parameters and passes them from the NAMD configuration file to the main script, (ii) ``ramd--5\_script.tcl" adds the randomly oriented force and performs all related computations.
 
-Two examples for running the scripts are included in the directory "lib/ramd/examples".  
-The user is encouraged to read the "README.examples" file provided in the same directory.
+Two examples for running RAMD are included in the directory ``lib/ramd/example/". The examples can be started using the RAMD-force.sh shell scripts.
 
-In order to turn RAMD on, the line "source /path/to/your/files/ramd--4.0.tcl" should be included in the NAMD configuration file. 
-Unless the user decides to store the scripts at a different location, the path 
-"/path/to/your/files" should point to the "lib/ramd/scripts" directory. 
-Otherwise, the user should make sure that the directory "/path/to/your/files" stores all three scripts described above. 
-
-The specific RAMD simulation parameters to be provided in the NAMD configuration file (listed below) should be preceded by the keyword "ramd". 
+The specific RAMD simulation parameters to be provided in the NAMD configuration file (listed below) should be preceded by the keyword ``ramd". 
 The default values for these parameters are only given as guidance. 
-They are likely not to be suitable for other systems than those the scripts were tested on
+They may not to be suitable for other systems
 
+Mandatory parameter settings:\\
 \begin{itemize}
+\item
+\NAMDCONF{ramd lastProtAtom} {Last index of protein atom} {{\tt positive integer}} { Specifies the index of the last protein atom. } 
 
 \item
-\NAMDCONFWDEF{ramd debugLevel}{ Set debug level of RAMD} {\tt integer value } {0} { Activates verbose output if set to an integer greater than 0. Should be used only for testing purposes because the very dense output is full of information only relevant for debugging.}
+\NAMDCONF{ramd firstRamdAtom}{ First index of ligand atom } {{\tt positive integer}} {Specifies the index of the first ligand atom.}
+
+\item
+\NAMDCONF{ramd lastRamdAtom}{ Last index of ligand atom } {{\tt positive integer}} {Specifies the index of the last ligand atom. }
 
-\NAMDCONFWDEF{ramd mdStart}{ Start RAMD-MD with MD or RAMD?} {{\tt yes} or {\tt no}} {{\tt no}} { Specifies if combined RAMD-MD simulation starts with MD or RAMD steps; ignored if pure RAMD simulation is performed.  Should be set to "yes" if initial MD steps are desired.}
+\item
+\NAMDCONF{ramd ramdfilename}{Name of ramd output file}{{\tt Valid file name}}{Specified the name of the file where the ramd logs are written.}
+\end{itemize}
 
+Optional parameter settings with a default. Depending on your simulation system, you might want to change these settings:\\
+\begin{itemize}
 \item
-\NAMDCONFWDEF{ramd ramdSteps} { Set number steps in RAMD block} {{\tt positive integer}} {{\tt 50}} {Specifies the number of steps in 1 RAMD block; the simulations are evaluated every 'ramdSteps' steps.} 
+\NAMDCONFWDEF{ramd firstProtAtom} {First index of protein atom} {{\tt positive integer}} {{\tt 1}} { Specifies the index of the first protein atom.}
  
 \item
-\NAMDCONFWDEF{ramd mdSteps} { Set number steps in MD block} {{\tt positive integer}} {{\tt 0}} {Specifies the number of steps in 1 standard MD block; in combined RAMD-MD simulations, the RAMD blocks are evaluated every 'ramdSteps', the MD blocks every 'mdSteps' steps. Default of 0 gives pure RAMD simulation.}
+\NAMDCONFWDEF{ramd ramdSteps} { Set number of steps in RAMD block} {{\tt positive integer}} {{\tt 50}} {Specifies the number of steps in 1 RAMD block; the simulations are evaluated every `ramdSteps' steps.} 
 
 \item
-\NAMDCONFWDEF{ramd accel} {Set acceleration energy} {{\tt positive decimal}} {{\tt 0.25}} {Specifies acceleration in kcal/mol*A*amu to be applied during RAMD step.}
+\NAMDCONFWDEF{ramd forceRAMD} {Set acceleration force} {{\tt positive decimal}} {{\tt 16.0}} {Specifies the force to be applied. Replaces the acceleration (accel) specified in previous releases. Defaults to 16 kcal/mol/Angstrom}
 
 \item
-\NAMDCONFWDEF{ramd rMinRamd} {Set threshold for distance traveled RAMD} {{\tt positive decimal}} {{\tt 0.01}} {Specifies a threshold value for the distance in Angstroms traveled by the ligand in 1 RAMD block. In pure RAMD simulations the direction of the acceleration is changed if the ligand traveled less than 'rMinRamd' \AA in the evaluated block. In combined RAMD-MD simulations, a switch from a RAMD block to a standard MD block is applied if the ligand traveled more than 'rMinRamd' \AA in the evaluated block.}
+\NAMDCONFWDEF{ramd rMinRamd} {Set threshold for distance travelled RAMD} {{\tt positive decimal}} {{\tt 0.01}} {Specifies a threshold value for the distance in Angstroms travelled by the ligand in 1 RAMD block. In RAMD simulations the direction of the acceleration is changed if the ligand has travelled less than `rMinRamd' \AA\ in the evaluated block. 
+%(In combined RAMD-MD simulations, a switch from a RAMD block to a standard MD block is applied if the ligand travelled more than `rMinRamd' \AA in the evaluated block.)
+}
 
 \item
-\NAMDCONF{ramd rMinMd} {Set threshold for distance traveled in MD} {{\tt positive decimal}} {Specifies a threshold value for the distance, in Angstroms, traveled by accelerated atoms in 1 standard MD block.  In combined RAMD-MD simulations, a switch from a standard MD block to a RAMD block is applied according to the criteria described in the note below.  Required if 'mdStep' is not 0; ignored if 'mdSteps' is 0.}
-\item
-\NAMDCONFWDEF{ramd forceOutFreq}{Set frequency of RAMD forces output} {{\tt positive integer}, Must be divisor of both {\tt ramdSteps} and {\tt mdSteps}} {{\tt 0}} { Every 'forceOutFreq' steps, detailed output of forces will be written.} 
+\NAMDCONFWDEF{ramd forceOutFreq}{Set frequency of RAMD forces output} {{\tt positive integer}, Must be divisor of {\tt ramdSteps}} {{\tt 10}} { Every `forceOutFreq' steps, detailed output of forces will be written.} 
 
 \item
 \NAMDCONFWDEF{ramd maxDist} {Set center of mass separation} {{\tt positive decimal}} {{\tt 50}} { Specifies the distance in Angstroms between the the centers of mass of the ligand and the protein when the simulation is stopped.}
  
-\item
-\NAMDCONFWDEF{ramd firstProtAtom} {First index of protein atom} {{\tt positive integer}} {{\tt 1}} { Specifies the index of the first protein atom.}
-\item
-\NAMDCONF{ramd lastProtAtom} {Last index of protein atom} {{\tt positive atom}} { Specifies the index of the last protein atom. } 
 
 \item
-\NAMDCONF{ramd firstRamdAtom}{ First index of ligand atom } {{\tt positive integer}} {Specifies the index of the first ligand atom.}
+\NAMDCONFWDEF{ramd ramdSeed}{Set RAMD seed} {{\tt positive integer}} {{\tt 14253}} {Specifies seed for the random number generator for generation of RAMD force directions. Change this parameter if you wish to run different trajectories with identical parameters.}
 
 \item
-\NAMDCONF{ramd lastRamdAtom}{ Last index of ligand atom } {{\tt positive integer}} {Specifies the index of the last ligand atom. }
+\NAMDCONFWDEF{ramd debugLevel}{ Set debug level of RAMD} {\tt integer value } {0} { Activates verbose output if set to an integer greater than 0. Should be used only for testing purposes because the very dense output is full of information only relevant for debugging.}
 
 \item
-\NAMDCONFWDEF{ramd ramdSeed}{Set RAMD seed} {{\tt positive integer}} {{\tt 14253}} {Specifies seed for the random number generator for generation of acceleration directions. Change this parameter if you wish to run different trajectories with identical parameters.}
+\NAMDCONFWDEF{ramd namdVersion}{ Set the NAMD version}{\tt float value } {2.13} { After NAMD version 2.10 a call to {\em enabletotalforces} is done to enable tcl processing in NAMD}
 
 \end{itemize}
 
 Note: 
-In combined RAMD-MD simulations, RAMD blocks alternate with standard MD blocks ('ramdSteps' and 'mdSteps' input parameters). The switches between RAMD and MD blocks are decided based on the following parameters: (i) 'd' =  the distance between the protein and ligand centers of mass, (ii) 'dr' = the distance traveled by the ligand in 1 RAMD block, and (iii) 'dm' = the distance traveled by the ligand in 1 MD block. A switch from RAMD to MD is applied if 'dr' $>$ 'rRamdMin'. A switch from MD to RAMD is applied if: (i) 'dm' $<$ 'rMdMin' and 'd' $>$ 0 (acceleration direction is kept from previous RAMD block), (ii) if 'dm' $<$ 'rMdMin' and 'd' $<$ 0 (acceleration direction is changed), (iii) if 'dm' $>$ 'rMdMin' and 'd' $<$ 0 (acceleration direction is changed). In all other case, a switch is not applied.
-%References:
-%Luedemann, S.K., Lounnas, V. and R. C. Wade. How do Substrates Enter and Products Exit the Buried Active Site of Cytochrome P450cam ? 1. Random Expulsion Molecular Dynamics Investigation of Ligand Access Channels and Mechanisms. J Mol Biol, 303:797-811 (2000). 
-%Winn,P., Luedemann, S.K., Gauges,R., Lounnas, V. and R. C. Wade. Comparison of the dynamics of substrate access channels in three cytochrome P450s reveals different opening mechanisms and a new functional role for a buried arginine PNAS, 99, 5361-5366 (2002). 
-%Schleinkofer, K., Sudarko, Winn,P., Luedemann, S.K. and R. C. Wade. Do mammalian cytochrome P450s show multiple ligand access pathways and ligand channelling? EMBO Reports, 6, 584-589 (2005).
-%Carlsson, P., Burendahl, S., Nilsson, L. Unbinding of retinoic acid from the retinoic acid receptor by random expulsion molecular dynamics. Biophys. J. 91, 3151-3161 (2006).
-%Wang, T., Duan, Y. Chromophore channeling in the G-protein coupled receptor rhodopsin. J. Am. Chem. Soc. 129, 6970-6971 (2007).
-%Vashisth, H., Abrams, C.F. Ligand escape pathways and (un)binding free energy calculations for the hexameric insulin-phenol complex. Biophys. J. 95, 4193-4204 (2008).
-%Perakyla, M. Ligand unbinding pathways from the vitamin D receptor studied by molecular dynamics simulations. 38, 185-198 (2009).doi:10.1007/s00249-008-0369-x 
-%Klvana, M. et al. Pathways and Mechanisms for Product Release in the Engineered Haloalkane Dehalogenases Explored Using Classical and Random Acceleration Molecular Dynamics Simulations 
J. Mol. Biol. 392, 1339-1356 (2009).
-%Pavlova, M. et al. Redesigning dehalogenase access tunnels as a strategy for degrading an anthropogenic substrate Nature Chem. Biol. 5, 727-733 (2009).
-%Wang, T., Duan, Y. Ligand entry and exit pathways in the beta2-adrenergic receptor. J. Mol. Biol. 392, 1102-1115 (2009).
-
+In the current RAMD implementation, combined RAMD-MD simulations, where RAMD blocks alternate with standard MD blocks are not available. In case you are are interested in this feature, please contact the RAMD developers at mcmsoft@h-its.org
 
+Scripts for using RAMD in the $\tau$RAMD procedure for computing residence times are available at: https://www.h-its.org/downloads/ramd/