Add section on changes in Colvars syntax (incl. backward-compatible ones) 84/4584/2
authorGiacomo Fiorin <giacomo.fiorin@gmail.com>
Tue, 18 Sep 2018 01:34:48 +0000 (21:34 -0400)
committerDavid Hardy <dhardy@ks.uiuc.edu>
Tue, 18 Sep 2018 05:13:06 +0000 (00:13 -0500)
This change was already reviewed on GitHub by Joao Ribeiro:
https://github.com/Colvars/colvars/pull/178

Change-Id: I7edb8e28b6a70193606e10a3474e51cd33615665

ug/ug_colvars.tex
ug/ug_colvars_macros.tex

index e84a568..fe4dba8 100644 (file)
@@ -235,9 +235,8 @@ Setting this to \emph{no} will use the current local coordinates that are wrappe
 
 \cvsubsec{Configuration syntax for the Colvars module}{sec:colvars_config}
 
-\cvnamdonly{All the parameters defining the colvars and their biasing or analysis algorithms are read from the file specified by the configuration option \texttt{colvarsConfig}, or by the Tcl commands \texttt{cv config} and \texttt{cv configfile}.
-Hence, none of the keywords described in this section and the following ones are available as keywords for the
-NAMD configuration file.}
+\cvnamdonly{All the parameters defining variables and their biasing or analysis algorithms are read from the file specified by the configuration option \texttt{colvarsConfig}, or by the Tcl commands \texttt{cv config} and \texttt{cv configfile}.
+\emph{None of the keywords described in the remainder of this manual are recognized directly in the NAMD configuration file, unless as arguments of \texttt{cv config}.}}
 \cvvmdonly{The Colvars configuration is usually read using the commands \texttt{cv configfile} or \texttt{cv config}.}
 The syntax of the Colvars configuration is ``\texttt{keyword value}'', where the keyword and its value are separated by any white space.
 The following rules apply:
@@ -280,17 +279,6 @@ The following keywords are available in the global context of the Colvars config
     If the value is \texttt{0}, such trajectory file is not written.
     For optimization the output is buffered, and synchronized with the disk only when the restart file is being written.}
 
-% \item %
-%   \keydef
-%     {colvarsTrajAppend}{%
-%     global}{%
-%     Append to trajectory file?}{%
-%     boolean}{%
-%     \texttt{off}}{%
-%     If this flag is enabled, and a file with the same name as the trajectory file is already present, new data is appended to that file.
-%     Otherwise, a new file is created with the same name that overwrites the previous file.
-% \cvnamdonly{\textbf{Note:} \emph{when running consecutive simulations with the same \outputName{} (e.g.~in FEP calculations), you should enable this option to preserve the previous contents of the trajectory file.}}}
-
 \item %
   \labelkey{Colvars-global|colvarsRestartFrequency}
   \keydef
@@ -558,6 +546,7 @@ See Section~\ref{sec:cvc} for the physical ranges of values of each component.}
     Analogous to \texttt{hardLowerBoundary}.}
 
 \item %
+  \labelkey{expandBoundaries}{colvar|expandBoundaries} %
   \keydef
     {expandBoundaries}{%
     \texttt{colvar}}{%
@@ -632,6 +621,7 @@ See Section~\ref{sec:cvc} for the physical ranges of values of each component.}
     ``\texttt{Ep\_}$<$\texttt{name}$>$''.}
 
 \item %
+  \labelkey{colvar|outputTotalForce}
   \keydef
     {outputTotalForce}{%
     \texttt{colvar}}{%
@@ -1159,6 +1149,7 @@ Be careful when using these options in ABF simulations or when using total force
 }
 
 \item %
+  \labelkey{atom-group|fittingGroup} %
   \keydef
     {fittingGroup}{%
     atom group}{%
@@ -2702,7 +2693,7 @@ while \texttt{wrapAround} is optional.
 
 The following keywords can be used within periodic components, and within
 custom \cvscriptonly{or scripted} colvars (\ref{sec:colvar_custom_function}
-\cvscriptonly{, \ref{sec::colvar_scripted}}).
+\cvscriptonly{, \ref{sec:colvar_scripted}}).
 
 \begin{itemize}
 \item %
@@ -3308,7 +3299,7 @@ The following specific parameters can be set in the ABF configuration block:
 
 \cvnamdonly{
 \cvsubsubsec{Multiple-replica ABF}{sec:colvarbias_abf_shared}
-\label{mw-ABF}
+\label{sec:mw-ABF}
 
 \begin{itemize}
 \item \keydef{shared}{\texttt{abf}}{%
@@ -4679,3 +4670,37 @@ The following configuration options can modify the behavior of the scripting int
 
 }
 
+
+\cvsec{Syntax changes from older versions}{sec:colvars_config_changes}
+
+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}}
+\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/}\\
+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}
+
+\item \textbf{Colvars version 2016-06-09 or later \cvnamdonly{(NAMD version 2.12b1 or later)}\cvvmdonly{(VMD version 1.9.3 or later)}\cvlammpsonly{(LAMMPS version 15Sep2016 or later)}.}\\
+  The legacy keyword \texttt{refPositionsGroup} has been renamed \refkey{fittingGroup}{atom-group|fittingGroup} for clarity (the legacy version is still supported).
+
+\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}
+
+\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.
+
+\item \textbf{Deprecation warning for calculations including wall potentials.}\\
+  The legacy keywords \texttt{lowerWall} and \texttt{upperWall} will stop having default values and will need to be set explicitly (preferably as part of the \texttt{harmonicWalls} restraint).
+  When using an ABF bias, it is recommended to set the two walls equal to \refkey{lowerBoundary}{colvar|lowerBoundary} and \refkey{upperBoundary}{colvar|upperBoundary}, respectively.
+  When using a metadynamics bias, it is recommended to set the two walls \emph{within} \refkey{lowerBoundary}{colvar|lowerBoundary} and \refkey{upperBoundary}{colvar|upperBoundary}.  This guarantees that the tails of each Gaussian hill are accounted in the region between the grid boundaries and the wall potentials.  See also \refkey{expandBoundaries}{colvar|expandBoundaries} for an automatic definition of the PMF grid boundaries.
+
+\end{itemize}
index a37f86b..83abfc4 100644 (file)
@@ -33,9 +33,9 @@
   {\bf \large \tt #1:} analogous to \texttt{#3}%
 }
 
-\newcommand{\cvsec}[2]{\subsection{#1}}
-\newcommand{\cvsubsec}[2]{\subsubsection{#1}}
-\newcommand{\cvsubsubsec}[2]{\paragraph*{#1}}
+\newcommand{\cvsec}[2]{\subsection{#1}\label{#2}}
+\newcommand{\cvsubsec}[2]{\subsubsection{#1}\label{#2}}
+\newcommand{\cvsubsubsec}[2]{\paragraph*{#1}\label{#2}}
 
 \newcommand{\outputName}{\emph{outputName}}
 \newcommand{\restartName}{\emph{restartName}}