Update mwABF documentation

colvartools/mwABF_selection.tcl

@@ -10,7 +10,7 @@
 # selectFreq    Number of timesteps between  between rounds of replica selection
 #               NOTE: Total simulation time is cycleNum * selectFreq
 # sampleRad     Half-length (in bins) of the interval around the current position of a replica
-#               in which to count samples for selection purposes (1D only, default: 0)
+#               in which to count samples for selection purposes (default: 0)
 # percentStop   Relative difference (in percent) between lowest and highest sample counts
 #               below which no selection is performed (recommended range: 20 to 90, default: 40)
 # biasName      Name of the ABF bias to perform selection on (default: "abf1", Colvars default)

doc/colvars-refman-main.tex

@@ -5528,36 +5528,46 @@
 \end{itemize}
 
 \cvnamdonly{
-\cvsubsubsec{Multiple-replica ABF}{sec:colvarbias_abf_shared}
+\cvsubsubsec{Multiple-walker ABF}{sec:colvarbias_abf_shared}
 \label{sec:mw-ABF}
 
+This implements the multiple-walker ABF scheme described in \cite{Minoukadeh2010}. The reference for this
+implementation is \cite{Comer2014c}.
+This feature requires that \MDENGINE be compiled and executed with multiple-replica
+support.
+
+If \refkey{shared}{abf|shared} is enabled, the total force samples will be synchronized among all replicas
+at intervals defined by \refkey{sharedFreq}{abf|sharedFreq}.
+Each replica maintains a separate buffer of total force samples that determine the biasing force.
+Every \refkey{sharedFreq}{abf|sharedFreq} steps, the replicas communicate the samples that have been gathered since the last synchronization time, ensuring all replicas apply a similar biasing force.
+Thus, it is as if total force samples among all replicas are gathered in a single shared buffer.
+Shared ABF allows all replicas to benefit from the sampling done by other replicas and can lead to faster convergence of the biasing force.
+
+An implementation of the selection mechanism described in \cite{Comer2014c} is provided as a set of Tcl scripts in \texttt{colvartools/mwABF\_selection.tcl} in the Colvars repository.
+Compared with the initial implementation, the current implementation supports selection on sets of up to 3 colvars.
+To reduce noise, samples can be counted in a hybercube around the current bin (see Tcl script for details).
+A set of example NAMD inputs can be found in the \texttt{namd/tests/library/multiple\_walker\_abf} directory.
+
 \begin{itemize}
-\item \keydef{shared}{\texttt{abf}}{%
-    Apply multiple-replica ABF, sharing force samples among the replicas?}
+\item
+  \labelkey{abf|shared}
+  \keydef{shared}{\texttt{abf}}{%
+    Apply multiple-walker ABF, sharing force samples among the replicas?}
   {boolean}
   {\texttt{no}}
-  { This is command requires that NAMD be compiled and executed with multiple-replica
-    support.
-    If \texttt{shared} is set to yes, the total force samples will be synchronized among all replicas
-    at intervals defined by \texttt{sharedFreq}.
-    This implements the multiple-walker ABF scheme described in \cite{Minoukadeh2010}; this
-    implementation is documented in \cite{Comer2014c}.
-    Thus, it is as if total force samples among all replicas are
-    gathered in a single shared buffer, which why the algorithm is referred to as shared ABF.
-    Shared ABF allows all replicas to benefit from the sampling done by other replicas and can lead to faster convergence of the biasing force.
+  {
+    Enable sharing of ABF data between replicas, in a multi-replica simulation.
   }
 
-\item \keydef{sharedFreq}{\texttt{abf}}{%
+\item
+  \labelkey{abf|sharedFreq}
+  \keydef{sharedFreq}{\texttt{abf}}{%
     Frequency (in timesteps) at which force samples are synchronized among the replicas}
   {positive integer or zero}
   {\refkey{outputFreq}{colvarbias|outputFreq}}
   {
-  In the current implementation of shared ABF, each replica maintains a separate
-  buffer of total force samples that determine the biasing force.
-  Every \texttt{sharedFreq} steps, the replicas communicate the samples that
-  have been gathered since the last synchronization time, ensuring all replicas
-  apply a similar biasing force.
-
+    Every \texttt{sharedFreq} steps, the replicas communicate the samples that have been gathered since the last synchronization time.
+    Because this forces the replicas to synchronize, small values of this parameter may slightly reduce the overall throughput, especially on systems with unequal performance.
   }
 \end{itemize}
 }