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 18.
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.5 lists the parameters which are required to run a basic simulation. Section 16 describes the relation between specific NAMD and X-PLOR dynamics options. Several sample NAMD configuration files are shown in section 17.
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'' (or ``minimize'' or ``startup'') 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.
If the argument --tclmain is present, all following arguments will
be passed to the Tcl interpreter as a script file and arguments accessible
via the standard argc and argv variables.
Note that Charm++ arguments such as +pemap are processed during
Charm++ startup and will not be passed to Tcl.
If the first argument is +tclsh,
Charm++ argument parsing and startup are not performed,
the Tcl interpreter is initialized without NAMD scripting features,
and all following arguments are passed to Tcl.
Statically linked packages such as psfgen are available via ``package require ...''.
identifying the option
being specified, and a 
which is a parameter to be used for this
option. The keyword and value can be separated by only white space:
keyword valueor the keyword and value can be separated by an equal sign and white space:
keyword = valueBlank 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 commentor 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 filenameor 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.
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:
Additional features include:
Force and energy analysis are especially useful in the context of pair interaction calculations; see Sec. 15.1 for details, as well as the example scripts in Sec. 17.
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''.
Multiple-copy (or replica-based) algorithms are supported by the following commands, which utilize two-sided semantics modeled on MPI:
The replicaSend/Sendrecv data argument may be any string, and hence any Tcl object (e.g., a list) that can be represented as a string. Data received from the source replica is returned by replicaRecv/Sendrecv. In order to ensure message ordering, replicaSend/Sendrecv will block until the corresponding remote receive call (except when replicaSend is called from inside replicaEval, as discussed below).
The parameter replicaUniformPatchGrids must be true for atom exchange (replicaAtom...) or remote checkpointing (checkpoint... with a second argument, see below).
The following additional commands utilize one-sided semantics, and should provide a complete feature set for running a simulation with fewer NAMD replica partitions than logical replicas:
The key can be any string. By default the checkpoint is stored in the memory of the replica the command is called on. If you specify a replica index the checkpoint is stored asynchronously in that replica's memory. If you specify ``global'' a hash is computed based on the key to select the replica on which to store the checkpoint. You can have checkpoints with the same key stored on multiple replicas at once if you really want to. The checkpoint... commands will not return until the checkpoint operation has completed.
Storing checkpoints is not atomic. If two replicas try to store a checkpoint with the same key on the same replica at the same time you may end up with a mix of the two (and probably duplicate/missing atoms). If one replica tries to load a checkpoint while another replica is storing it the same may happen. You cannot store a checkpoint on a replica until that replica has created its own patch data structures. This can be guaranteed by calling ``startup'' and ``replicaBarrier'' before any remote checkpoint calls.
The replicaEval command asynchronously executes its script in the top-level context of the target replica's Tcl interpreter and returns the result or error. This should be general enough to build any kind of work scheduler or shared data structure you need. If you want to call replicaEval repeatedly, e.g., to check if some value has been set, you should call ``replicaYield seconds'' in between, as this will introduce a delay but still enable processing of asynchronous calls from other replicas. Potentially blocking functions such as replicaRecv should not be called from within replicaEval, nor should functions such as run, checkpointLoad/Store, and replicaAtomSend/Recv that would require the simulation of the remote replica to be halted. It is allowed to call replicaSend (but not replicaSendrecv) from within replicaEval, since replicaSend is non-blocking and one-sided (but potentially overtaking) in this context. Rather than polling a remote replica (e.g., for work) via replicaEval, it is more efficient to register a request via replicaEval and then call replicaRecv to wait for notification.
The replicaDcdFile command is similar to the dcdFile command in that it changes the trajectory output file, but the file is actually opened by a different replica partition and may be written to by any other partition that calls replicaDcdFile with the same index but no filename argument. If a filename argument is given, any file currently associated with the index is closed and a new file created, even if the new and old filenames are the same. The new file is created only when the next trajectory frame is written, not during the replicaDcdFile command itself. The caller must ensure that an index is not used before it is associated with a filename, and that each index is in use by only one replica at a time. The keyword ``off'' will return to writing the local trajectory file set by the dcdFile command.
NAMD may be compiled with an embedded Python interpreter
via the config script option --with-python.
Currently, Python 3.x versions are not yet supported.
The default embedded Tcl interpreter is also required to enable Python scripting.
Released NAMD binaries do not support Python scripting at this time
due to portability issues with the extensive Python library.
Python scripting is accessed via the Tcl ``python'' command, which functions in either expression mode or script mode. When passed a single-line string, the Python interpreter will evaluate the expression in the string and return the result. Python containers (tuples, lists, etc.) are converted to Tcl lists and all other values are converted to their string representation, which is typically compatible with Tcl. For example, ``[python ( 1 + 1, 'abc' + '123' )]'' evaluates to the Tcl list ``2 abc123''.
When the python command is passed a single multi-line string (typically enclosed in braces), the Python interpreter will execute the code in the string and return nothing. Because of Python's indentation-sensitive syntax the enclosed code can not be indented.
Calls to Tcl from Python code are supported by the tcl module functions tcl.call(), which takes the Tcl command name and its arguments as separate arguments and performs limited container and string conversions as described above, and tcl.eval(), which passes a single string unmodified to the Tcl interpreter. Both functions return the result as a string, so numerical results must be explicitly cast to float or int as appropriate.
NAMD simulation parameters and commands are wrapped for convenience by the ``namd'' object. Any NAMD simulation parameter may be set by assigning to the corresponding case-insensitive attribute of the namd object, e.g., ``namd.timestep = 1.0'', and similarly read (as a string) by access, e.g., ``ts = float(namd.TimeStep)''. Assignment corresponds exactly to normal config file parsing, i.e., ``timestep 1.0'', and hence multiple assignment will generate an error just as would repeated parameters. For convenience, multiple parameters may be set at once by passing them as keyword arguments, e.g., ``namd(langevin=True, langevinDamping=5., langevinTemp=100.)''. NAMD (and other) commands in the Tcl interpreter may be called as a method of the namd object, e.g., ``namd.run(1000)'' and ``namd.output('myfile')''.
The NAMD 1-4scaling parameter is incompatible with Python syntax, but may be accessed several other ways, e.g., ``namd.param('1-4scaling',1.0)'', ``tcl.call('1-4scaling',1.0)'', or ``tcl.eval('1-4scaling 1.0')''.
The following example illustrates various aspects of the Python scripting interface:
set a 1
cutoff 12.0
python {
# do not indent
namd.pairlistDist = float(namd.Cutoff) + float(tcl.eval("set a")) # cast strings to float
b = 2
namd(switching=True, switchdist = float(namd.cutoff) - b) # case insensitive
}
set c [python $a + b]
The following parameters are required for every NAMD simulation:
![[*]](crossref.png)
),
),
),
),
),
),
),
),
).
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.