CHARMm Principles

1       Introduction to CHARMm

CHARMm (Chemistry at Harvard Macromolecular Mechanics) is a highly flexible molecular mechanics and dynamics program originally developed in the laboratory of Dr. Martin Karplus at Harvard University. A variety of systems, from isolated small molecules to solvated complexes of large biological macromolecules, can be simulated using CHARMm.

CHARMm uses empirical energy functions to describe the forces on atoms in molecules. These functions, plus the parameters for the functions, constitute the CHARMm force field. Well-validated energy and force calculations form the core of a broad range of calculation and simulation capabilities, including calculation of interaction and conformational energies, local minima, barriers to rotation, time-dependent dynamic behavior, free energy, and vibrational frequencies.

This book describes CHARMm and many of the functions of CHARMm. This first chapter provides an overview of CHARMm activities and basic information on how CHARMm works. It is included, along with Chapters 2 through 5, in the first part of the book describing basic CHARMm activities. The remaining chapters in Part Two describe several CHARMm advanced calculations.

This chapter explains

• Getting started

• Understanding CHARMm processes

• Commands and command files

• Input and output operations

• File formats

• Command stream control

• CHARMm measurement units

• CHARMm array dimensions

Before you begin

The software must be ready. That is, you must have properly licensed software installed and running. If you want to run CHARMm in a stand-alone mode, you need the CHARMm software. If you want to use CHARMm as part of your QUANTA software, you need the QUANTA software including CHARMm.

To start CHARMm

If you are using CHARMm in a stand-alone mode, type the following to access the program:

>	charmm < input.file > output

Understanding CHARMm processes

As illustrated in this figure, the activity flow is as follows:

1.   Read model definitions -- Information about residues, the basic chemical units that comprise all models, is stored in residue topology files (RTF). The atoms, atomic properties, bonds, bond angles, torsion angles, improper torsion angles, hydrogen bond donors, acceptors, and antecedents, and non-bonded exclusions are all specified on a per residue basis.

2.   Read sequence -- Sequence information must be supplied from sequence (.seq) files before a model can be simulated.

3.   Read parameters -- When a structure has been generated, its energy can be evaluated only if parameters exist for all internal, external, and special energy terms. Parameter files contain parameters that specify force constants, equilibrium geometries, van der Waals radii, and other data needed for calculating energies. The values are derived from experimental data and quantum mechanical calculations. Refinement and extension of parameters is a continuing process.

4.   Generate PSF -- The protein structure file (PSF) is the concatenation of information in the RTF. It specifies the information for the entire structure. The PSF has a hierarchical organization with atoms collected into groups, groups into residues, and residues into segments that comprise the structure. Each atom is uniquely identified within a residue by its IUPAC name, residue identifier, and segment identifier.

5.   Read or generate Cartesian coordinates -- Cartesian coordinates can be read into the coordinate file or generated from internal coordinates and parameter files. Internal coordinate files contain information about the relative positions of atoms within a structure.

Two sets of Cartesian coordinates are provided. The main set is the default used for all operations involving the positions of atoms. A comparison or reference set is used for a variety of purposes, such as a reference for rotation or for operations that involve differences between coordinates for a particular molecule. Associated with each coordinate is a general purpose weighting array.

6.   Calculate energy -- The main purpose of CHARMm is the evaluation and manipulation of the potential energy of a macromolecular system. Before the energy of a structure can be evaluated and manipulated, the following must be available:

• A PSF for the structure generated from the appropriate RTF

• All parameters required by the PSF

• Defined Cartesian coordinates for every atom in the structure

7.   Perform calculations and simulations -- This is the point at which the process diverges. Using information in the PSF and parameters files and the energy data you have calculated, you can do any of a number of things at this point including molecular dynamics, free energy perturbation, and imposing periodic boundaries.

Many commands are abbreviated in files and scripts. Generally, using the first four letters of any command are sufficient to uniquely identify it. Check the CHARMm Dictionary for information if you see commands that are unfamiliar to you.

In general, ordering of commands is limited only by the data required by the command. For example, energy cannot be calculated unless information about coordinates, parameters, and so on has already been read into the program

Command file title

A command file for CHARMm must begin with a title. This title can describe the overall purpose of the calculation or contain other information to document the run.

A title must also precede all data being entered into CHARMm as part of a command stream or as an external file. A title consists of as many as 32 lines of information. An asterisk (*) must be the first character in each line of the title. Furthermore, a single asterisk must be used to terminate the title. An example of a valid CHARMm title is:

* Example of CHARMm title
* Test CHARMm minimization and dynamics run
*

