next up previous
Next: NAMD Standard Output Up: NAMD Tutorial Previous: Parameter Files

NAMD Configuration Files

The NAMD configuration file (also called a config file, .conf file, or .namd file) is given to NAMD on the command line and specifies virtually everything about the simulation to be done. The only exceptions are details relating to the parallel execution environment, which vary between platforms. Therefore, the config file should be portable between machines, platforms, or numbers of processors in a run, as long as the referenced input files are available.

As a convenience, on startup NAMD will switch to the directory that contains the config file, so that all file paths are relative to that directory. NAMD also accepts multiple config files on the command line, but changes directories before parsing each file, so it is best to keep everything in the same directory when using multiple config files.

NAMD parses its configuration file using the Tcl scripting language, which you should be familiar with if you have done any serious work using VMD. However, to remain compatible with config files from earlier version of NAMD which did not include Tcl, several compromises have been made. Tcl is a case sensitive language, so the $temp and $TEMP are different variables. NAMD's config file options are implemented as case-insensitive Tcl commands, however, so temperature 300, Temperature 300, or even tEmPerATURe 300 will all have the same effect.

NAMD config files were historically order-independent, and the whole file was parsed before any files were read or calculations done. Now that NAMD incorporates more advanced scripting, the config file is parsed up to the point where one of the case-sensitive ``action'' commands such as minimize or run are encountered; at this point the input files are read and real calculation begins. Beyond this point, the config file is order-dependent and only these action commands and a subset of configuration options may be given. Also, at this point any comments must follow the rules of Tcl, using a semicolon to end a command before using # to start a comment on the same line; it is good practice to follow these rules everywhere in the file.

We will now walk through a NAMD configuration file template that contains options for common simulation methods in NAMD. A version of this file should be available in the tutorial materials as sample.conf.

First we specify the files that contain the molecular structure and initial conditions. A coordinates PDB file is always required, even if the actual coordinates will come from a binary coordinates file.

structure          mypsf.psf
coordinates        mypdb.pdb

Setting the Tcl variable $temperature makes it easy to change the target temperature for many options.

set temperature    310  ;# target temperature used several times below

If we are starting from scratch, we'll use the coordinates from the PDB file and take velocities randomly from a Boltzmann distribution, using the $temperature variable.

# starting from scratch
temperature         $temperature    ;# initialize velocities randomly

Otherwise we'll read in the binary output files of the previous run. We use the Tcl variable $inputname to avoid errors in typing the input file names, since we will end up copying and modifying this file several times during the course of a long simulation. The extendedSystem file holds the periodic cell dimensions that are needed to continue after a constant pressure simulation. In order to start numbering timesteps with the final step of the previous run, we use firsttimestep to specify the timestep on which the input coordinates and velocities were written. The number of steps calculated in this run will be numsteps - firsttimestep.

# continuing a run
set inputname      myinput          ;# only need to edit this in one place!
binCoordinates     $inputname.coor  ;# coordinates from last run (binary)
binVelocities      $inputname.vel   ;# velocities from last run (binary)
extendedSystem	   $inputname.xsc   ;# cell dimensions from last run
firsttimestep      50000            ;# last step of previous run
numsteps           100000           ;# run stops when this step is reached

The outputName prefix will be used to create all of the trajectory (.dcd, .xst), output (.coor, vel, .xsc), and restart (.restart.coor, .restart.vel, .restart.xsc) files generated by this run. Be careful that this is different from $myinput, or the job will overwrite its input files!

outputName         myoutput   ;# base name for output from this run

We will write restart files, coordinate trajectory .dcd files, and extended system (periodic cell) trajectory .xst files at regular intervals.

restartfreq         500     ;# 500 steps = every 1ps
dcdfreq             500
xstFreq             500

The default is to print energies every steps, but that makes for a very long file, so we'll cut it down to every 100 steps. We'll also enable the printing of performance information every 1000 steps.

