NAMD configuration file

Besides these input and output files, NAMD also uses a file referred to as the configuration file. This file specifies what dynamics options and values that NAMD should use, such as the number of timesteps to perform, initial temperature, etc. The options and values in this file control how the system will be simulated. The NAMD configuration file is specified on the NAMD command line, either before or after the various parallel execution options described in section 17.

A NAMD configuration file contains a set of options and values. The options and values specified determine the exact behavior of NAMD, what features are active or inactive, how long the simulation should continue, etc. Section 2.2.1 describes how options are specified within a NAMD configuration file. Section 2.2.3 lists the parameters which are required to run a basic simulation. Section 15 describes the relation between specific NAMD and X-PLOR dynamics options. Several sample NAMD configuration files are shown in section 16.

During execution NAMD will change to the directory containing the configuration file so that all file paths in the configuration file are relative to the configuration file directory. Multiple configuration files may be specified on the command line and the will be read in order, but all file paths will be relative to the first configuration file to call a ``run'' command, or to the last configuration file if ``run'' is not called.

Commands or parameters may also be specified directly on the command line via --keyword value argument pairs, for example --outputenergies 100 --run 100 -- checkpoint. This may be used to include multiple configuration files without altering the working directory via --source /path/to/second.conf. Note that escaping or quoting of command line parameter values containing spaces may be difficult or impossible on some systems due to multiple levels of scripts called during the NAMD parallel launch process and because the keyword and value are simply merged into a single string that is passed to the Tcl interpreter.

Configuration parameter syntax

Each line in the configuration files consists of a $keyword$ identifying the option being specified, and a $value$ which is a parameter to be used for this option. The keyword and value can be separated by only white space:

keyword            value

or the keyword and value can be separated by an equal sign and white space:

keyword      =     value

Blank lines in the configuration file are ignored. Comments are prefaced by a # and may appear on the end of a line with actual values:

keyword            value          #  This is a comment

or may be at the beginning of a line:

#  This entire line is a comment . . .

Some keywords require several lines of data. These are generally implemented to either allow the data to be read from a file:

keyword            filename

or to be included inline using Tcl-style braces:

keyword {
  lots of data
}

The specification of the keywords is case insensitive so that any combination of upper and lower case letters will have the same meaning. Hence, DCDfile and dcdfile are equivalent. The capitalization in the values, however, may be important. Some values indicate file names, in which capitalization is critical. Other values such as on or off are case insensitive.

Tcl scripting interface and features

When compiled with Tcl (all released binaries) the config file is parsed by Tcl in a fully backwards compatible manner with the added bonus that any Tcl command may also be used. This alone allows:

• the ``source'' command to include other files (works w/o Tcl too!),
• the ``print'' command to display messages (``puts'' to stdout fails on some platforms),
• environment variables through the env array (``$env(USER)''), and
• user-defined variables (``set base sim23'', ``dcdfile $base.dcd'').

Additional features include:

