General parameters and input/output files

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

<17873>>

Using the cv command

The Colvars module is accessed in VMD through the command cv. The command must be used the first time as cv molid $<$ molid$>$ to set up the Colvars module for a given molecule. In all following uses, the cv command will continue operating on the same molecule, regardless of its ``top'' status. To use the cv command on a different molecule, use cv delete first and then cv molid $<$ molid$>$ . Invoking the cv command with no arguments prints a help screen.

<17874>>Collective variables and biases can be added, queried and deleted through the scripting command cv, with the following syntax: cv $<$ subcommand$>$ [args...]. For example, to query the value of a collective variable named myVar, use the following syntax: set value [cv colvar myVar value]. All subcommands of cv are documented below.

1]

#1

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 of the colvars module;
• version: return the version of the colvars code.

Input and output

• 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;
• 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 colvars and biases based on the current atomic coordinates;
• 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;

Accessing 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$>$ delete: delete colvar $<$ name$>$ ;
• colvar $<$ name$>$ addforce $<$ F$>$ : apply given force on colvar $<$ name$>$ ;
• 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 10.4.3);
• 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).

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

<18125>>Collective variables and biases can be added, queried and deleted through the scripting command cv, with the following syntax: cv $<$ subcommand$>$ [args...]. For example, to query the value of a collective variable named myVar, use the following syntax: set value [cv colvar myVar value]. All subcommands of cv are documented below.

1]

#1

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 of the colvars module;
• version: return the version of the colvars code.

Input and output

• 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 simulation;
• 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;
• update: recalculate all colvars and biases based on the current atomic coordinates;
• 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;

Accessing 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$>$ delete: delete colvar $<$ name$>$ ;
• colvar $<$ name$>$ addforce $<$ F$>$ : apply given force on colvar $<$ name$>$ ;
• 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).

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

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. This file can also be provided by the Tcl command cv load.

Configuration syntax for the Colvars module

All the parameters defining the colvars 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. Hence, none of the keywords described in this section and the following ones are available as keywords for the NAMD configuration file. 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.

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.

• colvarsTrajAppend $<$ Append to trajectory file? $>$
  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. Note: when 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 $<$ 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 10.3.

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

• 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 10.2.5 for details.

The example below defines the same configuration shown in Fig. 6. The options within the colvar blocks are described in 10.2 and 10.4, the ones within the harmonic and histogram blocks in 10.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 10.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 10.3 documents how to select atoms, and section 10.4 lists all of the available functional forms, which we call ``colvar components''. Finally, section 10.5 lists the available methods and algorithms to perform biased simulations and multidimensional analysis of colvars.

Input state file (optional)

Aside from the colvars configuration, an optional input state file may be provided to load the relevant data from a previous simulation. The name of this file is provided as a value to the keyword colvarsInput.

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 format , regardless of the value of binaryOutput in the NAMD configuration; to continue the simulation, the name of this file must be included in the configuration of the next run using colvarsInput, together with the other NAMD output files;

• if the NAMD parameter restartFreq or the parameter colvarsRestartFrequency is larger than zero, a restart file named restartName.colvars.state is written every that many steps: this file is equivalent to the final state file;

• if the parameter colvarsTrajFrequency 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 be written by specific methods applied to the colvars (e.g. by the ABF method, see 10.5.1, or the metadynamics method, see 10.5.3). 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.

Finally, the total energy of all biases or restraints applied to the colvars appears under the NAMD standard output, under the MISC column.