General parameters and input/output files

The structure of a typical colvars configuration is represented in Figure 6. Each colvar is a combination of one or more components (see 9.2), which are functions of several atomic coordinates. Many different biasing or analysis methods can be applied to the same colvars. But care should be taken that certain methods (such as free energy reconstruction) do not produce correct results when other biases are adding forces to their colvars.

Figure 6: Example of a collective variables (colvar) configuration. The colvar ``$d$'' is defined as the difference between two distances, each calculated between the centers of mass of two atom groups. The second colvar ``$c$'' holds the coordination number (i.e. the number of contacts) within a radius of 6 Å between two groups. The third colvar ``alpha'' measures the degree of $\alpha$-helicity of the protein segment between residues 1 and 10. A moving harmonic restraint is applied to the colvars ``$d$'' and ``$c$'', each rescaled by means of width parameters $w_{d}$ and $w_{c}$; the centers of the restraint, $d_0$ and $c_0$, evolve with the simulation time $t$. The joint histogram of ``alpha'' and ``$c$'' is also recorded on-the-fly.

NAMD parameters

To enable a colvar calculation, two parameters should be added to the NAMD configuration file must set (three when restarting a previous run):

• colvars $<$ Enable the collective variables module $>$
  Acceptable Values: boolean
  Default Value: off
  Description: If this flag is on, the collective variables module within NAMD is executed at each time step; the module requires a separate configuration file, to be provided with colvarsConfig.

• colvarsConfig $<$ Configuration file for the collective variables $>$
  Acceptable Values: UNIX filename
  Description: This file contains the definition of all collective variables and their biasing or analysis methods. It is meant to contain all the information needed to begin a colvars simulation. Additional information is needed instead to continue a previous run, which is read from the file provided by colvarsInput.

• colvarsInput $<$ Input state file for the collective variables $>$
  Acceptable Values: UNIX filename
  Description: When continuing a previous simulation run, this file contains the current state of all collective variables and their biasing methods. Its format is similar to that of colvarsConfig, but with different keywords. In normal circumstances, this file is written automatically at the end of a NAMD run, and the user does not need to edit it.

Output files

By default, the collective variables module writes three output files:

• a state file, named $<$outputName$>$.colvars.state; this file is in ASCII format, regardless of the value of binaryOutput in the NAMD configuration; the name of this file can be provided as colvarsInput to continue the simulation in the next run;

• a restart file (equivalent to the state file) is written every colvarsRestartFrequency steps, if either colvarsRestartFrequency or the NAMD parameter restartFreq is defined; its name is $<$restartName$>$.colvars.state, and can be given as colvarsInput to continue an interrupted run; (provided that the coordinates and velocities restart files at the same time step are also used);

• a trajectory file is written during the simulation, if the colvars module parameter colvarsTrajFrequency is greater than 0 (default: 100); its name is $<$outputName$>$.colvars.traj; unlike the state file it is not needed to restart a simulation, but can be read in for post-processing (see 9.2.4).

Other output files may be written by specific methods applied to the colvars (e.g. by the ABF method, see 9.3.1, or the metadynamics method, see 9.3.2). Like the colvar trajectory file, they are needed only for analyzing, not continuing a simulation. All such files' names also begin with the prefix $<$outputName$>$.

Colvars module configuration file

Except for the three NAMD keywords listed above (colvars, colvarsConfig and colvarsInput), all the parameters defining the colvars and their biases are read from the extra input file (provided by colvarsConfig). Hence, none of the keywords described in this and the following sections are available in the NAMD main configuration.

The syntax of the collective variables configuration file is similar to that of the NAMD file (2.2.1), with a few important differences:

• certain keywords may have multiple values;
• a long value (or values) can be distributed across several lines, by using curly braces ({ and }): the opening brace ({) must occur on the same line as the keyword, after a space character or any other white space;
• blocks defined by curly braces may be nested: therefore, the values of a keyword (such as colvar) may in turn contain simple keywords (such as name) and keywords with other blocks (such as distance);
• nested keywords are only meaningful within the parent keyword's block, and not elsewhere: when the same keyword is available within different blocks, it may have different meanings; for every keyword documented in the following, the ``parent'' keyword defining the context block is indicated in parentheses;
• certain keywords can be used multiple times even within the same context (e.g. the keyword colvar);
• as in the NAMD configuration, comments can be inserted at any point using the hash sign, #;
• unlike in the NAMD config, the deprecated `=' sign between a keyword and its value, is not allowed;
• Tcl commands and variables are not available;
• 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'.

Three global options are available:

• colvarsTrajFrequency $<$ (global) Colvar value trajectory frequency $>$
  Acceptable Values: positive integer
  Default Value: 100
  Description: The values of each colvar (and any additional quantities which have been set to be reported) are written at this frequency to the file <outputName>.colvars.traj. If the value is 0, the trajectory file is not written. For optimization, the output is buffered (as is the NAMD log output in most operating systems), but it is synchronized with the disks every time the restart file is written.

• colvarsTrajAppend $<$ (global) Append to trajectory file? $>$
  Acceptable Values: boolean
  Default Value: off
  Description: If this flag is enabled, and a file with the same name as the trajectory file is already present, new data is appended to that file. Otherwise, a new file is created. Note: if you're running consecutive simulations with the same outputName (e.g. in FEP calculations), you should enable this option to preserve the previous contents of the trajectory file.

• colvarsRestartFrequency $<$ (global) Colvar module restart frequency $>$
  Acceptable Values: positive integer
  Default Value: restartFreq
  Description: Allows to choose a different restart frequency for the collective variables 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.

• analysis $<$ (global) Turn on analysis calculations $>$
  Acceptable Values: boolean
  Default Value: off
  Description: If this flag is enabled, the analysis mode is turned on, and all the colvars and their biasing methods are instructed to perform whatever analysis they are configured to.

The following is a typical configuration file. The options available inside the two colvar blocks are documented in 9.2. harmonic defines an harmonic potential, which is one of the available biases, documented in 9.3. Note: except colvar, none of the keywords below is mandatory.

# collective variables config file: two distances

colvarsTrajFrequency 100 # output values every 100 steps

colvar {
  name 1st-colvar # needed to identify the variable

  outputSystemForce yes # report also the system force on this colvar
                        # (in addition to the current value)
  distance {
    group1 {
      atomNumbers 1 2 3 
    }
    group2 {
      atomNumbers 4 5 6 
    }
  }
}

colvar {
  name 2nd-colvar
  ...
}

harmonic {
  name my_pot
  colvars 1st-colvar 2nd-colvar
  centers 3.0 4.0
  forceConstant 5.0
}

In the following, the section 9.2 explains how to define a colvar. 9.2.1 lists the available colvar components; 9.2.2 defines how to combine existing components to create new types of colvars; 9.2.3 documents how to define in a compact way atom groups, which are used by most components; 9.2.4 lists the available option for runtime analysis of the colvars.

9.3 lists the available methods to perform biased simulations and multidimensional analysis (ABF, harmonic restraint, histogram, and metadynamics).