Defining collective variables and their properties

In the configuration file each colvar is defined by the keyword colvar, followed by its configuration options within curly braces: colvar { ... }. One of these options is the name of a colvar component: for example, including rmsd { ... } defines the colvar as a RMSD function. In most applications, only one component is used, and the component is equal to the colvar.

The full list of colvar components can be found in Section 10.4, with the syntax to select atoms in Section 10.3. The following section lists several options to control the behavior of a single colvar, regardless of its type.

General options for a collective variable

The following options are not required by default; however, the first four are very frequently used:

• name $<$ Name of this colvar $>$
  Context: colvar
  Acceptable Values: string
  Default Value: ``colvar'' + numeric id
  Description: The name is an unique case-sensitive string which allows the colvar module to identify this colvar unambiguously; it is also used in the trajectory file to label to the columns corresponding to this colvar.

• width $<$ Colvar fluctuation scale, or resolution for grid-based methods $>$
  Context: colvar
  Acceptable Values: positive decimal
  Default Value: 1.0
  Description: This number has the same physical unit as the colvar value and defines an effective colvar unit. Biasing algorithms use it for different purposes. Harmonic restraints (10.5.3) use it to set the physical unit of the force constant, which is useful for multidimensional restraints involving colvars with different units or scale which may then be defined by a single, scaled force constant. Histogram (10.5.6) and ABF biases (10.5.1) interpret it as the grid spacing in the direction of this variable. Metadynamics (10.5.2) uses it to set the width of newly added hills. In other cases, it is simplest to keep the default value of 1, so that harmonic force constants are provided in their usual physical unit. When a non-unity width is required by the application, the optimal value is application-dependent, but can often be thought of as a user-provided estimate of the fluctuation amplitude for the colvar. In those cases, it should generally be set smaller than or equal to the standard deviation of the colvar during a very short simulation run.

• lowerBoundary $<$ Lower boundary of the colvar $>$
  Context: colvar
  Acceptable Values: decimal
  Description: Defines the lowest end of the interval of ``relevant'' values for the colvar. This number can be either a true physical boundary, or a user-defined number. Together with upperBoundary and width, it is used to define a grid of values along the colvar (not available for colvars based on distanceDir, distanceVec, and orientation). This option does not affect dynamics: to confine a colvar within a certain interval, the options lowerWall and lowerWallConstant should be used.

• upperBoundary $<$ Upper boundary of the colvar $>$
  Context: colvar
  Acceptable Values: decimal
  Description: Similarly to lowerBoundary, defines the highest possible or allowed value.

• hardLowerBoundary $<$ Whether the lower boundary is the physical lower limit $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: off
  Description: This option does not affect simulation results, but enables some internal optimizations. Depending on its mathematical definition, a colvar may have ``natural'' boundaries: for example, a distance colvar has a ``natural'' lower boundary at 0. Setting this option instructs the colvars module that the user-defined lower boundary is ``natural''. See Section 10.4 for the physical ranges of values of each component.

• hardUpperBoundary $<$ Whether the upper boundary is the physical upper limit of the colvar's values $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: off
  Description: Analogous to hardLowerBoundary.

• expandBoundaries $<$ Allow to expand the two boundaries if needed $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: off
  Description: If defined, biasing and analysis methods may keep their own copies of lowerBoundary and upperBoundary, and expand them to accommodate values that do not fit in the initial range. Currently, this option is used by the metadynamics bias (10.5.2) to keep all of its hills fully within the grid. This option cannot be used when the initial boundaries already span the full period of a periodic colvar.

Artificial boundary potentials (walls)

The following options are useful to define restraints (confining potentials) for this colvar. To apply moving restraints, or restraints to more than one colvar simultaneously, a more convenient option is to use the harmonic bias (10.5.3). When using an extended Lagrangian, the boundary potential is applied to the ``actual'' colvar, in contrast with forces for all types of biases, which are applied to the extended coordinate.

• lowerWallConstant $<$ Lower wall force constant (kcal/mol/U$^2$ ) $>$
  Context: colvar
  Acceptable Values: positive decimal
  Description: Defines the force constant for a confining restraint on the colvar, in the form of a ``half-harmonic'' potential. The potential starts at lowerWall if it is defined, or lowerBoundary otherwise. The energy unit of the constant is kcal/mol, while the spatial unit U is that of the colvar.