outputEnergies      100     ;# 100 steps = every 0.2 ps
outputTiming       1000     ;# shows time per step and time to completion

Next are the parameter file itself and the options that control the nonbonded potential functions. These are mostly specified by the CHARMM force field, but the cutoff and other distances may be shortened when full electrostatics are used; Just be sure that you adjust all of the distances together. The pairlistdist can be made longer if you see warnings in the NAMD output, but making it bigger than necessary will reduce performance.

# Force-Field Parameters
paraTypeCharmm	    on
parameters          par_all27_prot_lipid.inp 

# These are specified by CHARMM
exclude             scaled1-4
1-4scaling          1.0
switching           on

# You have some freedom choosing the cutoff
cutoff              12. ;# may use smaller, maybe 10., with PME
switchdist          10. ;# cutoff - 2.

# Promise that atom won't move more than 2A in a cycle
pairlistdist        14. ;# cutoff + 2.

The chosen stepspercycle is related to pairlistdist above, as pairlists are generated at the beginning of each cycle and are assumed to contain every atom that passes within the cutoff distance during entire cycle. Warnings will appear in the output if pairlistdist is too short (or stepspercycle is too large). The length of the simulation must be an integer number of cycles.

stepspercycle       10   ;# redo pairlists every ten steps

The integration timestep is normally limited to 1fs. This can be extended to 2fs by fixing the length of all bonds in the molecule involving hydrogen atoms via rigidBonds all, which also makes water molecules completely rigid. To only make water rigid, use rigidBonds water and a 1fs timestep. For any simulations involving water molecules, one should make water rigid since water molecules have been parametrized as rigid water. Nonbonded forces must be calculated at least every 2fs, which in this example is every step. Full electrostatics forces (from particle mesh Ewald, discussed below) are evaluated every other step in this example. nonbondedFreq and fullElectFrequency must evenly divide stepspercycle.

# Integrator Parameters
timestep            2.0  ;# 2fs/step
rigidBonds          all  ;# needed for 2fs steps
nonbondedFreq       1    ;# nonbonded forces every step
fullElectFrequency  2    ;# PME only every other step

Langevin dynamics balances friction with random noise to drive each atom in the system towards a target temperature. The following parameters are good for equilibration, but a langevinDamping as low as 1. would be sufficient for simulation. Higher damping may be necessary if, for example, work done on the system by steering forces is driving up the temperature.

# Constant Temperature Control
langevin            on            ;# langevin dynamics
langevinDamping     1.            ;# damping coefficient of 1/ps
langevinTemp        $temperature  ;# random noise at this level
langevinHydrogen    no            ;# don't couple bath to hydrogens

If the simulation will use periodic boundary conditions, they are specified as shown below. Like the temperature option, these should only be given when starting a simulation from scratch, since the basis vectors will fluctuate during constant pressure simulation and updated values need to be read via extendedSystem from a .xsc file.

# Periodic Boundary conditions
cellBasisVector1    31.2   0.   0.  ;# vector to the next image
cellBasisVector2     0.   44.8  0.
cellBasisVector3     0.    0   51.3
cellOrigin           0.    0.   0.  ;# the *center* of the cell

The cell origin is the one coordinate that does not change during constant pressure simulation. This point plays a role in calculating the pressure contribution due to fixed atoms, harmonic restraints, and other ``external'' forces. To minimize pressure fluctuations, this point should be close to the center of the macromolecule of interest.

The origin also defines the center of the periodic cell to which coordinates will be wrapped on output if the following options below are used. With wrapping, some molecules will jump between sides of the cell in the trajectory file to yield the periodic image nearest to the origin. Without wrapping, molecules will have smooth trajectories, but water in the trajectory may appear to explode as individual molecules diffuse. Wrapping only affects output, not the correctness of the simulation.

