next up previous contents index
Next: Defining collective variables Up: Collective Variable-based Calculations (Colvars) Previous: Writing a Colvars configuration:   Contents   Index


Enabling and controlling the Colvars module in NAMD

Here, we document the syntax of the commands and parameters used to set up and use the Colvars module in NAMD. One of these parameters is the configuration file or the configuration text for the module itself, whose syntax is described in 9.2.4 and in the following sections.

Units in the Colvars module

The ``internal units'' of the Colvars module are the units in which values are expected to be in the configuration file, and in which collective variable values, energies, etc. are expressed in the output and colvars trajectory files. Generally the Colvars module uses internally the same units as its back-end MD engine, with the exception of VMD, where different unit sets are supported to allow for easy setup, visualization and analysis of Colvars simulations performed with any simulation engine.

Note that angles are expressed in degrees, and derived quantites such as force constants are based on degrees as well. Atomic coordinates read from XYZ files (and PDB files where applicable) are expected to be expressed in Ångström, no matter what unit system is in use by the back-end or the Colvars Module.

To avoid errors due to reading configuration files written in a different unit system, it can be specified within the input:

NAMD parameters

To enable a Colvars-based calculation, the colvars on command must be added to the NAMD script. Two optional commands, colvarsConfig and colvarsInput can be used to define the module's configuration or continue a previous simulation. Because these are static parameters, it is typically more convenient to use the cv command in the rest of the NAMD script.

Using the cv command to control the Colvars module

At any moment after the first initialization of the Colvars module, several options can be read or modified by the Tcl command cv, with the following syntax:
cv $ <$ subcommand$ >$ [args ...]
The most frequent uses of the cv command are discussed here. For a complete list of all sub-commands of cv, see section 9.6.

Setting up the Colvars module

If the NAMD configuration parameter colvars is on, the cv command can be used anywhere in the NAMD script, and will be invoked as soon as NAMD begins processing Tcl commands.

To define collective variables and biases, configuration can be loaded using either:
cv configfile
to load configuration from a file, or:
cv config "keyword { ... }"
to load configuration as a string argument.

The latter version is particularly useful to dynamically define the Colvars configuration. For example, when running an ensemble of umbrella sampling simulations in NAMD, it may be convenient to use an identical NAMD script, and let the queuing system assist in defining the window. In this example, in a Slurm array job an environment variable is used to define the window's numeric index (starting at zero), and the umbrella restraint center (starting at 2 for the first window, and increasing in increments of 0.25 for all other windows):
cv configfile
set window $env(SLURM_ARRAY_TASK_ID)
cv config "harmonic {
  name us_${window}
  colvars xi
  centers [expr 2.0 + 0.25 * ${window}]

Using the Colvars version in scripts

The vast majority of the syntax in Colvars is backward-compatible, adding keywords when new features are introduced. However, when using multiple versions simultaneously it may be useful to test within the script whether the version is recent enough to support the desired feature. cv version can be used to get the Colvars version for this use:
if { [cv version] >= "2020-02-25" } {
  cv config "(use a recent feature)"

Loading and saving the Colvars state and other information

After a configuration is fully defined, cv load may be used to load a state file from a previous simulation that contains e.g. data from history-dependent biases), to either continue that simulation or analyze its results:
cv load $ <$ oldjob$ >$ .colvars.state
or more simply using the prefix of the state file itself:
cv load $ <$ oldjob$ >$
The latter is much more convenient in combination with the NAMD reinitatoms command, for example:
reinitatoms $ <$ oldjob$ >$
cv load $ <$ oldjob$ >$
The step number contained by the loaded file will be used internally by Colvars to control time-dependent biases, unless firstTimestep is issued, in which case that value will be used.

When the system's topology is changed during simulation via the structure command (e.g. in constant-pH simulations), it is generally best to reset and re-initalize the module from scratch before loading the corresponding snapshot:
structure newsystem.psf
reinitatoms $ <$ snapshot$ >$
cv reset
cv configfile ...
cv load $ <$ snapshot$ >$

cv save, analogous to cv load, saves all restart information to a state file. This is normally not required during a simulation if colvarsRestartFrequency (see 9.2.5) is defined (either directly or indirectly by the NAMD restart frequency), but it is necessary in post-processing e.g. with VMD. Because not only a state file (used to continue simulations) but also other data files (used to analyze the trajectory) are written, it is generally clearer to use cv save with a prefix rather than a file name:
cv save $ <$ job$ >$

See 9.6.1 for a complete list of scripting commands used to manage the Colvars module.

Managing collective variables