• lowerWall $<$ Position of the lower wall $>$
  Context: colvar
  Acceptable Values: decimal
  Default Value: lowerBoundary
  Description: Defines the value below which a confining restraint on the colvar is applied, in the form of a ``half-harmonic'' potential. Allows to use a different position of the wall than lowerBoundary.

• upperWallConstant $<$ Upper wall force constant (kcal/mol/U$^2$ ) $>$
  Context: colvar
  Acceptable Values: positive decimal
  Description: Analogous to lowerWallConstant.

• upperWall $<$ Position of the upper wall $>$
  Context: colvar
  Acceptable Values: decimal
  Default Value: upperBoundary
  Description: Analogous to lowerWall.

Trajectory output

• outputValue $<$ Output a trajectory for this colvar $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: on
  Description: If colvarsTrajFrequency is non-zero, the value of this colvar is written to the trajectory file every colvarsTrajFrequency steps in the column labeled ``$<$ name$>$ ''.

• outputVelocity $<$ Output a velocity trajectory for this colvar $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: off
  Description: If colvarsTrajFrequency is defined, the finite-difference calculated velocity of this colvar are written to the trajectory file under the label ``v_$<$ name$>$ ''.

• outputEnergy $<$ Output an energy trajectory for this colvar $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: off
  Description: This option applies only to extended Lagrangian colvars. If colvarsTrajFrequency is defined, the kinetic energy of the extended degree and freedom and the potential energy of the restraining spring are are written to the trajectory file under the labels ``Ek_$<$ name$>$ '' and ``Ep_$<$ name$>$ ''.

• outputSystemForce $<$ Output a system force trajectory for this colvar $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: off
  Description: If colvarsTrajFrequency is defined, the total system force on this colvar (i.e. the projection of all interatomic forces except constraint forces on this colvar -- see equation (53) in section 10.5.1) are written to the trajectory file under the label ``fs_$<$ name$>$ ''. For extended Lagrangian colvars, the "system force" felt by the extended degree of freedom is simply the force from the harmonic spring. Note: not all components support this option. The physical unit for this force is kcal/mol, divided by the colvar unit U.

• outputAppliedForce $<$ Output an applied force trajectory for this colvar $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: off
  Description: If colvarsTrajFrequency is defined, the total force applied on this colvar by biases and confining potentials (walls) within the colvar module are written to the trajectory under the label ``fa_$<$ name$>$ ''. For extended Lagrangian colvars, this force is actually applied to the extended degree of freedom rather than the geometric colvar itself. The physical unit for this force is kcal/mol divided by the colvar unit.

Extended Lagrangian.

The following options enable extended-system dynamics, where a colvar is coupled to an additional degree of freedom (fictitious particle) by a harmonic spring. All biasing and confining forces are then applied to the extended degree of freedom. The ``actual'' geometric colvar (function of Cartesian coordinates) only feels the force from the harmonic spring and its wall potentials, if any.

• extendedLagrangian $<$ Add extended degree of freedom $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: off
  Description: Adds a fictitious particle to be coupled to the colvar by a harmonic spring. The fictitious mass and the force constant of the coupling potential are derived from the parameters extendedTimeConstant and extendedFluctuation, described below. Biasing forces on the colvar are applied to this fictitious particle, rather than to the atoms directly. This implements the extended Lagrangian formalism used in some metadynamics simulations [37]. The energy associated with the extended degree of freedom is reported under the MISC title in NAMD's energy output.

• extendedFluctuation $<$ Standard deviation between the colvar and the fictitious particle (colvar unit) $>$
  Context: colvar
  Acceptable Values: positive decimal
  Description: Defines the spring stiffness for the extendedLagrangian mode, by setting the typical deviation between the colvar and the extended degree of freedom due to thermal fluctuation. The spring force constant is calculated internally as $k_B T / \sigma^2$ , where $\sigma$ is the value of extendedFluctuation.

• extendedTimeConstant $<$ Oscillation period of the fictitious particle (fs) $>$
  Context: colvar
  Acceptable Values: positive decimal
  Default Value: 200
  Description: Defines the inertial mass of the fictitious particle, by setting the oscillation period of the harmonic oscillator formed by the fictitious particle and the spring. The period should be much larger than the MD time step to ensure accurate integration of the extended particle's equation of motion. The fictitious mass is calculated internally as $k_B T (\tau/2 \pi \sigma)^2$ , where $\tau$ is the period and $\sigma$ is the typical fluctuation (see above).

