General parameters and input/output files

To enable a collective variable calculation, one or more parameters are added to the NAMD configuration file. In 10.1.1, we document the syntax of such parameters. One of these is the name of a configuration file for the collective variables module itself, which is described in 10.1.2, and in the following sections.

NAMD parameters

To enable a collective variables-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 $<$ (NAMD configuration file context) Enable the collective variables module $>$
  Acceptable Values: boolean
  Default Value: off
  Description: If this flag is on, the collective variables module within NAMD is enabled; the module requires a separate configuration file, to be provided with colvarsConfig.

• colvarsConfig $<$ (NAMD configuration file context) 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. Parameters within the configuration file can be controlled from a NAMD config file using Tcl variables in the following way:

  colvars on
  colvarsConfig colvars_subst.tmp
  set myParameter someValue
  # Parse template and create specific config file on the fly
  set infile [open colvars_template.in r]
  set outfile [open colvars_subst.tmp w+]
  puts $outfile [subst [read $infile]]
  close $infile
  close $outfile

  In this example, the string $myParameter will be replaced with the value someValue wherever it appears in the file colvars_template.in. This value will then be read in by the colvars module when it parses its input.

• colvarsInput $<$ (NAMD configuration file context) 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 of their associated algorithms. It is written automatically at the end of any simulation with collective variables.

Configuration file for the collective variables module

All the parameters defining the colvars and their biasing or analysis algorithms are read from the file specified by colvarsConfig. 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 file 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;

• unlike in the NAMD main configuration file, the deprecated `=' sign between a keyword and its value is not allowed;

• unlike in the NAMD main configuration file, Tcl commands and variables are not available, but it is possible to use Tcl to generate a new configuration file with different parameters (see 10.1.1);

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

All parameters defining the colvars and their biasing or analysis algorithms are read from the file specified by colvarsConfig. The following keywords are available in the global context of this configuration file, i.e. not nested inside other keywords:

• colvarsTrajFrequency $<$ (global context) Colvar value trajectory frequency $>$
  Acceptable Values: positive integer
  Default Value: 100
  Description: Thevalues 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 $<$ (global context) 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 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 $<$ (global context) 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.

• indexFile $<$ (global context) Index file for atom selection (GROMACS ``ndx'' format) $>$
  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. 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.

• analysis $<$ (global context) Turn on run-time statistical analysis $>$
  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 configuration file, an optional input state file may be provided to continue a previous simulation. The name of this file is provided as a value to the keyword colvarsInput.

Output files

In addition to the output files written by NAMD, 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.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.

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