General parameters

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.3 and in the following sections.

NAMD parameters

To enable a Colvars-based calculation, two parameters must be added to the NAMD configuration file, colvars and colvarsConfig. An optional third parameter, colvarsInput, can be used to continue a previous simulation.

• 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; the module requires a separate configuration file, to be provided with colvarsConfig.

• colvarsConfig $<$ Configuration file for the collective variables $>$
  Context: NAMD configuration file
  Acceptable Values: UNIX filename
  Description: This file contains the definition of all collective variables and their biasing or analysis methods. This file can also be provided by the Tcl command cv configfile; alternatively, the contents of the file itself can be given as an argument to the command cv config.

• colvarsInput $<$ Input state file for the collective variables $>$
  Context: NAMD configuration file
  Acceptable Values: UNIX filename
  Description: When continuing a previous simulation run, this file contains the current state of all collective variables and of their associated algorithms. It is written automatically at the end of any simulation with collective variables. The step number contained by this file will be used internally by Colvars to control time-dependent biases, unless firstTimestep is given, in which case that value will be used. This file can also be loaded with the Tcl command cv load.

Using the cv command

At any moment during the execution of NAMD, several options in the Colvars module can be read or modified by the command cv with the following syntax:
cv $<$ subcommand$>$ [args...]
For example, to record the value of a collective variable named myVar into the Tcl variable value, use the following syntax:
set value [cv colvar myVar value]
All subcommands of cv are documented below.

Managing the Colvars module

• configfile $<$ file name$>$ : read configuration from a file;
• config $<$ string$>$ : read configuration from the given string; both config and configfile subcommands may be invoked multiple times;
• reset: delete all internal configuration and atom selections of the Colvars module;
• version: return the version of the Colvars module (see 9.6 for any changes to older keywords).

Input and output commands

• list: return a list of all currently defined variables;
• list biases: return a list of all currently defined biases (i.e. sampling and analysis algorithms);
• load $<$ file name$>$ : load a collective variables state file, typically produced during a previous simulation; the step number contained by this file will be used internally by Colvars to control time-dependent biases, unless firstTimestep is given, in which case that value will be used;
• load $<$ prefix$>$ : same as above, but without the .colvars.state suffix;
• save $<$ prefix$>$ : save the current state in a file whose name begins with the given argument; if any of the biases have additional output files defined, those are saved as well using the same prefix;
• update: recalculate all variables and biases based on the current atomic coordinates (this is typically not needed in NAMD, as these functions are called already during a timestep);
• addenergy $<$ E$>$ : add value E to the total bias energy; this can be used within calc_colvar_forces;
• printframe: return a summary of the current frame, in a format equivalent to a line of the collective variables trajectory file;
• printframelabels: return text labels for the columns of printframe's output;

Managing collective variables

• colvar $<$ name$>$ value: return the current value of colvar $<$ name$>$ ;
• colvar $<$ name$>$ update: recalculate colvar $<$ name$>$ ;
• colvar $<$ name$>$ type: return the type of colvar $<$ name$>$ ;
• colvar $<$ name$>$ addforce $<$ F$>$ : apply given force on colvar $<$ name$>$ ; this can be used within calc_colvar_forces
• colvar $<$ name$>$ getappliedforce: get the force currently being applied on colvar $<$ name$>$ ;
• colvar $<$ name$>$ gettotalforce: get the total force acting on colvar $<$ name$>$ at the previous step (see 9.3.4);
• colvar $<$ name$>$ getconfig: return config string of colvar $<$ name$>$ .
• colvar $<$ name$>$ cvcflags $<$ flags$>$ : for a colvar with several CVCs (numbered according to their name string order), set which CVCs are enabled or disabled in subsequent evaluations according to a list of 0/1 flags (one per CVC).
• colvar $<$ name$>$ modifycvcs $<$ strings$>$ : for a colvar with one or more CVCs (numbered according to their name string order), pass a list of new configuration strings to modify each CVC without needing to delete the colvar. This option is currently limited to changing the values of componentCoeff (see 9.3.5) and componentExp (see 9.3.5) (e.g. to update the polynomial superposition parameters on the fly), of period (see 9.3.3) and wrapAround (see 9.3.3) (e.g. to update the period of variables such as distanceZ), and of the forceNoPBC option for those CVCs that support it. Changes in configuration done by this command are not saved to state files, and are lost when restarting a simulation, deleting the parent colvar, or resetting the module with cv reset.

Managing biases

• bias $<$ name$>$ energy: return the current energy of the bias $<$ name$>$ ;
• bias $<$ name$>$ update: recalculate the bias $<$ name$>$ ;
• bias $<$ name$>$ delete: delete the bias $<$ name$>$ ;
• bias $<$ name$>$ getconfig: return config string of bias $<$ name$>$ .

Configuration syntax

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. The syntax of the Colvars configuration is ``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;

• 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: restartFreq
  Description: Allows to choose a different restart frequency for the Colvars module. Redefining it may be useful to trace the time evolution of those few properties which are not written to the trajectory file for reasons of disk space.

• 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: the same group name cannot appear in multiple index files. 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.

• analysis $<$ Turn on run-time statistical analysis $>$
  Context: global
  Acceptable Values: boolean
  Default Value: off
  Description: If this flag is enabled, each colvar is instructed to perform whatever run-time statistical analysis it is configured to, such as correlation functions, or running averages and standard deviations. See section 9.3.12 for details.

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.

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.2).
  This is the only Colvars output file needed to continue a simulation.

• If the parameter colvarsRestartFrequency (see 9.2.4) 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.4) 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.1, 9.5.3). 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.