WIP: Custom grids for all biases

doc/colvars-refman-main.tex

@@ -4233,6 +4233,7 @@
 
 Many algorithms require the definition of two boundaries and a bin width for each colvar, which are necessary to compute discrete ``states'' for a collective variable's otherwise continuous values.
 The following keywords define these parameters for a specific variable, and will be used by all bias that refer to that variable unless otherwise specified.
+Some of these parameters can be set directly within a bias configuration by inserting a \refkey{grid}{sec:colvarbias_grid} block (\ref{sec:colvarbias_grid}).
 
 \begin{itemize}
 
@@ -4408,7 +4409,7 @@
 of freedom, and the actual geometric colvar (function of Cartesian
 coordinates) only feels the force from the harmonic spring.
 This is particularly useful when combined with an \refkey{abf}{sec:colvarbias_abf} bias
-to perform eABF simulations (\ref{sec:eABF}).
+to perform eABF simulations (\ref{sec:colvarbias_abf_extended}).
 
 Note that for some biases (\refkey{harmonicWalls}{sec:colvarbias_harmonic_walls}, \refkey{histogram}{sec:colvarbias_histogram}),
 this masking behavior is controlled by the keyword \refkey{bypassExtendedLagrangian}{colvarbias|bypassExtendedLagrangian}.
@@ -5223,7 +5224,7 @@
     This option is implemented by the \refkey{harmonicWalls}{sec:colvarbias_harmonic_walls} and
     \refkey{histogram}{sec:colvarbias_histogram} biases.
     It is only relevant if the bias is applied to one or several extended-Lagrangian colvars (\ref{sec:colvar_extended}),
-    for example within an eABF (\ref{sec:eABF}) simulation.
+    for example within an eABF (\ref{sec:colvarbias_abf_extended}) simulation.
     Usually, biases use the value of the extended coordinate as a proxy for the actual colvar, and their biasing forces are applied to the extended coordinates as well.
     If \texttt{bypassExtendedLagrangian} is enabled, the bias behaves as if there were no extended coordinates, and accesses the value of the underlying colvars, applying any biasing forces along the gradients of those variables.}
 
@@ -5258,6 +5259,70 @@
 \end{itemize}
 
 
+
+\cvsubsec{Defining grids for biasing and analysis methods}{sec:colvarbias_grid}
+
+Several methods (\hyperlink{sec:colvarbias_histogram}{histograms}, \hyperlink{sec:colvarbias_abf}{ABF} and \hyperlink{sec:colvarbias_abf_extended}{eABF}, optionally \hyperlink{sec:colvarbias_metadynamics}{metadynamics}) rely on discretizing colvars on regular grids to represent functions such as probability distributions or free energy surfaces.
+
+Grid parameters are specific to each variable, and some of them may even be defined automatically: for instance, periodic angles have default boundaries of -180$^\circ$ and 180$^\circ$.
+When not given by default, boundaries may be also specified when defining the collective variable itself (\ref{sec:colvar_grid_params}).
+
+Each bias will use by default any colvar boundaries that are automatically defined or explicitly given.
+Optionally, the bias may also contain a dedicated configuration block \texttt{grid \{ \ldots \}} inside its configuration.
+The options supported within the \texttt{grid \{ \ldots \}} block are:
+
+\begin{itemize}
+\item %
+  \key{%
+    lowerBoundary}{%
+    \texttt{grid}}{%
+    Lower boundaries of the grid}{%
+    list of space-separated decimals}{%
+    This option is specified once, and takes as many parameters as there are colvars associated with this bias.
+    It defines the lower boundaries of the grid, overriding any values defined by the \refkey{lowerBoundary}{colvar|lowerBoundary} keyword of each colvar.
+  }
+\item %
+  \simkey{upperBoundary}{\texttt{grid}}{lowerBoundary}
+\item %
+  \key{%
+    width}{%
+    \texttt{grid}}{%
+    Bin widths of the grid}{%
+    list of space-separated decimals}{%
+    This option is specified once, and takes as many parameters as there are colvars associated with this bias.
+    It defines the bin widths of the grid along each dimension, overriding any values defined by the \refkey{width}{colvar|width} keyword of each colvar.
+  }
+\end{itemize}
+
+\noindent\textbf{Example:} Definition of custom grid parameters for a histogram.  Note how some of the boundaries of the variables are automatically defined, but this histogram's grid is custom-defined to also specify a finer width and narrower boundaries.
+\begin{cvexampleinput}
+\-colvar~\{\\
+\-\-~~name~r\\
+\-\-~~\#~lowerBoundary~0.0~is~automatically~defined\\
+\-\-~~upperBoundary~20.0\\
+\-\-~~distance~\{~...~\}\\
+\-\}\\
+\\
+\-colvar~\{\\
+\-\-~~name~theta\\
+\-\-~~\#~lowerBoundary~-180.0~is~automatically~defined\\
+\-\-~~\#~upperBoundary~180.0~is~automatically~defined\\
+\-\-~~dihedral~\{~...~\}\\
+\-\}\\
+\\
+\-histogram~\{\\
+\-\-~~name~hist2d\\
+\-\-~~colvars~r~theta\\
+\-\-~~grid~\{\\
+\-\-~~~~width~~0.1~1.0\\
+\-\-~~~~lowerBoundary~~~2.0~30.0\\
+\-\-~~~~upperBoundary~~10.0~90.0\\
+\-\-~~\}\\
+\-\}\\
+\end{cvexampleinput}
+
+
+
 \cvsubsec{Thermodynamic integration}{sec:colvarbias_ti}
 
 The methods implemented here provide a variety of estimators of conformational free-energies.