• extendedTemp $<$ Temperature for the extended degree of freedom (K) $>$
  Context: colvar
  Acceptable Values: positive decimal
  Default Value: thermostat temperature
  Description: Temperature used for calculating the coupling force constant of the extended coordinate (see extendedFluctuation) and, if needed, as a target temperature for extended Langevin dynamics (see extendedLangevinDamping). This should normally be left at its default value.

• extendedLangevinDamping $<$ Damping factor for extended Langevin dynamics (ps$^{-1}$ ) $>$
  Context: colvar
  Acceptable Values: positive decimal
  Default Value: 1.0
  Description: If this is non-zero, the extended degree of freedom undergoes Langevin dynamics at temperature extendedTemp. The friction force is minus extendedLangevinDamping times the velocity. This is useful because the extended dynamics coordinate may heat up in the transient non-equilibrium regime of ABF. Use moderate damping values, to limit viscous friction (potentially slowing down diffusive sampling) and stochastic noise (increasing the variance of statistical measurements). In doubt, use the default value.

Statistical analysis of collective variables

When the global keyword analysis is defined in the configuration file, run-time calculations of statistical properties for individual colvars can be performed. At the moment, several types of time correlation functions, running averages and running standard deviations are available.

• corrFunc $<$ Calculate a time correlation function? $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: off
  Description: Whether or not a time correlaction function should be calculated for this colvar.

• corrFuncWithColvar $<$ Colvar name for the correlation function $>$
  Context: colvar
  Acceptable Values: string
  Description: By default, the auto-correlation function (ACF) of this colvar, $\xi_{i}$ , is calculated. When this option is specified, the correlation function is calculated instead with another colvar, $\xi_{j}$ , which must be of the same type (scalar, vector, or quaternion) as $\xi_{i}$ .

• corrFuncType $<$ Type of the correlation function $>$
  Context: colvar
  Acceptable Values: velocity, coordinate or coordinate_p2
  Default Value: velocity
  Description: With coordinate or velocity, the correlation function $C_{i,j}(t)$  = $\left\langle \Pi\left(\xi_{i}(t_{0}), \xi_{j}(t_{0}+t)\right) \right\rangle$ is calculated between the variables $\xi_{i}$ and $\xi_{j}$ , or their velocities. $\Pi(\xi_{i}, \xi_{j})$ is the scalar product when calculated between scalar or vector values, whereas for quaternions it is the cosine between the two corresponding rotation axes. With coordinate_p2, the second order Legendre polynomial, $(3\cos(\theta)^{2}-1)/2$ , is used instead of the cosine.

• corrFuncNormalize $<$ Normalize the time correlation function? $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: on
  Description: If enabled, the value of the correlation function at $t$  = 0 is normalized to 1; otherwise, it equals to $\left\langle O\left(\xi_{i}, \xi_{j}\right) \right\rangle$ .

• corrFuncLength $<$ Length of the time correlation function $>$
  Context: colvar
  Acceptable Values: positive integer
  Default Value: 1000
  Description: Length (in number of points) of the time correlation function.

• corrFuncStride $<$ Stride of the time correlation function $>$
  Context: colvar
  Acceptable Values: positive integer
  Default Value: 1
  Description: Number of steps between two values of the time correlation function.

• corrFuncOffset $<$ Offset of the time correlation function $>$
  Context: colvar
  Acceptable Values: positive integer
  Default Value: 0
  Description: The starting time (in number of steps) of the time correlation function (default: $t$  = 0). Note: the value at $t$  = 0 is always used for the normalization.

• corrFuncOutputFile $<$ Output file for the time correlation function $>$
  Context: colvar
  Acceptable Values: UNIX filename
  Default Value: $<$ name$>$ .corrfunc.dat
  Description: The time correlation function is saved in this file.

• runAve $<$ Calculate the running average and standard deviation $>$
  Context: colvar
  Acceptable Values: boolean
  Default Value: off
  Description: Whether or not the running average and standard deviation should be calculated for this colvar.

• runAveLength $<$ Length of the running average window $>$
  Context: colvar
  Acceptable Values: positive integer
  Default Value: 1000
  Description: Length (in number of points) of the running average window.

• runAveStride $<$ Stride of the running average window values $>$
  Context: colvar
  Acceptable Values: positive integer
  Default Value: 1
  Description: Number of steps between two values within the running average window.

• runAveOutputFile $<$ Output file for the running average and standard deviation $>$
  Context: colvar
  Acceptable Values: UNIX filename
  Default Value: $<$ name$>$ .runave.dat
  Description: The running average and standard deviation are saved in this file.