Overview of Running CHARMM

Scope

The documentation presented here is for academic versions of the CHARMM program (Chemistry at HARvard Molecular Mechanics), as maintained at the development sites. Quite a few features are contained in these versions may or may not be included in the in a given executable, as some are optional, and other sets of features are considered mutually exclusive, such as the quantum mechanics interface. For the same reason, the commercial CHARMm version distributed by Accelrys may or may not certain features. The information in these .doc files has been contributed by CHARMM developers over the years, and hopefully reflects the current state of the program.

CHARMM remains essentially a command line program, i.e. a command is read from the input stream (typed, or from a file) and acted upon. CHARMM is under active development, and there are significant enhancements occurring on a regular basis. Consequently, available features and documentation will change over time; regular upgrades are recommended.


Running CHARMM Under Unix

While CHARMM may be run interactively, that is not usually recommended, except for graphics; even then, a stream file should be used for the initial setup (reading PSF, coords, etc.). The general syntax for using the program (assuming /bin/csh) is:

charmm < file.inp >& file.out [[param:value] ...] [ & ]

charmm
The actual name of the program (or script which runs the program) on the computer system being used; the name may not be the same on all systems.
file.inp
A text file containing CHARMM input commands, using the command syntax described in usage.doc. The actual file is up to the user, although it is useful to use short names which hint at the overall purpose, e.g. makpsf.inp for a file which makes a PSF.
file.out
The log file for the CHARMM run, containing echoed commands, and various amounts of command output. The output print level may be increased or decreased in general, and procedures such as minimization and dynamics have printout frequency specifications.
param:value
CHARMM script parameters (essentially user defined variables) may optionally be defined on Unix shell command line, using the form param:value; the value is substituted for occurrences of @param in the input script.
&
The optional ampersand will place the program in the background under most Unix shells; note that the computer system being used may have a batch job queueing system which should normally be used instead of running CHARMM as a background process via the above syntax.

Consult the local system administrator to determine the actual program name (e.g. charmm, charmm-mpi, etc.) and the policy for running compute intensive tasks (batch queue, background, etc.) on the computer system being used. In general, CHARMM calculations are best limited to around a day or two, to both promote resource sharing and to minimize data loss due to machine or network failures.

For foreground usage, e.g. graphics, start the program by typing it's name alone, wait for the program "header" to be printed, and enter a title. Then use a "stream" file, e.g.

stream toppar-psfcrd.str

will read CHARMM commands from the file named toppar-psfcrd.str as if they were being typed at the keyboard; as implied by the name, the stream file reads the RTF, PARAms, PSF, COORdinates, etc., the basic starting point for nearly all work with CHARMM.

For parallel usage, the command to run CHARMM is more complex, and depends on the both the parallel library (typically an MPI implementation), and local conventions at the computing facility. An example might be

mpirun -np 64 mpi-opts /path/charmm -i file.inp >& file.out

where mpi-opts represents additional options which may be required, such as indicating a file with list of nodes to use, or specifying a high speed node interconnect such as Infiniband. The /path prefix indicates that the full pathname of the program is needed; param:value arguments can also be used as above, as long as they follow the full pathname of the CHARMM executable. Consult your support staff or cluster documentation for details on how to run programs in parallel.


CHARMM Documentation Homepage