Each command line consists of a command and keywords, possibly followed by other data. The command line is scanned in free-field format.

The command line can be longer than one line. To use more than one line, place a hyphen at the end of the line that is to be continued on the next line.

A comment can be placed on a command line by preceding the comment with an exclamation point (!). Additionally, blank lines are permitted to separate blocks of command lines for increased readability.

As each command is read by CHARMm, it is echoed to the output file. Any output resulting from the execution of a command follows. Some commands do not produce any output.

The first word of every command line specifies the command itself. Generally, required keywords of a command must follow in order. Optional keywords can generally be specified in any order. A numeric value is always preceded by a keyword.

Abbreviations are permitted in various contexts. Commands, keywords, and operands can be abbreviated to four characters. However, some keywords used to mark numbers can not be abbreviated.

Many command options and numeric values are maintained from one invocation of a command to the next. When a value is specified, it is maintained until it is changed in a subsequent command. For example, if the nonbonded cutoff value is specified in an energy command, it will be used in a subsequent dynamics calculation.

As each command is interpreted by CHARMm, a check is made to see that no extraneous information remains. Extraneous alphanumeric information is usually an indication of a error in entering the command or keywords in the command line.

Input and output operations

• Using a CHARMm command stream file, an input file that you create to direct CHARMm.

A command stream file is a special file consisting entirely of CHARMm commands. When a command stream file is invoked, the file is read and its commands are executed in sequence. Command stream files are convenient for operations needing several CHARMm commands that are applied repetitively or are used in several contexts.

• Using external files.

External files can be manipulated by CHARMm as directed by a command stream file. A variety of commands allow files to be opened and closed and data to be written or read in a number of different formats:

OPEN command -- Opens logical units to files specified from the input file rather than from logical name assignments made prior to the run. External files must be opened prior to reading or writing data structures. Implicit file opening is also possible.

READ command -- Reads data from external files into data structures in CHARMm. The external files can either be formatted text files or unformatted binary files.

WRITE command -- Saves the CHARMm data structures to external files. When you create an external data file using CHARMm, provide a valid title. This title is written at the start of the file and serves to document that file.

CLOSE command -- Closes a previously opened logical unit. This frees the associated file and logical unit so that they can be used for other purposes.

File formats

Data file	Text	Binary
Residue topology files (RTFs)	3	·
Residue topology files (appended)	·
Parameter files	·	·
Sequence files	·
Protein structure files (PSFs)	·	·
Coordinate files	·	·
Dynamics trajectories (coordinate and velocity)	1	·
Constraint (harmonic atom) files	·	·
Crystal image files	·
Hydrogen bond list files	·	·
Nonbonded list files	·	·
Internal coordinate files	·	·
Image transformation files	·
Normal mode files (VIBRAN)		·

1 Dynamics trajectories can be stored in a machine-independent, hexadecimal format.

Converting file formats

* ...
* Copyright (c) 1986, 1987, 1988, 1989, 1990, 1991, 1992
* Molecular Simulations Incorporated
* Confidential and Proprietary: All Rights Reserved
* ...
* ...
* This input file will create binary data files
* ...
*
upper
open read unit 11 card name masses.rtf
read rtf unit 11 card
close unit 11
open read unit 11 card name amino.rtf
read rtf unit 11 card appe
open read unit 12 card name parm.prm
read para unit 12 card
open writ unit 12 file name "AMINO.BIN"
writ rtf unit 12 file
* ...  
* Topology File for CHARMm Version 22  (Polar Hydrogens Only)
* ...
* ...
* Copyright (c) 1986, 1987, 1988, 1989, 1990, 1991, 1992
* Molecular Simulations Incorporated
* Confidential and Proprietary: All Rights Reserved
* ...
* Includes topology definitions for the twenty naturally
* occurring
* amino acids, some commonly used patches, and water.
* Hydrogens are specified for polar atoms (such as N and O).
* ... 
* Latest creation of binary file:  $Date: 94/12/27 17:38:27 $
* ...
*
open writ unit 13 file name "PARM.BIN" 
writ para unit 13 file
* ...
* Parameter File for CHARMm Version 22
* ...
* Includes parameters for both polar and all hydrogen topology
*files
* ...
* Copyright (c) 1986, 1987, 1988, 1989, 1990, 1991, 1992
* Molecular Simulations Incorporated
* Confidential and Proprietary: All Rights Reserved
* ...
* Dihedrals are presumed to be automatically generated and 
* should be totally specified, i.e. amide bonds have 4 dihedral
* terms and ethane has 9 dihedral terms. Check the CHARMm PSF
* if necessary.
* This does not necessarily imply multiple periodicity.
* ...  
* Latest creation of binary file:  $Date: 94/12/27 17:38:27 $
* ...
* stop

