Small improvements to Colvars doc 42/4742/1
authorGiacomo Fiorin <giacomo.fiorin@gmail.com>
Mon, 29 Oct 2018 15:21:34 +0000 (11:21 -0400)
committerGiacomo Fiorin <giacomo.fiorin@gmail.com>
Mon, 29 Oct 2018 16:28:04 +0000 (12:28 -0400)
More forward-compatible explanation of current keywords, and support for some
hyperlinks.  There are no changes to the C++ or Tcl code.

The PDF and HTML versions of the manual both compile correctly.

See also:
https://github.com/Colvars/colvars/pull/185
(review completed)

Change-Id: I18dc77fe5ee7411fc2d552d4e4ecf90cbada9ca7

ug/ug_colvars.tex
ug/ug_colvars_macros.tex

index 9f57de9..db8c83a 100644 (file)
@@ -2318,15 +2318,14 @@ The parameters described below offer a way to specify these parameters only once
   \keydef
     {width}{%
     \texttt{colvar}}{%
-    Colvar fluctuation scale, or resolution for grid-based methods}{%
+    Unit of the variable, or grid spacing}{%
     positive decimal}{%
     1.0}{%
-    This number has the same physical unit as the colvar value and defines an effective colvar unit.
-%    Biasing algorithms use it for different purposes.
-    Harmonic restraints (\ref{sec:colvarbias_harmonic}) use it to set the physical unit of the force constant, which is useful for multidimensional restraints involving variables with very different units (for examples, $\AA$ or degrees $^\circ$) with a single, scaled force constant.
+    This number defines the effective unit of measurement for the collective variable, and is used by the biasing methods for the following purposes.
+    Harmonic (\ref{sec:colvarbias_harmonic}), harmonic walls (\ref{sec:colvarbias_harmonic_walls}) and linear restraints (\ref{sec:colvarbias_linear}) use it to set the physical unit of the force constant, which is useful for multidimensional restraints involving multiple variables with very different units (for examples, $\AA$ or degrees $^\circ$) with a single, scaled force constant.
+    The values of the scaled force constant in the units of each variable are printed at initialization time. 
     Histograms (\ref{sec:colvarbias_histogram}), ABF (\ref{sec:colvarbias_abf}) and metadynamics (\ref{sec:colvarbias_meta}) all use this number as the initial choice for the grid spacing along this variable: for this reason, \texttt{width} should generally be no larger than the standard deviation of the colvar in an unbiased simulation.
-%    When a non-unity width is required by the application, the optimal value is application-dependent, but can often be thought of as a user-provided estimate of the fluctuation amplitude for the colvar.
-    Unless it is required to control the spacing, it is usually simplest to keep the default value of 1, so that restraint force constants are provided in more intuitive units.
+    Unless it is required to control the spacing, it is usually simplest to keep the default value of 1, so that restraint force constants are provided with their full physical unit.
   }
 
 \item %
@@ -2338,8 +2337,8 @@ The parameters described below offer a way to specify these parameters only once
     decimal}{%
     Defines the lowest end of the interval of ``relevant'' values for the colvar.
     This number can be either a true physical boundary, or a user-defined number.  
-    Together with \texttt{upperBoundary} and \texttt{width}, it is used to define a grid of values along the colvar (not available for colvars based on \texttt{distanceDir}, \texttt{distanceVec}, and \texttt{orientation}).
-    This option does not affect dynamics: to confine a colvar within a certain interval, use a \texttt{harmonicWalls} bias.
+    Together with \texttt{upperBoundary} and \texttt{width}, it is used to define a grid of values along the variable (not available for variables with vector values, \ref{sec:cvc_non_scalar}).
+    \emph{This option does not affect dynamics: to confine a colvar within a certain interval, use a \texttt{harmonicWalls} bias.}
 }
 
 \item %
@@ -3129,12 +3128,11 @@ To gain an estimate of the computational cost of a large colvar, one can use a t
 
 \cvsec{Biasing and analysis methods}{sec:colvarbias}
 
-All of the biasing and analysis methods implemented (\texttt{abf},
-\texttt{harmonic}, \texttt{histogram} and \texttt{metadynamics})
-recognize the following options:
+All of the biasing and analysis methods implemented recognize the following options:
 \begin{itemize}
 
 \item %
+  \labelkey{colvarbias|name}
   \keydef
     {name}{%
     colvar bias}{%
@@ -3145,6 +3143,7 @@ recognize the following options:
     output messages and to name some output files.}
 
 \item %
