Document solute scaling parameters in user guide 93/4593/2
authorDavid Hardy <dhardy@ks.uiuc.edu>
Thu, 20 Sep 2018 18:54:48 +0000 (13:54 -0500)
committerDavid Hardy <dhardy@ks.uiuc.edu>
Fri, 21 Sep 2018 04:26:16 +0000 (23:26 -0500)
Provide user guide documentation for solute scaling (aka REST2)
configuration parameters.  Change default value for soluteScalingAll
to OFF, so as not to scale bond and angle interactions, as recommended
by the 2011 reference paper.

Change ssFile to soluteScalingFile and ssCol to soluteScalingCol for
consistency.  Update REST2 example scripts in the lib/replica/REST2
directory.

Also remove the "\url" command from URLs in the Colvars section, as
its introduction breaks the NAMD documentation build.  Now URLs are
simply set in teletype font, as done elsewhere.

Change-Id: Ie8ce1753b4bf559eed0d4351f22721c54dc23a61

lib/replica/REST2/aaqaa3_rest2_base.namd
lib/replica/REST2/aaqaa3_rest2_test.namd
src/Molecule.C
src/SimParameters.C
ug/ug.bib
ug/ug_accel.tex
ug/ug_colvars.tex

index 2539ad8..5f32165 100644 (file)
@@ -63,7 +63,7 @@ LangevinPistonTemp      300
 commotion             no
 
 soluteScaling           on
-ssCol              O
-ssFile            aaqaa3.spt
+soluteScalingCol        O
+soluteScalingFile       aaqaa3.spt
 
 soluteScalingAll no
index af471d6..3f13c12 100644 (file)
@@ -55,17 +55,17 @@ LangevinPistonPeriod    100
 LangevinPistonDecay     100
 LangevinPistonTemp      300
 
-commotion         no
+commotion            no
 
-soluteScaling     on
-ssCol             O
-ssFile            aaqaa3.spt
+soluteScaling        on
+soluteScalingCol     O
+soluteScalingFile    aaqaa3.spt
 
-soluteScalingFactor 1.0
+soluteScalingFactor  1.0
 run 20
 
-soluteScalingFactor 0.9
+soluteScalingFactor  0.9
 run 20
 
-soluteScalingFactor 0.8
+soluteScalingFactor  0.8
 run 20