@@ -5318,7 +5383,7 @@
 
 Combining ABF with the extended Lagrangian feature (\ref{sec:colvar_extended})
 of the variables produces the extended-system ABF variant of the method
-(\ref{sec:eABF}).
+(\ref{sec:colvarbias_abf_extended}).
 
 ABF is based on the thermodynamic integration (TI) scheme for
 computing free energy profiles. The free energy as a function
@@ -5421,7 +5486,7 @@
 The following conditions must be met for an ABF simulation to be possible and
 to produce an accurate estimate of the free energy profile.
 Note that these requirements do not apply when using the extended-system
-ABF method (\ref{sec:eABF}).
+ABF method (\ref{sec:colvarbias_abf_extended}).
 
 \begin{enumerate}
  \item \emph{Only linear combinations} of colvar components can be used in ABF calculations.
@@ -5459,7 +5524,8 @@
 
 \cvsubsubsec{Parameters for ABF}{sec:colvarbias_abf_params}
 
-ABF depends on parameters from each collective variable to define the grid on which free energy gradients are computed: see \ref{sec:colvar_grid_params} for detauls.
+ABF depends on parameters from each collective variable to define the grid on which free energy gradients are computed: see \ref{sec:colvar_grid_params} for details.
+Alternately, grid parameters can be set directly inside the ABF block by inserting a \texttt{grid} sub-block, as explained in \ref{sec:colvarbias_grid}.
 Other parameters to control the ABF runtime can be set in the ABF configuration block:
 
 \begin{itemize}
@@ -5763,8 +5829,7 @@
 
 
 
-\cvsubsec{Extended-system Adaptive Biasing Force (eABF)}{sec:ecolvarbias_abf_extended}
-\label{sec:eABF}
+\cvsubsec{Extended-system Adaptive Biasing Force (eABF)}{sec:colvarbias_abf_extended}
 
 Extended-system ABF (eABF) is a variant of ABF (\ref{sec:colvarbias_abf})
 where the bias is not applied
@@ -7489,7 +7554,7 @@
 
 The \texttt{histogram} feature is used to record the distribution of a set of collective variables in the form of a N-dimensional histogram.  Defining such a histogram is generally useful for analysis purposes, but it has no effect on the simulation.
 
-\noindent\textbf{Example 1:} the two-dimensional histogram of a distance and an angle can be generated using the configuration below.  The histogram code requires that each variable is a scalar number that is confined within a pre-defined interval.  The interval's boundaries may be specified by hand (e.g.{} through \refkey{lowerBoundary}{colvar|lowerBoundary} and \refkey{upperBoundary}{colvar|upperBoundary} in the variable definition), or auto-detected based on the type of function.  In this example, the lower boundary for the distance variable ``\texttt{r}'' is automatically set to zero, and interval for the three-body angle ``\texttt{theta}'' is $0^\circ$ and $180^\circ$: however, that an upper boundary for the distance ``\texttt{r}'' still needs to be specified manually.  The grid spacings for the two variables are $0.2$~\lengthunit and $3.0^\circ$, respectively.
+\noindent\textbf{Example:} the two-dimensional histogram of a distance and an angle can be generated using the configuration below.  The histogram code requires that each variable is a scalar number that is confined within a pre-defined interval.  The interval's boundaries may be specified by hand (e.g.{} through \refkey{lowerBoundary}{colvar|lowerBoundary} and \refkey{upperBoundary}{colvar|upperBoundary} in the variable definition), or auto-detected based on the type of function.  In this example, the lower boundary for the distance variable ``\texttt{r}'' is automatically set to zero, and interval for the three-body angle ``\texttt{theta}'' is $0^\circ$ and $180^\circ$: however, that an upper boundary for the distance ``\texttt{r}'' still needs to be specified manually.  The grid spacings for the two variables are $0.2$~\lengthunit and $3.0^\circ$, respectively.
 % Note: a three-body angle is used to support NAMD users, because the
 % init_as_periodic_angle() function was added after the NAMD 2.14 release.
 \begin{cvexampleinput}
