Configuration syntax for the Colvars module

The Colvars configuration is usually read using the commands cv configfile or 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;

• 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 ...: for example, it is possible to convert the atom selection $sel into an atom group (see 13.3.1) using cv config "atomNumbers { [$sel get serial] }";

• 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.

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

• colvarsTrajFrequency $\langle\,$ Colvar value trajectory frequency$\,\rangle$
  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.

• colvarsTrajAppend $\langle\,$ Append to trajectory file?$\,\rangle$
  Context: global
  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 with the same name that overwrites the previous file.

• colvarsRestartFrequency $\langle\,$ Colvar module restart frequency$\,\rangle$
  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 $\langle\,$ Index file for atom selection (GROMACS ``ndx'' format)$\,\rangle$
  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 13.3.

• smp $\langle\,$ Whether SMP parallelism should be used$\,\rangle$
  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 VMD.

• smp $\langle\,$ Whether SMP parallelism should be used$\,\rangle$
  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 VMD.

• analysis $\langle\,$ Turn on run-time statistical analysis$\,\rangle$
  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 13.2.5 for details.

The example below defines the same configuration shown in Fig. 13.1. The options within the colvar blocks are described in 13.2 and 13.4, the ones within the harmonic and histogram blocks in 13.5. Note: except colvar, none of the keywords shown is mandatory.

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 13.2 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 13.3 documents how to select atoms, and section 13.4 lists all of the available functional forms, which we call ``colvar components''. Finally, section 13.5 lists the available methods and algorithms to perform biased simulations and multidimensional analysis of colvars.