CHARMm parameters

The SET command sets up a command line parameter. Command line parameters are substituted into the command line by the command line reader when it encounters the symbol @.

In the current version of CHARMm, a command line parameter token can be a string instead of only a single character (that is, 0-9, a-z, or A-Z). The token is end-delimited by any non-alphanumeric character.

When a token is not found in the parameter table, a check is made to see if the first character of the token is itself a token in the parameter table. If this single-character token is in the table, the corresponding value is substituted. This scheme allows backwards compatibility with the old parameter substitution that allowed parameters to be embedded in strings.

To test if a token is in the parameter table, use @?token. This will substitute 1 if a token is in the table and 0 if it is not. This test is useful together with the IF command for setting defaults. Note that @? takes precedence over any of the built-in parameters such as ?ENER. It is parsed first.

For unambiguous token detection, protect your tokens with brackets {}. This also allows you to use non-alphanumerics such as a dash, comma, or underscore character in tokens.

Example: Using a parameter token

In this short example, the token is delimited by the period in the filename and the value myjob is substituted in place of @outfile.

SET outfile = myjob 
OPEN UNIT 1 WRITE CARD NAME @outfile.dat

CHARMm variables

CHARMm variables can be used in titles or in conjunction with CHARMm parameters. You can query the current value of a number of CHARMm variables by placing a question mark before the variable name. For example, if you use ?VDW, you get the current van der Waals energy reported.

Conditional statements are used to check the values of parameters or variables. Operations such as equal, not equal, and less than are supported. The consequence of using a conditional statement can be to transfer control within the command stream or to perform specific CHARMm commands.

CHARMm measurement units

Variable	AKMA	SI
Length	1 Å	1 x 10-10 m
Energy	1 kcal/mol	4186 J/mol
Mass	1 AMU	1.661 x 10-27 kg
Charge	1 electron	1.602 x 10-19 C
Time	1 time unit	0.04888 x 10-12 sec
Force	1 kcal/mol-Å	6.95 x 10-1 N

Using the AKMA system, the unit of time is 4.888821E-14. Twenty AKMA time units equal 0.978 picoseconds. Although CHARMm computes time using AKMA units, output is usually expressed in picoseconds.

Angles are given in degrees for the CHARMm analysis and constraint sections. In parameter files, minimum positions or angles are specified in degrees, but force constants for angles, dihedrals, and dihedral constraints are specified in kcal/mole/radian/radian.

CHARMm array dimensions

Array definition	Medium	Large
Maximum number of atoms	30,000	120,000
Maximum number of atoms including image atoms	60,000	240,000
Maximum number of atom types	500	500
Maximum number of bonds	30,000	120,000
Maximum number of angles	30,000	120,000
Maximum number of dihedral angles	60,000	240,000
Maximum number of improper dihedral angles	9,200	29,646
Maximum number of groups	10,000	40,000
Maximum number of residues	14,000	32,000
Maximum number of segments	5,000	5,000
Maximum number of hydrogen bonds	8,000	14,000
Maximum number of hydrogen bond donors or acceptors	8,160	29,646
Maximum number of image transformations	5,000	5,000
Maximum number of crystal symmetry operations	192	192
Maximum number of internal coordinate entries	30,000	120,000
Maximum number of restrained dihedral angles	500	500
Maximum number of NOE restraints	2,000	2,000
Maximum number of SHAKE constraints	22,500	90,000
Maximum number of bond parameters	1,500	1,500
Maximum number of angle parameters	5,500	5,500
Maximum number of dihedral parameters	3,000	3,000
Maximum number of improper dihedral parameters	600	600
Maximum number of hydrogen bond parameters	3,200	3,200
Maximum number of VDW values	8,192	8,192
Maximum number of explicit nonbonded exclusions	17,200	17,200
Maximum number of residues within a topology file	200	200
Maximum number of atoms for all residue definitions	3,000	3,000
Maximum number of bonds for all residue definitions	3,000	3,000
Maximum number of internal coordinates for all residue definitions	3,000	3,000
Maximum number of hydrogen bond acceptors for all residue definitions	300	300
Maximum number of hydrogen bond donors for all residue definitions	300	300
Maximum number of improper dihedral angles for all residue definitions	2,000	2,000
Maximum number of dihedral angles for all residue definitions	2,000	2,000
Maximum number of angles for all residue definitions	2,000	2,000
Maximum number of nonbonded exclusions for all residue definitions	2,000	2,000