index d8d13ea..5d4f0f0 100644 (file)
@@ -8794,14 +8794,14 @@ void Molecule::build_ss_flags(
 
   if (ssfile == NULL) {
     if ( ! initial_pdb ) {
-      NAMD_die("Initial PDB file unavailable, ssFile required.");
+      NAMD_die("Initial PDB file unavailable, soluteScalingFile required.");
     }
     bPDB = initial_pdb;
     strcpy(filename, "coordinate PDB file (default)");
   }
   else {
     if (ssfile->next != NULL) {
-      NAMD_die("Multiple definitions of ssFile in configuration file");
+      NAMD_die("Multiple definitions of soluteScalingFile in configuration file");
     }
 
     if ((cwd == NULL) || (ssfile->data[0] == '/')) {
@@ -8818,7 +8818,7 @@ void Molecule::build_ss_flags(
     }
 
     if (bPDB->num_atoms() != numAtoms) {
-      NAMD_die("Number of atoms in ssFile PDB does not match coordinate PDB");
+      NAMD_die("Number of atoms in soluteScalingFile PDB does not match coordinate PDB");
     }
   }
 
@@ -8827,7 +8827,7 @@ void Molecule::build_ss_flags(
   }
   else {
     if (sscol->next != NULL) {
-      NAMD_die("Multiple definitions of ssCol value in config file");
+      NAMD_die("Multiple definitions of soluteScalingCol value in config file");
     }
 
     if (strcasecmp(sscol->data, "X") == 0) {
@@ -8846,7 +8846,7 @@ void Molecule::build_ss_flags(
       bcol = 5;
     }
     else {
-      NAMD_die("ssCol must have value of X, Y, Z, O or B");
+      NAMD_die("soluteScalingCol must have value of X, Y, Z, O or B");
     }
   }
 
index 2cef67f..21aeeb2 100644 (file)
@@ -1216,15 +1216,15 @@ void SimParameters::config_parser_methods(ParseOptions &opts) {
        "Solute scaling factor for van der Waals interactions",
        &soluteScalingFactorVdw);
    opts.range("soluteScalingFactorVdw", NOT_NEGATIVE);
-   opts.optional("soluteScaling", "ssFile",
+   opts.optional("soluteScaling", "soluteScalingFile",
        "PDB file with scaling flags; if undefined, defaults to main PDB file",
        PARSE_STRING);
-   opts.optional("soluteScaling", "ssCol",
-       "Column in the ssFile providing the scaling flag",
+   opts.optional("soluteScaling", "soluteScalingCol",
+       "Column in the soluteScalingFile providing the scaling flag",
        PARSE_STRING);
    opts.optionalB("main", "soluteScalingAll",
        "Apply scaling also to bond and angle interactions?",
-       &soluteScalingAll, TRUE);
+       &soluteScalingAll, FALSE);
 
    // Drude oscillators
    opts.optionalB("main", "drude", "Perform integration of Drude oscillators?",
index 3485238..6028f63 100644 (file)
--- a/ug/ug.bib
+++ b/ug/ug.bib
@@ -1152,3 +1152,32 @@ URL = {http://www.eurekaselect.com/node/75602/article}
 
 % end RAMD references
 
+% begin REST2 references
+
+@article{WANG2011E,
+ author = {Lingle Wang and Richard A. Friesner and B. J. Berne},
+ title = {Replica Exchange with Solute Scaling: A More Efficient Version of
+         Replica Exchange with Solute Tempering {(REST2)}},
+ journal = JPCB,
+ year = 2011,
+ volume = 115,
+ number = 30,
+ pages = {9431--9438},
+}
+
+@article{JO2015,
+ author = {Sunhwan Jo and Wei Jiang},
+ title = {A generic implementation of replica exchange with solute
+         tempering ({REST}2) algorithm in {NAMD} for
+         complex biophysical simulations},
+ journal = CPC,
+ volume = 197,
+ pages = {304--311},
+ year = 2015,
+ issn = {0010-4655},
+ doi = "http://www.sciencedirect.com/science/article/pii/S001046551500329X",
+ keywords = "REST2, NAMD, Tcl, Free energy calculation"
+}
+
+% end REST2 references
+
index c457964..cc0b765 100644 (file)
@@ -291,6 +291,126 @@ The following is a list of input parameters unique to a GaMD run:
 \end{itemize}
 
 
+\subsection{Solute Scaling and REST2}
+\label{section:rest2}
+
+Solute scaling improves sampling efficiency
+by scaling the intramolecular potential energy of a protein
+to lower barriers separating different confirmations~\cite{WANG2011E}.
+The potential is scaled based on a parameter $\beta$,
+\begin{equation}
+U^{\text{SS}}(\vec{r}) =
+\beta U_{\text{pp}}(\vec{r}) +
+\sqrt{\beta} U_{\text{pw}}(\vec{r}) +
+U_{\text{ww}}(\vec{r}),
+\end{equation}
+with $U_{\text{pp}}$ denoting protein--protein interactions,
+$U_{\text{pw}}$ denoting protein--water interactions,
+and $U_{\text{ww}}$ denoting water--water interactions,
+effectively ``heating'' the protein's interatomic interactions
+whenever $\beta < 1$.
+The NAMD implementation is made efficient by rescaling
+the force field parameters for the affected atoms~\cite{JO2015}.
+In particular, this parameter scaling approach makes the calculation
+compatible with existing CUDA force kernels.
+
+The NAMD implementation provides additional flexibility to
+solute scaling by allowing different scaling factors for electrostatics,
+van der Waals, and bonded interactions, as described in the
+following section.
+Solute scaling can be combined with replica exchange
+to produce a powerful sampling enhancement method
+that is highly transferable and provides higher efficiency
+than traditional temperature exchange methods.
+In the literature, this replica exchange solute scaling method
+is known as REST2, due to its improvement of the earlier
+REST (replica exchange solute tempering) method
+that directly scaled the temperature of the solute.
+Sample files are available in directory {\tt lib/replica/REST2},
+with script file {\tt lib/replica/REST2/rest2\_remd.namd}
+demonstrating use of solute scaling with multiple replicas.
+
+\subsubsection{NAMD parameters}
+
+The following parameters are used to control solute scaling:
+
+\begin{itemize}
+
+\item
+\NAMDCONFWDEF{soluteScaling}{%
+Is replica exchange solute tempering enabled?
+}{%
+{\tt on} or {\tt off}}{{\tt off}
+}{%
+Specifies whether or not REST2 is enabled.
+If set on, then {\tt soluteScaling} must also be set.
+}
+
+\item
+\NAMDCONF{soluteScalingFactor}{%
+Solute scaling factor
+}{%
+non-negative
+}{%
+The scaling factor is set less than 1 to
+reduce potential energy barriers for the solute.
+}
+
+\item
+\NAMDCONFWDEF{soluteScalingFactorCharge}{%
+Solute scaling factor for electrostatics
+}{%
+non-negative}{{\tt soluteScalingFactor}
+}{%
+Scaling factor applied to just the electrostatics interactions.
+If not specified, this is set to {\tt soluteScalingFactor}.
+}
+
+\item
+\NAMDCONFWDEF{soluteScalingFactorVdw}{%
+Solute scaling factor for van der Waals
+}{%
+non-negative}{{\tt soluteScalingFactor}
+}{%
+Scaling factor applied to just the van der Waals interactions.
+If not specified, this is set to {\tt soluteScalingFactor}.
+}
+
+\item
+\NAMDCONFWDEF{soluteScalingFile}{%
+PDB file with scaling flags
+}{%
+UNIX filename}{{\tt coordinates}
+}{%
+PDB file used to flag solute atoms for scaling.
+If undefined, this defaults to the coordinate PDB file.
+}
+
+\item
+\NAMDCONFWDEF{soluteScalingCol}{%
+Column of PDB file
+}{%
+{\tt X}, {\tt Y}, {\tt Z}, {\tt O}, or {\tt B}}{{\tt O}
+}{%
+Column of the PDB file used to flag solute atoms for scaling.
+If undefined, this defaults to the {\tt O} (occupancy) column.
+A value of 1.0 marks the atom for scaling.
+}
+
+\item
+\NAMDCONFWDEF{soluteScalingAll}{%
+Apply scaling also to bond and angle interactions?
+}{%
+{\tt on} or {\tt off}}{{\tt off}
+}{%
+If set on, {\tt scalingFactor} is applied also to bond and angle interactions.
+Otherwise, {\tt scalingFactor} is applied only to dihedral, improper,
+and crossterm interactions.
+}
+
+\end{itemize}
+
+
 \subsection{Adaptive Tempering}
 \label{section:adapttemp}
 Adaptive tempering is akin to a single-copy replica exchange method for dynamically updating the simulation temperature. The temperature $T$ is a new random variable in the range $[Tmin,Tmax]$ that is governed by the equation $dE/dT = E-E(T)-1/T+sqrt(2)T\xi$, where $\xi$ is Gaussian white noise. The effect is that when the potential energy for a given structure is lower than the (so far calculated) average energy, the temperature is lowered. Conversely when the current energy is higher than the average energy, the temperature is raised. The effect is faster conformational sampling to find minimum energy structures. The method is implemented exactly as described by Zhang and Ma in J. Chem. Phys. 132, 244101 (2010) (using Equation 18 of their paper to calculate the average energy at a given temperature from the histogram of energies). 
index fe4dba8..ffb27d0 100644 (file)
@@ -4677,12 +4677,14 @@ The following is a list of syntax changes in Colvars since its first release.
 Many of the older keywords are still recognized by the current code: the primary purpose of this list is to make you aware of improvements that affect old configuration files.
 
 The syntax of the latest version of Colvars can always be accessed at:\\
-\cvnamdonly{\url{https://colvars.github.io/colvars-refman-namd/colvars-refman-namd.html}}
+%\cvnamdonly{\url{https://colvars.github.io/colvars-refman-namd/colvars-refman-namd.html}}
+\cvnamdonly{{\tt https://colvars.github.io/colvars-refman-namd/colvars-refman-namd.html}}
 \cvlammpsonly{\url{https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html}}
 \cvvmdonly{\url{https://colvars.github.io/colvars-refman-vmd/colvars-refman-vmd.html}}
 
 If you are using any of the NAMD and VMD tutorials:\\
-\url{https://www.ks.uiuc.edu/Training/Tutorials/}\\
+%\url{https://www.ks.uiuc.edu/Training/Tutorials/}\\
+{\tt https://www.ks.uiuc.edu/Training/Tutorials/}\\
 please be aware that \emph{several of these tutorials are not actively maintained}: for those cases, the following list will help you reconcile any inconsistencies.
 
 \begin{itemize}
@@ -4693,7 +4695,8 @@ please be aware that \emph{several of these tutorials are not actively maintaine
 \item \textbf{Colvars version 2016-08-10 or later \cvnamdonly{(NAMD version 2.12b1 or later)}\cvvmdonly{(VMD version 1.9.3 or later)}\cvlammpsonly{(LAMMPS version 15Sep2016 or later)}.}\\
   ``System forces'' have been replaced by ``total forces'' (see for example \refkey{outputTotalForce}{colvar|outputTotalForce}).
   See the following page for more information:\\
-  \url{https://colvars.github.io/README-totalforce.html}
+  %\url{https://colvars.github.io/README-totalforce.html}
+  {\tt https://colvars.github.io/README-totalforce.html}
 
 \item \textbf{Colvars version 2017-01-09 or later \cvnamdonly{(NAMD version 2.13b1 or later)}\cvvmdonly{(VMD version 1.9.4 or later)}\cvlammpsonly{(LAMMPS version 10Mar2017 or later)}.}\\
   A new type of restraint, \texttt{harmonicWalls} (see~\ref{sec:colvarbias_harmonic_walls}), replaces and improves upon the legacy keywords \texttt{lowerWall} and \texttt{upperWall}: these are still supported as short-hands.