@@ -7512,64 +7577,22 @@
 \-\}\\
 \end{cvexampleinput}
 
-\noindent\textbf{Example 2:} This example is similar to the previous one, but with the important difference that the parameters for the histogram's grid are defined \emph{explicitly} for this histogram instance.  Therefore, this histogram's grid may differ from the one defined from parameters embedded in the \texttt{colvar~\{~...~\}} block (for example, narrower intervals and finer grid spacings may be selected).
-\begin{cvexampleinput}
-\-colvar~\{\\
-\-\-~~name~r\\
-\-\-~~upperBoundary~20.0\\
-\-\-~~distance~\{~...~\}\\
-\-\}\\
-\\
-\-colvar~\{\\
-\-\-~~name~theta\\
-\-\-~~dihedral~\{~...~\}\\
-\-\}\\
-\\
-\-histogram~\{\\
-\-\-~~name~hist2d\\
-\-\-~~colvars~r~theta\\
-\-\-~~histogramGrid~\{\\
-\-\-~~~~widths~~0.1~1.0\\
-\-\-~~~~lowerBoundaries~~~2.0~30.0\\
-\-\-~~~~upperBoundaries~~10.0~90.0\\
-\-\-~~\}\\
-\-\}\\
-\end{cvexampleinput}
-
 
-The standard keywords below are used to control the histogram's computation and to select the variables that are sampled.  See also \ref{sec:colvarbias_histogram_grid} for keywords used to define the grid, \ref{sec:colvarbias_histogram_output} for output parameters and \ref{sec:colvarbias_histogram_vectors} for more advanced keywords.
+The standard keywords below are used to control the histogram's computation and to select the variables that are sampled.  See also \ref{sec:colvarbias_grid} for keywords used to define the grid, \ref{sec:colvarbias_histogram_output} for output parameters and \ref{sec:colvarbias_histogram_vectors} for more advanced keywords.
 
 \begin{itemize}
 
 \item \dupkey{name}{\texttt{histogram}}{sec:colvarbias}{biasing and analysis methods}
 \item \dupkey{colvars}{\texttt{histogram}}{sec:colvarbias}{biasing and analysis methods}
-% \item \dupkey{outputEnergy}{\texttt{histogram}}{sec:colvarbias}{biasing and analysis methods}
 \item \dupkey{stepZeroData}{\texttt{histogram}}{sec:colvarbias}{biasing and analysis methods}
 
 \end{itemize}
 
 
-\cvsubsubsec{Defining grids for multidimensional histograms}{sec:colvarbias_histogram_grid}
-
-Grid parameters for the histogram may be provided at the level of the individual variables, or via a dedicated configuration block \texttt{histogramGrid \{ \ldots \}} inside the configuration of this \texttt{histogram}.
-The options supported \emph{inside this block} are:
-
-\begin{itemize}
+Grid parameters for the histogram may be provided at the level of the individual variables, or via a dedicated configuration block \texttt{grid \{ \ldots \}} inside the configuration of this \texttt{histogram}.
+The options supported \emph{inside this block} are described in \ref{sec:colvarbias_grid}.
 
-\item %
-  \key{%
-    lowerBoundaries}{%
-    \texttt{histogramGrid}}{%
-    Lower boundaries of the grid}{%
-    list of space-separated decimals}{%
-    This option defines the lower boundaries of the grid, overriding any values defined by the \texttt{lowerBoundary} keyword of each colvar.
-    Note that when \texttt{gatherVectorColvars} is \texttt{on}, each vector variable is automatically treated as a scalar, and a single value should be provided for it.
-  }
-\item %
-  \simkey{upperBoundaries}{\texttt{histogramGrid}}{lowerBoundaries}
-\item %
-  \simkey{widths}{\texttt{histogramGrid}}{lowerBoundaries}
-\end{itemize}
+Note that when \texttt{gatherVectorColvars} is \texttt{on}, each vector variable is automatically treated as a scalar, and a single value of each grid parameter should be provided for it.
 
 
 \cvsubsubsec{Output options for multi-dimensional histograms}{sec:colvarbias_histogram_output}

