Multidimensional histograms

The histogram feature is used to record the distribution of a set of collective variables in the form of a N-dimensional histogram. A histogram block may define the following parameters:

• name: see definition of name (biasing and analysis methods)
• colvars: see definition of colvars (biasing and analysis methods)
• outputFreq: see definition of outputFreq (biasing and analysis methods)
• stepZeroData: see definition of stepZeroData (biasing and analysis methods)

• outputFile $\langle\,$ Write the histogram to a file$\,\rangle$
  Context: histogram
  Acceptable values: UNIX filename
  Default value: outputName.$<$ name$>$ .dat
  Description: Name of the file containing histogram data (multicolumn format), which is written every outputFreq steps. For the special case of 2 variables, Gnuplot may be used to visualize this file. If outputFile is set to none, the file is not written.

• outputFileDX $\langle\,$ Write the histogram to a file$\,\rangle$
  Context: histogram
  Acceptable values: UNIX filename
  Default value: outputName.$<$ name$>$ .dx
  Description: Name of the file containing histogram data (OpenDX format), which is written every outputFreq steps. For the special case of 3 variables, VMD may be used to visualize this file. This file is written by default if the dimension is 3 or more. If outputFileDX is set to none, the file is not written.

• gatherVectorColvars $\langle\,$ Treat vector variables as multiple observations of a scalar variable?$\,\rangle$
  Context: histogram
  Acceptable values: UNIX filename
  Default value: off
  Description: When this is set to on, the components of a multi-dimensional colvar (e.g. one based on cartesian, distancePairs, or a vector of scalar numbers given by scriptedFunction) are treated as multiple observations of a scalar variable. This results in the histogram being accumulated multiple times for each simulation step or iteration of cv update). When multiple vector variables are included in histogram, these must have the same length because their components are accumulated together. For example, if $\xi$ , $\lambda$ and $\tau$ are three variables of dimensions 5, 5 and 1, respectively, for each iteration 5 triplets $(\xi_{i},\lambda_{i},\tau)$ ( $i = 1, \ldots 5$ ) are accumulated into a 3-dimensional histogram.

• weights $\langle\,$ Treat vector variables as multiple observations of a scalar variable?$\,\rangle$
  Context: histogram
  Acceptable values: list of space-separated decimals
  Default value: all weights equal to 1
  Description: When gatherVectorColvars is on, the components of each multi-dimensional colvar are accumulated with a different weight. For example, if $x$ and $y$ are two distinct cartesian variables defined on the same group of atoms, the corresponding 2D histogram can be weighted on a per-atom basis: to compute an electron density map, it is possible to use weights [$sel get atomicnumber] in the definition of histogram.

As with any other biasing and analysis method, when a histogram is applied to an extended-system colvar (), it accesses the value of the extended coordinate rather than that of the actual colvar. This can be overridden by enabling the bypassExtendedLagrangian option. A joint histogram of the actual colvar and the extended coordinate may be collected by specifying the colvar name twice in a row in the colvars parameter (e.g. colvars myColvar myColvar): the first instance will be understood as the actual colvar, and the second, as the extended coordinate.

• bypassExtendedLagrangian: see definition of bypassExtendedLagrangian (biasing and analysis methods)

Grid definition for multidimensional histograms

Like the ABF and metadynamics biases, histogram uses the parameters lowerBoundary, upperBoundary, and width to define its grid. These values can be overridden if a configuration block histogramGrid { ...} is provided inside the configuration of histogram. The options supported inside this configuration block are:

• lowerBoundaries $\langle\,$ Lower boundaries of the grid$\,\rangle$
  Context: histogramGrid
  Acceptable values: list of space-separated decimals
  Description: This option defines the lower boundaries of the grid, overriding any values defined by the lowerBoundary keyword of each colvar. Note that when gatherVectorColvars is on, each vector variable is automatically treated as a scalar, and a single value should be provided for it.
• upperBoundaries: analogous to lowerBoundaries
• widths: analogous to lowerBoundaries