wrapWater           on              ;# wrap water to central cell
wrapAll             on              ;# wrap other molecules too
wrapNearest         off             ;# use for non-rectangular cells

Particle mesh Ewald (PME) full electrostatics are more accurate and less expensive than larger cutoffs, and are recommended for most work. PME is only applicable to periodic simulations, and the user must specify a grid corresponding to the size of the periodic cell. PME grid dimensions should have small integer factors only and be greater than or equal to length of the basis vector. To manually define the grid size instead of letting NAMD choose the dimensions for you according to these guidelines, replace the GridSpacing command with explicit GridSize commands instead.

#PME (for full-system periodic electrostatics)
PME                 yes

# let NAMD determine grid
PMEGridSpacing      1.0

# manually specify grid
#PMEGridSizeX        32  ;# 2^5, close to 31.2
#PMEGridSizeY        45  ;# 3^2 * 5, close to 44.8
#PMEGridSizeZ        54  ;# 2 * 3^3, close to 51.3

Constant pressure is recommended for periodic simulations. Using group-based pressure to control the periodic cell fluctuations is desirable because the atom-based pressure has more high-frequency noise. useFlexibleCell is useful for anisotropic systems such as membranes, allowing the height, length, and width of the cell to vary independently, possibly even fixing the lipid cross-sectional (x-y plane) area with useConstantArea. For a protein surrounded by water there is nothing to prevent the cell from becoming highly extended in one dimension, so it is better to choose useFlexibleCell no in this case.

# Constant Pressure Control (variable volume)
useGroupPressure      yes ;# needed for rigid bonds
useFlexibleCell       no  ;# no for water box, yes for membrane
useConstantArea       no  ;# no for water box, maybe for membrane

The actual parameters of the Nosé-Hoover Langevin piston method control the target pressure and the dynamical properties of the barostat. A ``piston'' with a longer period (i.e., larger mass) will better damp out fluctuations in the instantaneous pressure. Langevin dynamics is applied to the piston itself coupling it to a heat bath with a damping constant of $1 / $langevinPistonDecay. We set langevinPistonDecay smaller that langevinPistonPeriod to ensure that harmonic oscillations in the periodic cell are overdamped.

langevinPiston        on
langevinPistonTarget  1.01325      ;# pressure in bar -> 1 atm
langevinPistonPeriod  100.         ;# oscillation period around 100 fs
langevinPistonDecay   50.          ;# oscillation decay time of 50 fs
langevinPistonTemp    $temperature ;# coupled to heat bath

When initially assembling a system it is sometimes useful to fix the protein while equilibrating water or lipids around it. These options read a PDB file containing flags for the atoms to fix. The number and order of atoms in the PDB file must exactly match that of the PSF and other input files.

fixedAtoms          on
fixedAtomsFile      myfixedatoms.pdb  ;# flags are in this file
fixedAtomsCol       B                 ;# set beta non-zero to fix an atom

The interactive MD features of NAMD and VMD allow you to connect to a running simulation to apply steering forces manually. These options affect performance, and should therefore not be used unless you are actually steering the simulation.

IMDon           on
IMDport         3000    ;# port number (enter it in VMD)
IMDfreq         1       ;# send every 1 frame
IMDwait         no      ;# wait for VMD to connect before running?

Now we minimize the system to eliminate bad initial contacts, reinitialize the velocities to the desired target temperature (since minimization sets velocities to zero), and run for 100ps. We could accomplish the same thing with two different NAMD runs using the numsteps and minimization options. Scripting commands such as those below override numsteps.

minimize            1000          ;# lower potential energy for 1000 steps
reinitvels          $temperature  ;# since minimization zeros velocities
run 50000 ;# 100ps

Naturally, these are not all of the configuration options accepted by NAMD, but only a rapid introduction to those you are most likely to encounter. Documentation for these and many other options can be found in the Users Guide.

next up previous
Next: NAMD Standard Output Up: NAMD Tutorial Previous: Parameter Files