+  \labelkey{colvarbias|colvars}
   \key
     {colvars}{%
     colvar bias}{%
@@ -3154,6 +3153,7 @@ recognize the following options:
     analysis will be applied.}
 
 \item %
+  \labelkey{colvarbias|outputEnergy}
   \keydef
     {outputEnergy}{%
     colvar bias}{%
@@ -3170,6 +3170,7 @@ In addition, restraint biases (\ref{sec:colvarbias_harmonic}, \ref{sec:colvarbia
 \begin{itemize}
 
 \item %
+  \labelkey{writeTIPMF}{colvarbias|writeTIPMF}
   \keydef
     {writeTIPMF}{%
     colvar bias}{%
@@ -3183,6 +3184,7 @@ In addition, restraint biases (\ref{sec:colvarbias_harmonic}, \ref{sec:colvarbia
 
 
 \item %
+  \labelkey{writeTISamples}{colvarbias|writeTISamples}
   \keydef
     {writeTISamples}{%
     colvar bias}{%
@@ -3741,6 +3743,7 @@ This option can be utilized in both eABF and classical ABF simulations, e.g.,
 {\ttfamily ./eabf.tcl -mergesplitwindow merge abf0 abf1 abf2 abf3}.
 }
 
+
 \cvsubsec{Metadynamics}{sec:colvarbias_meta}
 
 The metadynamics method uses a history-dependent potential \cite{Laio2002} that generalizes to any type of colvars the conformational flooding \cite{Grubmuller1995} and local elevation \cite{Huber1994} methods,  originally formulated to use as colvars the principal components of a covariance matrix or a set of dihedral  angles, respectively.
@@ -3771,20 +3774,22 @@ At that stage the ``effective'' potential of mean force $\tilde{A}(\bm{\xi})$ is
 Assuming that the set of collective variables includes all relevant degrees of freedom, the predicted error of the estimate is a simple function of the correlation times of the colvars $\tau_{\xi_{i}}$, and of the user-defined parameters $W$, $\sigma_{\xi_{i}}$ and $\delta{}t$ \cite{Bussi2006}. 
 In typical applications, a good rule of thumb can be to choose the ratio $W/\delta{}t$ much smaller than $\kappa_{\mathrm{B}}T/\tau_{\bm{\xi}}$, where $\tau_{\bm{\xi}}$ is the longest among $\bm{\xi}$'s correlation times: $\sigma_{\xi_{i}}$ then dictates the resolution of the calculated PMF.
 
-%Given $\Delta\xi$ the length of the relevant region of the colvar $\xi$, and $A^{*}$ the highest free energy that needs to be sampled (e.g.~the higher transition state free energy), the upper bound for the required simulation time is of the order of $N_{\mathrm{s}}(\xi) = (A^{*}\Delta\xi)/(W2\sigma_{\xi})$ multiples of  $\delta{}t$.
-%In calculations with multiple colvars $\bm{\xi}$, the upper bound is then 
-%$N_{\mathrm{s}}(\xi_{1}) \times N_{\mathrm{s}}(\xi_{2}) \times \ldots \times N_{\mathrm{s}}(\xi_{N_{\mathrm{cv}}}) \times \delta{}t$.
 
-To enable a metadynamics calculation, a \texttt{metadynamics} block must be defined in the Colvars configuration file. 
-Its mandatory keywords are \texttt{colvars}, which lists all the variables involved, and \texttt{hillWeight}, which specifies the weight parameter $W$.
-The parameters $\delta{}t$ and $\sigma_{\xi}$ specified by the optional keywords \texttt{newHillFrequency} and \texttt{hillWidth}:
+\cvsubsubsec{Basic syntax}{sec:colvarbias_meta_basics}
+
+To enable a metadynamics calculation, a \texttt{metadynamics \{...\}} block must be defined in the Colvars configuration file.
+Its mandatory keywords are \refkey{colvars}{colvarbias|colvars}, which lists all the variables involved, \refkey{hillWeight}{metadynamics|hillWeight}, which specifies the weight parameter $W$, and \refkey{hillWidth}{metadynamics|hillWidth}, which defines the Gaussian width $2\sigma_{\xi}$ as a number of grid points.
+
 \begin{itemize}
 
 \item \dupkey{name}{\texttt{metadynamics}}{sec:colvarbias}{biasing and analysis methods}
 \item \dupkey{colvars}{\texttt{metadynamics}}{sec:colvarbias}{biasing and analysis methods}
 \item \dupkey{outputEnergy}{\texttt{metadynamics}}{sec:colvarbias}{biasing and analysis methods}
+\item \dupkey{writeTIPMF}{\texttt{metadynamics}}{sec:colvarbias}{biasing and analysis methods}
+\item \dupkey{writeTISamples}{\texttt{metadynamics}}{sec:colvarbias}{biasing and analysis methods}
 
 \item %
+  \labelkey{metadynamics|hillWeight}
   \key
     {hillWeight}{%
     \texttt{metadynamics}}{%
@@ -3794,36 +3799,36 @@ The parameters $\delta{}t$ and $\sigma_{\xi}$ specified by the optional keywords
     Lower values provide more accurate sampling of the system's degrees of freedom at the price of longer simulation times to complete a PMF calculation based on metadynamics.}
 
 \item %
+  \labelkey{metadynamics|hillWidth}
+  \key
+    {hillWidth}{%
+    \texttt{metadynamics}}{%
+    Width of a Gaussian hill, measured in number of grid points}{%
+    positive decimal}{%
+    The value of this keyword is the Gaussian width $2\sigma_{\xi_{i}}$, expressed in number of grid points: the grid spacing is determined by \refkey{width}{colvar|width}.
+    The values of the parameter $\sigma_{\xi_{i}}$ for each variable $\xi_{i}$ inits physical units are printed by \MDENGINE{} at initialization time.
+    Values between 1 and 3 are recommended: smaller values fail to adequately interpolate each Gaussian \cite{Fiorin2013}, while larger values may be unable to account for steep free-energy gradients.}
+
+\item %
+  \labelkey{metadynamics|newHillFrequency}
   \keydef
     {newHillFrequency}{%
     \texttt{metadynamics}}{%
     Frequency of hill creation}{%
     positive integer}{%
     \texttt{1000}}{%
-    This option sets the number of integration steps after which a new
-    hill is added to the metadynamics potential.  Its value determines
-    the parameter $\delta{}t$ in eq.~\ref{eq:colvars_meta_pot}.  Higher
-    values provide more accurate sampling at the price of longer
-    simulation times to complete a PMF calculation.}
+    This option sets the number of steps after which a new Gaussian hill is added to the metadynamics potential.
+    The product of this number and the integration time-step defines the parameter $\delta{}t$ in eq.~\ref{eq:colvars_meta_pot}.
+    Higher values provide more accurate statistical sampling, at the price of longer simulation times to complete a PMF calculation.
+    \cvvmdonly{When analyzing data from a previous simulation in VMD, the metadynamics potential does not need to be updated, and it is useful to set this number to 0.}}
 
-\item %
-  \keydef
-    {hillWidth}{%
-    \texttt{metadynamics}}{%
-    Relative width of a Gaussian hill with respect to the colvar's width}{%
-    positive decimal}{%
-    $\sqrt{2\pi}/2$}{%
-    The Gaussian width along each colvar, $2\sigma_{\xi_{i}}$, is set as the product between this number and the colvar's parameter $w_{i}$ given by \refkey{width}{colvar|width}; such product is printed in the standard output of \MDENGINE{}.
-    The default value of this number gives a Gaussian hill function whose volume is equal to the product of $\prod_{i}w_{i}$, the volume of one \texttt{histogram} bin (see \ref{sec:colvarbias_histogram}), and $W$.
-    \textbf{Tip:} \emph{use this property to estimate the fraction of colvar space covered by the Gaussian bias within a given simulation time.}
-    When \texttt{useGrids} is on, the default value also gives acceptable discretization errors~\cite{Fiorin2013}: for smoother visualization, this parameter may be increased and the \texttt{width} $w_{i}$ decreased in the same proportion.
-    \textbf{Note:} \emph{values smaller than 1 are not recommended}.}
 \end{itemize}
 
 
 \cvsubsubsec{Output files}{sec:colvarbias_meta_output}
-When interpolating grids are enabled (default behavior), the PMF is written every \texttt{colvarsRestartFrequency} steps to the file \outputName\texttt{.pmf}.
-The following two options allow to control this behavior and to visually track statistical convergence:
+
+When interpolating grids are enabled (default behavior), the PMF is written by default every \texttt{colvarsRestartFrequency} steps to the file \outputName\texttt{.pmf}.
+The following two options allow to disable or control this behavior and to track statistical convergence:
 
 \begin{itemize}
 
@@ -3850,7 +3855,7 @@ The following two options allow to control this behavior and to visually track s
 \end{itemize}
 
 \textbf{Note:} when Gaussian hills are deposited near the \refkey{lowerBoundary}{colvar|lowerBoundary} or \refkey{upperBoundary}{colvar|upperBoundary} and interpolating grids are used (default behavior), their truncation can give rise to accumulating errors.
-In these cases, as a measure of fault-tolerance all Gaussian hills near the boundaries are included in the output state file, and are recalculated analytically whenever the colvar falls outside the grid's boundaries.
+In these cases, as a measure of fault-tolerance all Gaussian hills near the boundaries are included in the output state file, and are recalculated analytically whenever the variable falls outside the grid's boundaries.
 (Such measure protects the accuracy of the calculation, and can only be disabled by \texttt{hardLowerBoundary} or \texttt{hardUpperBoundary}.)
 To avoid gradual loss of performance and growth of the state file, either one of the following solutions is recommended:
 \begin{itemize}
@@ -4127,6 +4132,8 @@ block, which may contain (in addition to the standard option
 \item \dupkey{name}{\texttt{harmonic}}{sec:colvarbias}{biasing and analysis methods}
 \item \dupkey{colvars}{\texttt{harmonic}}{sec:colvarbias}{biasing and analysis methods}
 \item \dupkey{outputEnergy}{\texttt{harmonic}}{sec:colvarbias}{biasing and analysis methods}
+\item \dupkey{writeTIPMF}{\texttt{harmonic}}{sec:colvarbias}{biasing and analysis methods}
+\item \dupkey{writeTISamples}{\texttt{harmonic}}{sec:colvarbias}{biasing and analysis methods}
 
 \item %
   \keydef
@@ -4135,16 +4142,12 @@ block, which may contain (in addition to the standard option
     Scaled force constant (\cvnamdonly{kcal/mol}\cvvmdonly{kcal/mol}\cvlammpsonly{unit of energy specified by \texttt{units}})}{%
     positive decimal}{%
     \texttt{1.0}}{%
-    This defines a scaled force constant $k$ for the harmonic potential (eq.~\ref{eq:colvarbias_harmonic_multi}).
-    To ensure consistency for multidimensional restraints, it is
-    divided internally by the square of the specific \texttt{width}
-    for each colvar involved (which is 1 by default), so that all colvars
-    are effectively dimensionless and of commensurate size.
-    For instance, setting a scaled force constant of 10~kcal/mol acting
-    on two colvars, an angle with a \texttt{width} of 5~degrees and a distance
-    with a width of 0.5~\AA{}, will apply actual force constants of
-    0.4~kcal/mol$\times$degree$^{-2}$ for the angle and
-    40~kcal/mol/\AA$^2$ for the distance.}
+    This option defines a scaled force constant $k$ for the harmonic potential (eq.~\ref{eq:colvarbias_harmonic_multi}).
+    To ensure consistency for multidimensional restraints, it is divided internally by the square of the specific \texttt{width} of each variable (which is 1 by default).
+    This makes all values effectively dimensionless and of commensurate size.
+    For instance, setting a scaled force constant of 10~kcal/mol acting on two variables, an angle with a \texttt{width} of 5~degrees and a distance  with a width of 0.5~\AA{}, will apply actual force constants of 0.4~kcal/mol$\times$degree$^{-2}$ for the angle and 40~kcal/mol/\AA$^2$ for the distance.
+    \emph{The values of the actual force constants are always printed when the restraint is defined.}
+  }
 
 \item %
   \labelkey{harmonic|centers}
@@ -4386,6 +4389,8 @@ The \texttt{harmonicWalls} bias implements the following options:
 \item \dupkey{name}{\texttt{harmonicWalls}}{sec:colvarbias}{biasing and analysis methods}
 \item \dupkey{colvars}{\texttt{harmonicWalls}}{sec:colvarbias}{biasing and analysis methods}
 \item \dupkey{outputEnergy}{\texttt{harmonicWalls}}{sec:colvarbias}{biasing and analysis methods}
+\item \dupkey{writeTIPMF}{\texttt{harmonicWalls}}{sec:colvarbias}{biasing and analysis methods}
+\item \dupkey{writeTISamples}{\texttt{harmonicWalls}}{sec:colvarbias}{biasing and analysis methods}
 
 \item %
   \key
@@ -4458,7 +4463,7 @@ using \cite{Pitera2012}.
 
 \item \dupkey{name}{\texttt{linear}}{sec:colvarbias}{biasing and analysis methods}
 \item \dupkey{colvars}{\texttt{linear}}{sec:colvarbias}{biasing and analysis methods}
-%\item \dupkey{outputEnergy}{\texttt{linear}}{sec:colvarbias}{biasing and analysis methods}
+\item \dupkey{outputEnergy}{\texttt{linear}}{sec:colvarbias}{biasing and analysis methods}
 
 \item %
   \keydef
@@ -4467,11 +4472,10 @@ using \cite{Pitera2012}.
     Scaled force constant (\cvnamdonly{kcal/mol}\cvvmdonly{kcal/mol}\cvlammpsonly{unit of energy specified by \texttt{units}})}{%
     positive decimal}{%
     \texttt{1.0}}{%
-    This defines a scaled force constant for the linear bias.
-    To ensure consistency for multidimensional restraints, it is
-    divided internally by the specific \texttt{width}
-    for each colvar involved (which is 1 by default), so that all colvars
-    are effectively dimensionless and of commensurate size.}
+    This option defines a scaled force constant for the linear bias.
+    To ensure consistency for multidimensional restraints, it is divided internally by the specific \texttt{width} of each variable (which is 1 by default), so that all variables are effectively dimensionless and of commensurate size.
+    \emph{The values of the actual force constants are always printed when the restraint is defined.}
+}
 
 \item %
   \key
@@ -4482,6 +4486,9 @@ using \cite{Pitera2012}.
     These are analogous to the \refkey{centers}{harmonic|centers} keyword of the harmonic restraint.
     Although they do not affect dynamics, they are here necessary to ensure a well-defined energy for the linear bias.}
 
+\item \dupkey{writeTIPMF}{\texttt{linear}}{sec:colvarbias}{biasing and analysis methods}
+\item \dupkey{writeTISamples}{\texttt{linear}}{sec:colvarbias}{biasing and analysis methods}
+
 \item \dupkey{targetForceConstant}{\texttt{linear}}{sec:colvarbias_harmonic}{Harmonic restraints}
 \item \dupkey{targetNumSteps}{\texttt{linear}}{sec:colvarbias_harmonic}{Harmonic restraints}
 \item \dupkey{targetForceExponent}{\texttt{linear}}{sec:colvarbias_harmonic}{Harmonic restraints}
@@ -4573,6 +4580,7 @@ an optimization algorithm until the bias has converged}.
      
 \end{itemize}
 
+
 \cvsubsec{Multidimensional histograms}{sec:colvarbias_histogram}
 
 The \texttt{histogram} feature is used to record the distribution of a set of collective
@@ -4814,7 +4822,7 @@ The default SMP schedule is the following:
 \item distribute the computation of all components across available threads;
 \item on a single thread, collect the results of multi-component variables using polynomial combinations (see \ref{sec:cvc_superp})\cvleptononly{, or custom functions (see \ref{sec:colvar_custom_function})}\cvscriptonly{, or scripted functions (see \ref{sec:colvar_scripted})};
 \item distribute the computation of all biases across available threads;
-\item compute on a single thread any scripted biases implemented via the keyword \refkey{scriptedColvarForces}.
+\item compute on a single thread any scripted biases implemented via the keyword \refkey{scriptedColvarForces}{Colvars-global|scriptedColvarForces}.
 \item communicate on a single thread forces to \MDENGINE{}.
 \end{enumerate}
 
index c46a50f..f5395cd 100644 (file)
 % use the NAMD UG macros to document keywords
 \newcommand{\key}[5]{\NAMDCOLVARCONF{#1}{#2}{#3}{#4}{#5}}
 \newcommand{\keydef}[6]{\NAMDCOLVARCONFWDEF{#1}{#2}{#3}{#4}{#5}{#6}}
-\newcommand{\labelkey}[1]{}
-\newcommand{\refkey}[2]{\texttt{#1}}
+\newcommand{\labelkey}[1]{\label{#1}}
+\newcommand{\refkey}[2]{\texttt{#1} (see \ref{#2})}
 \newcommand{\dupkey}[4]{%
-  {\bf \large \tt #1:} see definition of \texttt{#1} (#4)%
+  \index{#2!\texttt{#1}}
+  {\bf \large \tt #1:} see definition of \texttt{#1} in sec.~\ref{#3} (#4)%
 }
 \newcommand{\simkey}[3]{%
+  \index{#2!\texttt{#1}}
   {\bf \large \tt #1:} analogous to \texttt{#3}%
 }