gromacs/tests/library/000_distance-dihedral_histogram2d-periodic-customgrid/test.in

@@ -38,9 +38,9 @@ colvar {
 
 histogram {
     colvars r phi
-    histogramGrid {
-        widths  0.2 6.0
-        lowerBoundaries   0.0   0.0
-        upperBoundaries  10.0 360.0
+    grid {
+        width  0.2 6.0
+        lowerBoundary   0.0   0.0
+        upperBoundary  10.0 360.0
     }
 }

lammps/tests/library/000_distance-dihedral_histogram2d-periodic-customgrid/test.in

@@ -38,9 +38,9 @@ colvar {
 
 histogram {
     colvars r phi
-    histogramGrid {
-        widths  0.2 6.0
-        lowerBoundaries   0.0   0.0
-        upperBoundaries  10.0 360.0
+    grid {
+        width  0.2 6.0
+        lowerBoundary   0.0   0.0
+        upperBoundary  10.0 360.0
     }
 }

lammps/tests/library/000_distance-grid_histogram-customgrid/test.in

@@ -26,9 +26,9 @@ colvar {
 
 histogram {
     colvars    one
-    histogramGrid {
-        widths 0.2
-        lowerBoundaries 0.6
-        upperBoundaries 5.4
+    grid {
+        width 0.2
+        lowerBoundary 0.6
+        upperBoundary 5.4
     }
 }

namd/tests/library/000_dihedral_histogram-customgrid-periodic/test.in

@@ -28,9 +28,9 @@ colvar {
 
 histogram {
     colvars    one
-    histogramGrid {
-        widths 5
-        lowerBoundaries -60
-        upperBoundaries 300
+    grid {
+        width 5
+        lowerBoundary -60
+        upperBoundary 300
     }
 }

namd/tests/library/000_distance-dihedral_histogram2d-periodic-customgrid/AutoDiff/test.colvars.out

@@ -2,12 +2,14 @@ colvars: ----------------------------------------------------------------------
 colvars: Please cite Fiorin et al, Mol Phys 2013:
 colvars:   https://doi.org/10.1080/00268976.2013.813594
 colvars: as well as all other papers listed below for individual features used.
-colvars: SMP parallelism is enabled; if needed, use "smp off" to override this.
 colvars: This version was built with the C++11 standard or higher.
+colvars: Summary of compile-time features available in this build:
+colvars:   - SMP parallelism: enabled (num. threads = 4)
+colvars:   - Lepton custom functions: available
+colvars:   - Tcl interpreter: available
 colvars: Redefining the Tcl "cv" command to the new script interface.
 colvars: The restart output state file will be "test.tmp.colvars.state".
 colvars: The final output state file will be "test.colvars.state".
-colvars: Opening trajectory file "test.colvars.traj".
 colvars: ----------------------------------------------------------------------
 colvars: Reading new configuration from file "test.in":
 colvars: # units = "" [default]
@@ -111,7 +113,7 @@ colvars:   Initializing a new "dihedral" component.
 colvars:     # name = "" [default]
 colvars:     # componentCoeff = 1 [default]
 colvars:     # componentExp = 1 [default]
-colvars:     # period = 0 [default]
+colvars:     # period = 360 [default]
 colvars:     # wrapAround = 0 [default]
 colvars:     # forceNoPBC = off [default]
 colvars:     # scalable = on [default]
@@ -229,19 +231,21 @@ colvars: - NAMD engine:
 colvars: - Scalable center-of-mass computation (NAMD):
 colvars:   Phillips2020 https://doi.org/10.1063/5.0014475
 colvars: 
+colvars: updating target temperature (T = 0 K).
 colvars: Updating NAMD interface:
 colvars: updating atomic data (0 atoms).
 colvars: updating group data (4 scalable groups, 16 atoms in total).
 colvars: updating grid object data (0 grid objects in total).
+colvars: updating target temperature (T = 0 K).
+colvars: Current simulation parameters: initial step = 0, integration timestep = 1
+colvars: Updating atomic parameters (masses, charges, etc).
 colvars: Re-initialized atom group for variable "r":0/0. 4 atoms: total mass = 54.028, total charge = -0.72.
 colvars: Re-initialized atom group for variable "r":0/1. 4 atoms: total mass = 54.028, total charge = -0.4.
 colvars: Re-initialized atom group for variable "phi":0/0. 4 atoms: total mass = 54.028, total charge = -0.72.
 colvars: Re-initialized atom group for variable "phi":0/1. 4 atoms: total mass = 54.028, total charge = -0.4.
 colvars: Re-initialized atom group for variable "phi":0/2. 4 atoms: total mass = 54.028, total charge = -0.4.
 colvars: Re-initialized atom group for variable "phi":0/3. 4 atoms: total mass = 54.028, total charge = -0.4.
 colvars: The restart output state file will be "test.tmp.colvars.state".
-colvars: The final output state file will be "test.colvars.state".
-colvars:   Histogram histogram1 will be written to file "test.histogram1.dat"
 colvars: Synchronizing (emptying the buffer of) trajectory file "test.colvars.traj".
 colvars: Synchronizing (emptying the buffer of) trajectory file "test.colvars.traj".
 colvars: Saving collective variables state to "test.tmp.colvars.state".

namd/tests/library/000_distance-dihedral_histogram2d-periodic-customgrid/AutoDiff/test.colvars.state.stripped

@@ -5,19 +5,20 @@ configuration {
 
 colvar {
   name r
-  x  3.21688253464583e+00
+  x       3.2168825344401
 }
 
 colvar {
   name phi
-  x  6.02774557527018e+01
+  x       60.277455741941
 }
 
 histogram {
   configuration {
     step 20
     name histogram1
   }
+
 grid
  0 0 0 0 0 0 0 0
  0 0 0 0 0 0 0 0

namd/tests/library/000_distance-dihedral_histogram2d-periodic-customgrid/AutoDiff/test.colvars.traj

@@ -1,22 +1,22 @@
 # step         r                      phi                   
            0    3.20554673468334e+00   6.31129478791928e+01 
-           1    3.20437148316546e+00   6.30795952609024e+01 
-           2    3.20384028589204e+00   6.30231590817356e+01 
-           3    3.20396721187433e+00   6.29423176380356e+01 
-           4    3.20472817287036e+00   6.28366833861828e+01 
-           5    3.20606308066645e+00   6.27068898721072e+01 
-           6    3.20787989003051e+00   6.25546017866590e+01 
-           7    3.21005997943917e+00   6.23824530261739e+01 
-           8    3.21246460655188e+00   6.21939260051983e+01 
-           9    3.21494247388772e+00   6.19931890919450e+01 
-          10    3.21733851236362e+00   6.17849080688927e+01 
-          11    3.21950367383415e+00   6.15740450245643e+01 
-          12    3.22130499858006e+00   6.13656547661594e+01 
-          13    3.22263479496346e+00   6.11646847438178e+01 
-          14    3.22341769665784e+00   6.09757828950022e+01 
-          15    3.22361473677138e+00   6.08031168346083e+01 
-          16    3.22322417514557e+00   6.06502098509209e+01 
-          17    3.22227942564879e+00   6.05198025353684e+01 
-          18    3.22084479803044e+00   6.04137510912894e+01 
-          19    3.21900979846930e+00   6.03329741083708e+01 
-          20    3.21688253464583e+00   6.02774557527018e+01 
+           1    3.20437148316484e+00   6.30795952608635e+01 
+           2    3.20384028588952e+00   6.30231590815800e+01 
+           3    3.20396721186862e+00   6.29423176376863e+01 
+           4    3.20472817286016e+00   6.28366833855655e+01 
+           5    3.20606308065050e+00   6.27068898711517e+01 
+           6    3.20787989000758e+00   6.25546017852999e+01 
+           7    3.21005997940810e+00   6.23824530243513e+01 
+           8    3.21246460651160e+00   6.21939260028577e+01 
+           9    3.21494247383722e+00   6.19931890890363e+01 
+          10    3.21733851230199e+00   6.17849080653709e+01 
+          11    3.21950367376059e+00   6.15740450203887e+01 
+          12    3.22130499849384e+00   6.13656547612945e+01 
+          13    3.22263479486396e+00   6.11646847382338e+01 
+          14    3.22341769654449e+00   6.09757828886765e+01 
+          15    3.22361473664369e+00   6.08031168275266e+01 
+          16    3.22322417500307e+00   6.06502098430778e+01 
+          17    3.22227942549106e+00   6.05198025267681e+01 
+          18    3.22084479785707e+00   6.04137510819449e+01 
+          19    3.21900979827991e+00   6.03329740983038e+01 
+          20    3.21688253444007e+00   6.02774557419408e+01