• The ``callback'' command takes a 2-parameter Tcl procedure which is then called with a list of labels and a list of values during every timestep, allowing analysis, formatting, whatever.
• The ``run'' command takes a number of steps to run (overriding the now optional numsteps parameter, which defaults to 0) and can be called repeatedly. You can ``run 0'' just to get energies. Normally the preceeding timestep is repeated to account for any modifications to the energy function; this can be avoided with ``run norepeat''.
• The ``minimize'' command is similar to ``run'' and performs minimization for the specified number of force evaluations.
• Configuration file parameter introspection is supported by invoking a (case-insensitive) parameter keyword with no argument (e.g., ``numsteps'') and by the helper commands ``isset'' and ``istrue''. Note that keywords are not parsed until the first ``run'' command, and before this values are treated as unformatted strings, so for example ``eFieldOn'' and ``eField'' may return ``yes'' and ``1 2 3'' before the first ``run'' command, but ``1'' and ``1.0 2.0 3.0'' after parsing (``istrue eFieldOn'' would return ``1'' in both cases). Similarly, ``isset badparam'' will return ``0'' before parsing but raise an ``unknown parameter'' error after.
• Between ``run'' commands the reassignTemp, rescaleTemp, and langevinTemp parameters can be changed to allow simulated annealing protocols within a single config file. The useGroupPressure, useFlexibleCell, useConstantArea, useConstantRatio, LangevinPiston, LangevinPistonTarget, LangevinPistonPeriod, LangevinPistonDecay, LangevinPistonTemp, SurfaceTensionTarget, BerendsenPressure, BerendsenPressureTarget, BerendsenPressureCompressibility, and BerendsenPressureRelaxationTime parameters may be changed to allow pressure equilibration. The fixedAtoms, constraintScaling, and nonbondedScaling parameters may be changed to preserve macromolecular conformation during minimization and equilibration (fixedAtoms may only be disabled, and requires that fixedAtomsForces is enabled to do this). The consForceScaling parameter may be changed to vary steering forces or to implement a time-varying electric field that affects specific atoms. The eField, eFieldFreq, and eFieldPhase parameters may be changed to implement at time-varying electric field that affects all atoms. The alchLambda and alchLambda2 parameters may be changed during alchemical free energy runs. The DCDfile may be changed to write binary coordinate trajectory output to separate files. The restartname may be changed to write restart output to separate files.
• The ``checkpoint'' and ``revert'' commands (no arguments) allow a scripted simulation to save and restore (in memory) to a single prior state. The ``output'' and ``reinitatoms'' commands support multiple saved states using files.
• The ``output'' command takes an output file basename and causes .coor, .vel, and .xsc files to be written with that name. Alternatively, ``output withforces'' and ``output onlyforces'' will write a .force file either in addition to or instead of the regular files.
• The ``reinitatoms'' command reinitializes coordinates, velocities, and periodic cell dimensions to those initially read in (random velocities are generated if they were not read from a file). An optional file basename argument (matching that passed to the output command) causes .coor, .vel, and .xsc files to be read, assuming the format indicated by the binaryoutput parameter.
• The ``exit'' command writes output files and exits cleanly.
• The ``abort'' command concatenates its arguments into an error message and exits immediately without writing output files.
• The ``numPes'', ``numNodes'', and ``numPhysicalNodes'' commands allow performance-tuning parameters to be set based on the parallel execution environment.
• The ``reinitvels'' command reinitializes velocities to a random distribution based on the given temperature.
• The ``rescalevels'' command rescales velocities by the given factor.
• The ``reloadCharges'' command reads new atomic charges from the given file, which should contain one number for each atom, separated by spaces and/or line breaks.
• The ``consForceConfig'' command takes a list of 0-based atom indices and a list of forces which replace the existing set of constant forces (constantForce must be on).
• The ``measure'' command allows user-programmed calculations to be executed in order to facilitate automated methods. (For example, to revert or change a parameter.) A number of measure commands are included in the NAMD binary; the module has been designed to make it easy for users to add additional measure commands.
• The ``coorfile'' command allows NAMD to perform force and energy analysis on trajectory files. ``coorfile open dcd filename'' opens the specified DCD file for reading. ``coorfile read'' reads the next frame in the opened DCD file, replacing NAMD's atom coordinates with the coordinates in the frame, and returns 0 if successful or -1 if end-of-file was reached. ``coorfile skip'' skips past one frame in the DCD file; this is significantly faster than reading coordinates and throwing them away. ``coorfile close'' closes the file. The ``coorfile'' command is not available on the Cray T3E.

  Force and energy analysis are especially useful in the context of pair interaction calculations; see Sec. 14.1 for details, as well as the example scripts in Sec. 16.

Please note that while NAMD has traditionally allowed comments to be started by a # appearing anywhere on a line, Tcl only allows comments to appear where a new statement could begin. With Tcl config file parsing enabled (all shipped binaries) both NAMD and Tcl comments are allowed before the first ``run'' command. At this point only pure Tcl syntax is allowed. In addition, the ``;#'' idiom for Tcl comments will only work with Tcl enabled. NAMD has also traditionally allowed parameters to be specified as ``param=value''. This is supported, but only before the first ``run'' command. Some examples:

# this is my config file                            <- OK
reassignFreq 100 ; # how often to reset velocities  <- only w/ Tcl
reassignTemp 20 # temp to reset velocities to       <- OK before "run"
run 1000                                            <- now Tcl only
reassignTemp 40 ; # temp to reset velocities to     <- ";" is required

NAMD has also traditionally allowed parameters to be specified as ``param=value'' as well as ``param value''. This is supported, but only before the first ``run'' command. For an easy life, use ``param value''.

Required NAMD configuration parameters

The following parameters are required for every NAMD simulation:

• numsteps (page ),

• coordinates (page ),

• structure (page ),

• parameters (page ),

• exclude (page ),

• outputname (page ),

• one of the following three:
  • temperature (page ),

  • velocities (page ),

  • binvelocities (page ).

These required parameters specify the most basic properties of the simulation. In addition, it is highly recommended that pairlistdist be specified with a value at least one greater than cutoff.