NAMD doc for lambda-dynamics

[update-doc]

doc/colvars-code-refs.bib

@@ -230,6 +230,19 @@ @article{Humphrey1996
   url = {https://doi.org/10.1016/0263-7855(96)00018-5}
 }
 
+% alchLambda colvar component
+% alchFLambda colvar component
+% Tinker-HP interface
+@misc{Lagardere2023,
+      title={Lambda-ABF: Simplified, Accurate and Cost-effective Alchemical Free Energy Computations},
+      author={Louis Lagard\`ere and Lise Maurin and Olivier Adjoua and Krystel El Hage and Pierre Monmarch\'e and Jean-Philip Piquemal and J\'er\^ome H\'enin},
+      year={2023},
+      eprint={2307.08006},
+      archivePrefix={arXiv},
+      primaryClass={physics.chem-ph},
+      url = {https://arxiv.org/abs/2307.08006}
+}
+
 % eABF implementation
 % CZAR eABF estimator
 @article{Lesage2017,

doc/colvars-refman-main.tex

@@ -2977,32 +2977,46 @@
 \cvsubsubsec{\texttt{alchLambda}: alchemical lambda parameter.}{sec:cvc_alchlambda}
 \labelkey{colvar|alchLambda}
 
-The \texttt{alchLambda~\{\}} block defines a component returning the alchemical lambda parameter
-of the back-end simulation in \MDENGINE{}, provided that it is enabled using the appropriate options
-of \MDENGINE{}. This coordinate is obtained from the back-end at the beginning of a simulation, and
-synchronized from Colvars to \MDENGINE{} at every time step. This enables lambda-dynamics simulations.
-The \texttt{alchLambda} block itself takes no parameters, it should be left empty.
-In contrast, the \texttt{colvar} block containing it should define the relevant extended-system parameters
-to enable lambda dynamics, primarily \refkey{extendedMass}{colvar|extendedMass}:
+The \texttt{alchLambda} block defines a component returning the alchemical lambda parameter
+of the back-end simulation in \MDENGINE{}, provided that it is enabled within that software.
+\cvnamdonly{Specifically, the flag \texttt{alchOn} should be enabled, and \texttt{alchType}
+should be set to \texttt{TI}.}
+The current lambda value is obtained from the back-end at the beginning of a simulation, and
+synchronized from Colvars to \MDENGINE{} at every following time step.
+This enables lambda-dynamics simulations as documented in detail in \cite{Lagardere2023}.
+The \texttt{alchLambda} keyword itself takes no parameters.
+
+To run lambda-dynamics, the enclosing \texttt{colvar} block should contain extended-system
+parameters (\ref{sec:colvar_extended}) as in the following example:
 
 \begin{cvexampleinput}
 \-colvar~\{\\
 \-~~name~lambda\\
 \-~~extendedLagrangian~on\\
-\-~~extendedMass~400\\
-\-\\
-\-~~alchLambda~\{~\#~Keep~the~line~break\\
-\-~~\}\\
+\-~~extendedMass~150000\\
+\-~~extendedLangevinDamping~1000\\
+\\
+\-~~lowerBoundary~0\\
+\-~~upperBoundary~1\\
+\-~~reflectingLowerBoundary\\
+\-~~reflectingUpperBoundary\\
+\\
+\-~~alchLambda\\
 \-\}
 \end{cvexampleinput}
 
+These parameter values have been found  to give stable dynamics for a wide range of applications\cite{Lagardere2023}.
+Reflecting boundary conditions are recommended for lambda-dynamics to ensure that the alchemical
+variable remains precisely within its physical range.
+
+
 \cvsubsubsec{\texttt{alchFlambda}: Force on the alchemical lambda parameter.}{sec:cvc_alchFlambda}
 \labelkey{colvar|alchFlambda}
 
 The \texttt{alchFlambda~\{\}} block defines a component returning the force exterted on the alchemical
 lambda parameter of the back-end simulation in \MDENGINE{}, provided that it is enabled using the appropriate options
 of \MDENGINE{}. This coordinate is obtained from the back-end at each time step of a simulation.
-The \texttt{alchfLambda} block itself takes no parameters, it should be left empty.
+The \texttt{alchFlambda} block itself takes no parameters, it should be left empty.
 } % end of \cvalchlambdaonly
 
 \cvsubsec{Raw data: building blocks for custom functions}{sec:cvc_raw}
@@ -4443,7 +4457,7 @@
     positive decimal}{%
     This parameter specifies the fictitious mass in the case of an alchemical
     variable used in lambda-dynamics (\refkey{alchLambda}{colvar|alchLambda}).
-    Note that the dimension is not that of a usual mass. Its unit is the energy unit
+    Note that the dimension is not that of a usual mass: its unit is the energy unit
     (\ref{sec:units}) times fs$^2$.
     }
 }

doc/colvars-refman-namd.tex

@@ -32,7 +32,7 @@
 \newcommand{\cvnamebasedonly}[1]{#1}
 
 % only in programs were the alchemical coordinate (alchLambda) is available
-\newcommand{\cvalchlambdaonly}[1]{}
+\newcommand{\cvalchlambdaonly}[1]{#1}
 
 % File output prefixes
 \newcommand{\outputName}{\emph{outputName}}

src/colvarmodule_refs.h

@@ -227,6 +227,20 @@
     "  url = {https://doi.org/10.1016/0263-7855(96)00018-5}\n"
     "}\n";
 
+  paper_count_[std::string("Lagardere2023")] = 0;
+  paper_url_[std::string("Lagardere2023")] = "https://arxiv.org/abs/2307.08006";
+  paper_bibtex_[std::string("Lagardere2023")] =
+    "\n"
+    "@misc{Lagardere2023,\n"
+    "      title={Lambda-ABF: Simplified, Accurate and Cost-effective Alchemical Free Energy Computations},\n"
+    "      author={Louis Lagard\\`ere and Lise Maurin and Olivier Adjoua and Krystel El Hage and Pierre Monmarch\\'e and Jean-Philip Piquemal and J\\'er\\^ome H\\'enin},\n"
+    "      year={2023},\n"
+    "      eprint={2307.08006},\n"
+    "      archivePrefix={arXiv},\n"
+    "      primaryClass={physics.chem-ph},\n"
+    "      url = {https://arxiv.org/abs/2307.08006}\n"
+    "}\n";
+
   paper_count_[std::string("Lesage2017")] = 0;
   paper_url_[std::string("Lesage2017")] = "https://doi.org/10.1021/acs.jpcb.6b10055";
   paper_bibtex_[std::string("Lesage2017")] =
@@ -525,6 +539,15 @@
   feature_count_[std::string("VMD engine")] = 0;
   feature_paper_map_[std::string("VMD engine")] = "Humphrey1996";
 
+  feature_count_[std::string("alchLambda colvar component")] = 0;
+  feature_paper_map_[std::string("alchLambda colvar component")] = "Lagardere2023";
+
+  feature_count_[std::string("alchFLambda colvar component")] = 0;
+  feature_paper_map_[std::string("alchFLambda colvar component")] = "Lagardere2023";
+
+  feature_count_[std::string("Tinker-HP interface")] = 0;
+  feature_paper_map_[std::string("Tinker-HP interface")] = "Lagardere2023";
+
   feature_count_[std::string("eABF implementation")] = 0;
   feature_paper_map_[std::string("eABF implementation")] = "Lesage2017";