After one or more collective variables are defined, they can be accessed via cv colvar [args ...]. For example, to recompute the collective variable xi the following command can be used:
cv colvar xi update
This ordinarily is not needed during a simulation run, where all variables are recomputed at every step (along with biasing forces acting on them). However, when analyzing an existing trajectory a call to update is generally required.

While in all typical cases all configuration of the variables is done with cv config or cv configfile, a limited set of changes can be enacted at runtime using cv colvar $ <$ name$ >$ modifycvcs [args ...]. Each argument is a string passed to the function or functions that are used to compute the variable, and are called colvar components, or CVCs (9.3.1). For example, a variable DeltaZ made of a single distanceZ CVC can be made periodic with a period equal to the unit cell dimension along the Z-axis:
cv colvar DeltaZ modifycvcs "period $Lz"
where $Lz is obtained outside Colvars.
This option is currently limited to changing the values of componentCoeff (see 9.3.15) and componentExp (see 9.3.15) (e.g. to update the polynomial superposition parameters on the fly), of period (see 9.3.13) and wrapAround (see 9.3.13), and of the forceNoPBC option for all components that support it.

If the variable is computed using more than one CVC, it is possible to selectively turn some of them on or off:
cv colvar xi cvcflags $ <$ flags$ >$
where $ <$ flags$ >$ is a list of 0/1 values, one per component. This is useful for example when Tcl script-based path collective variables in Cartesian coordinates (9.3.10) are used, to minimize computational cost by disabling the computation of terms that are very close to zero.

Important: None of the changes enacted by modifycvcs or cvcflags will be saved to state files, and will be lost when restarting a simulation, deleting the corresponding collective variable, or resetting the module with cv reset.

Applying and analyzing forces on collective variables

As soon as a collective variable is up to date (during a MD run or after its update method has been called), forces can be applied to it, e.g. as part of a custom restraint implemented by scriptedColvarForces (see 9.5.12):
cv colvar xi addforce $force
where $force is a scalar or a vector (depending on the type of variable xi) and is defined by the user's function. The force will be physically applied to the corresponding atoms during the simulation after Colvars communicates all forces to the rest of NAMD. Until then, the total force applied to xi from all biases can be retrieved by:
cv colvar xi getappliedforce
(see also the use of the outputAppliedForce (see 9.3.19) option).

To obtain the total force projected on the variable xi:
cv colvar xi gettotalforce
Note that not all types of variable support this option, and the value of the total force may not be available immediately: see outputTotalForce (see 9.3.19) for more details.

See 9.6.2 for a complete list of scripting commands used to manage collective variables.

Managing collective variable biases

Because biases depend only upon data internal to the Colvars module (i.e. they do not need atomic coordinates from NAMD), it is generally easy to create them or update their configuration at any time. For example, given the most current value of the variable xi, an already-defined restraint on it named harmonic_xi can be updated as:
cv bias harmonic_xi update
Again, this is not generally needed during a running simulation, when an automat ic update of each bias is already carried out.

Calling update for a bias is most useful for just-defined biases or when changing their configuration. When update is called e.g. as part of the function invoked by scriptedColvarForces (see 9.5.12), it is executed before any biasing forces are applied to the variables, thus allowing to modify them. This use of update is often used e.g. in the definition of custom bias-exchange algorithms as part of the NAMD script. Because a bias is a relatively light-weight object, the easiest way to change the configuration of an existing bias is deleting it and re-creating it:

# Delete the restraint "harmonic_xi"
cv bias harmonic_xi delete
# Re-define it, but using an updated restraint center
cv config "harmonic {
  name harmonic_xi
  centers ${new_center}]
