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:

• units $<$ Unit system to be used $>$
  Context: global
  Acceptable Values: string
  Description: A string defining the units to be used internally by Colvars. In NAMD the only allowed value is NAMD's native units: real (Å, kcal/mol).

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.

• colvars $<$ Enable the Colvars module $>$
  Context: NAMD configuration file
  Acceptable Values: boolean
  Default Value: off
  Description: If this flag is on, the Colvars module within NAMD is enabled.

• colvarsConfig $<$ Configuration file for the collective variables $>$
  Context: NAMD configuration file
  Acceptable Values: UNIX filename
  Description: Name of the Colvars configuration file (9.2.4, 9.2.5 and following sections). This file can also be provided by the Tcl command cv configfile. Alternatively, the contents of the file (as opposed to the file itself) can be given as a string argument to the command cv config.

• colvarsInput $<$ Input state file for the collective variables $>$
  Context: NAMD configuration file
  Acceptable Values: UNIX filename
  Description: Keyword used to specify the input state file's name (9.2.6). If the input file is meant to be loaded within a Tcl script section, the cv load command may be used instead.

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 colvars-file.in
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 colvars-definition.in
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:

• keywords are case-insensitive (upperBoundary is the same as upperboundary and UPPERBOUNDARY): their string values are however case-sensitive (e.g. file names);

• a long value, or a list of multiple values, can be distributed across multiple lines by using curly braces, ``{'' and ``}'': the opening brace ``{'' must occur on the same line as the keyword, following a space character or other white space; the closing brace ``}'' can be at any position after that; any keywords following the closing brace on the same line are not valid (they should appear instead on a different line);

• many keywords are nested, and are only meaningful within a specific context: for every keyword documented in the following, the ``parent'' keyword that defines such context is also indicated in parentheses;

• the `=' sign between a keyword and its value, deprecated in the NAMD main configuration file, is not allowed;

• Tcl syntax is generally not available, but it is possible to use Tcl variables or bracket expansion of commands within a configuration string, when this is passed via the command cv config ...; this is particularly useful when combined with parameter introspection (see 2.2.2), e.g. cv config "colvarsTrajFrequency [DCDFreq]";

• if a keyword requiring a boolean value (yes|on|true or no|off|false) is provided without an explicit value, it defaults to `yes|on|true'; for example, `outputAppliedForce' may be used as shorthand for `outputAppliedForce on';

• the hash character # indicates a comment: all text in the same line following this character will be ignored.

Global keywords

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

• colvarsTrajFrequency $<$ Colvar value trajectory frequency $>$
  Context: global
  Acceptable Values: positive integer
  Default Value: 100
  Description: The values of each colvar (and of other related quantities, if requested) are written to the file outputName.colvars.traj every these many steps throughout the simulation. If the value is 0, such trajectory file is not written. For optimization the output is buffered, and synchronized with the disk only when the restart file is being written.

• colvarsRestartFrequency $<$ Colvar module restart frequency $>$
  Context: global
  Acceptable Values: positive integer
  Default Value: NAMD parameter restartFreq
  Description: The state file and any other output files produced by Colvars are written every these many steps (the trajectory file is still written every colvarsTrajFrequency (see 9.2.5) steps). It is generally a good idea to leave this parameter at its default value, unless needed for special cases or to disable automatic writing of output files altogether. Writing can still be invoked at any time via the command cv save.

• indexFile $<$ Index file for atom selection (GROMACS ``ndx'' format) $>$
  Context: global
  Acceptable Values: UNIX filename
  Description: This option reads an index file (usually with a .ndx extension) as produced by the make_ndx tool of GROMACS. This keyword may be repeated to load multiple index files. A group with the same name may appear multiple times, as long as it contains the same indices in identical order each time: an error is raised otherwise. The names of index groups contained in this file can then be used to define atom groups with the indexGroup keyword. Other supported methods to select atoms are described in 9.4.

• smp $<$ Whether SMP parallelism should be used $>$
  Context: global
  Acceptable Values: boolean
  Default Value: on
  Description: If this flag is enabled (default), SMP parallelism over threads will be used to compute variables and biases, provided that this is supported by the NAMD build in use.

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:

• A state file, named outputName.colvars.state; this file is in ASCII (plain text) format, regardless of the value of binaryOutput in the NAMD configuration. This file is written at the end of the specified run, but can also be written at any time with the command cv save (9.2.3).
  This is the only Colvars output file needed to continue a simulation.

• If the parameter colvarsRestartFrequency (see 9.2.5) is larger than zero, a restart file is written every that many steps: this file is fully equivalent to the final state file. The name of this file is restartName.colvars.state.

• If the parameter colvarsTrajFrequency (see 9.2.5) is greater than 0 (default: 100), a trajectory file is written during the simulation: its name is outputName.colvars.traj; unlike the state file, it is not needed to restart a simulation, but can be used later for post-processing and analysis.

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.