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 cv command is used by the Dashboard graphical interface,(), but can be also used in scripts or interactively from the command-line terminal (for example, in remote terminal sessions) or in the Tk Console. The most frequent uses of the cv command are discussed here. For a complete list of all sub-commands of cv, see section .

Setting up the Colvars module

The first step to using Colvars in VMD is choosing which ``molecule'' (i.e. which system): because VMD can handle multiple ``molecules'', the Colvars module needs to remain attached to a specific VMD molecule. For example:
cv molid top
will attach the Colvars module onto the molecule currently holding the ``top'' status (alternatively, you can refer to a molecule by its numeric ID in lieu of top). All following invocations of the cv command will continue operating on the same molecule, regardless of whether other molecules are loaded, or which one has the ``top'' status. The cv molid command without argument will return the molid currently associated with Colvars.

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.

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$>$

cv save, analogous to cv load, saves all restart information to a state file. This is normally not required during a simulation if colvarsRestartFrequency is defined (either directly or indirectly by the VMD 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 for a complete list of scripting commands used to manage the Colvars module.

Analyzing a trajectory in VMD

One of the typical uses of Colvars in VMD is computing the values of one or more variables along an existing trajectory. A complete example input for this use case is shown here.

# Activate the module on the current VMD molecule
cv molid top
# Load a Colvars config file
cv configfile test.in
set out [open "test.colvars.traj" "w"]
# Write the labels to the file
puts -nonewline ${out} [cv printframelabels]
for { set fr 0 } { ${fr} < [molinfo top get numframes] } { incr fr } {
  # Point Colvars to this trajectory frame
  cv frame ${fr}
  # Recompute variables and biases (required in VMD)
  cv update
  # Print variables and biases to the file
  puts -nonewline ${out} [cv printframe]
}
close ${out}

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 (). 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 may be obtained for example as:
set Lz [molinfo top get c].
This option is currently limited to changing the values of componentCoeff and componentExp (e.g. to update the polynomial superposition parameters on the fly), of period and wrapAround, 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 () 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 delete or 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:
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 VMD. (In VMD, these forces will never have an effect.) 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 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 for more details.

See 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 VMD), 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, 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 VMD 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 (), but they can be called from a scripted function to implement alternative coupling schemes.

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