# Now update it (based on the current value of "xi")
cv bias harmonic_xi update
It is also possible to make the change subject to a condition on the energy of the new bias:
cv bias harmonic_xi update
if { [cv bias harmonic_xi energy] < ${E_accept} } {

Loading and saving the state of individual biases

Some types of bias are history-dependent, and the magnitude of their forces depends not only on the values of their corresponding variables, but also on previous simulation history. It is thus useful to load information from a state file that contains information specifically for one bias only, for example:
cv bias metadynamics1 load old.colvars.state
or alternatively, using the prefix of the file instead of its full name:
cv bias metadynamics1 load old
A corresponding save function is also available:
cv bias metadynamics1 save new
This pair of functions is also used internally by Colvars to implement e.g. multiple-walker metadynamics (9.5.4), but they can be called from a scripted function to implement alternative coupling schemes.

See 9.6.3 for a complete list of scripting commands used to manage biases.

Configuration syntax used by the Colvars module

All the parameters defining variables and their biasing or analysis algorithms are read from the file specified by the configuration option colvarsConfig, or by the Tcl commands cv config and cv configfile. None of the keywords described in the remainder of this manual are recognized directly in the NAMD configuration file, unless as arguments of cv config. Each configuration line follows the format ``keyword value'', where the keyword and its value are separated by any white space. The following rules apply:

Global keywords

The following keywords are available in the global context of the Colvars configuration, i.e. they are not nested inside other keywords:

To illustrate the flexibility of the Colvars module, a non-trivial setup is represented in Figure 5. The corresponding configuration is given below. The options within the colvar blocks are described in 9.3, those within the harmonic and histogram blocks in 9.5. Note: except colvar, none of the keywords shown is mandatory.

Figure 5: Graphical representation of a Colvars configuration. The colvar called ``$ d$ '' is defined as the difference between two distances: the first distance ($ d_{1}$ ) is taken between the center of mass of atoms 1 and 2 and that of atoms 3 to 5, the second ($ d_{2}$ ) between atom 7 and the center of mass of atoms 8 to 10. The difference $ d = d_{1} - d_{2}$ is obtained by multiplying the two by a coefficient $ C = +1$ or $ C = -1$ , respectively. The colvar called ``$ c$ '' is the coordination number calculated between atoms 1 to 10 and atoms 11 to 20. A harmonic restraint is applied to both $ d$ and $ c$ : to allow using the same force constant $ K$ , both $ d$ and $ c$ are scaled by their respective fluctuation widths $ w_d$ and $ w_c$ . A third colvar ``alpha'' is defined as the $ \alpha$ -helical content of residues 1 to 10. The values of ``$ c$ '' and ``alpha'' are also recorded throughout the simulation as a joint 2-dimensional histogram.

colvar {
  # difference of two distances
  name d
  width 0.2 # 0.2 Å of estimated fluctuation width
  distance {
    componentCoeff 1.0
    group1 { atomNumbers 1 2 }
    group2 { atomNumbers 3 4 5 }
  distance {
    componentCoeff -1.0
    group1 { atomNumbers 7 }
    group2 { atomNumbers 8 9 10 }

colvar {
  name c
  coordNum {
    cutoff 6.0
    group1 { atomNumbersRange 1-10 }
    group2 { atomNumbersRange 11-20 }

colvar {
  name alpha
  alpha {
    psfSegID PROT
    residueRange 1-10

harmonic {
  colvars d c
  centers 3.0 4.0
  forceConstant 5.0

histogram {
  colvars c alpha

Section 9.3 explains how to define a colvar and its behavior, regardless of its specific functional form. To define colvars that are appropriate to a specific physical system, Section 9.4 documents how to select atoms, and section 9.3 lists all of the available functional forms, which we call ``colvar components''. Finally, section 9.5 lists the available methods and algorithms to perform biased simulations and multidimensional analysis of colvars.

Input state file

Because many of the methods implemented in Colvars are history-dependent, a state file is often needed to continue a long simulation over consecutive runs. Such state file is written automatically at the end of any simulation with Colvars, and contains data accumulated during that simulation along with the step number at the end of it. The step number read from the state file is then used to control such time-dependent biases: because of this essential role, the step number internal to Colvars may not always match the step number reported by the MD program that carried during the simulation (which may instead restart from zero each time). If a state file is not given, the NAMD command firstTimestep may be used to control the Colvars step number.

Depending on the configuration, a state file may need to be loaded issued at the beginning of a new simulation when time-dependent biasing methods are applied (moving restraints, metadynamics, ABF, ...). When the Colvars module is initialized in NAMD, the colvarsInput keyword can be used to give the name of the state file. After initialization, a state file may be loaded at any time with the Tcl command cv load.

It is possible to load a state file even if the configuration has changed: for example, new variables may be defined or restraints be added in between consecutive runs. For each newly defined variable or bias, no information will be read from the state file if this is unavailable: such new objects will remain uninitialized until the first compute step. Conversely, any information that the state file has about variables or biases that are not defined any longer is silently ignored. Because these checks are done by the names of variables or biases, it is the user's responsibility to ensure that these are consistent between runs.

Output files

During a simulation with collective variables defined, the following three output files are written:

Other output files may also be written by specific methods, e.g. the ABF or metadynamics methods (9.5.2, 9.5.4). Like the trajectory file, they are needed only for analyzing, not continuing a simulation. All such files' names also begin with the prefix outputName.

Lastly, the total energy of all biases or restraints applied to the colvars appears under the NAMD standard output, under the MISC column.

next up previous contents index
Next: Defining collective variables Up: Collective Variable-based Calculations (Colvars) Previous: Writing a Colvars configuration:   Contents   Index