Topology
For every molecule in the PumMa simulation a topology description is required. Instead of using one file to describe all topologies present in the system, PumMa has chosen to uses separate files for each molecule, the so-called .ptf files. For instance a bilayer simutation typically consists of two types of molecules, water (W) and the lipids (DPPC). Therefore two ptf files exist, W.ptf and DPPC.ptf.
To introduce the topology file format in PumMa we will first consider two examples (coarse grained water and CHARMM TIP3 water). In depth discussion of each line type is postponed until after the examples. However, it is good to notice that also for the topology file blank lines and lines starting with # are ignored and that lines can be in any order, as long as no redeclaration occurs.
Example files
As an first example the topology file of water used in the bilayer coarse grained model is discussed. This topology file looks like:
ATOM A1 W 0.0000
This is clearly a very simple topology file, since it only consists of one line. This line specifies that it handles the occurence of an atom in the molecule, hence the keyword ATOM. The second argument gives us the local atom name, in the example A1. This name can be anything, but it has to be unique for this molecule. Next the atom type is given, in this case W. This atom type has to be declared in the parameter file. The last argument gives the charge for that atom in the molecule (in units of e).
If we now take a look at the TIP3 water model, use in CHARMM, casted in the PumMa file format, the topology file looks like:
ATOM A1 O -0.834 ATOM A2 H 0.417 ATOM A3 H 0.417 BOND A1 A2 BOND A1 A3 ANGL A2 A1 A3
Since in the TIP3 water model the water molecule is build from three atoms, three lines starting with the ATOM keyword are present. Furthermore, two bond declarations (keyword BOND, using the local atom names) and an angle declaration (keyword ANGL) are found in the topology description.
Atom types in the molecule
The atom types are declared by using the keyword ATOM. This declaration is followed by the atom name, the atom type and the charge on the atom. An atom typing line could look like:
ATOM A1 H 0.00
The second argument is arbitrary. It is not used in assigning any properties within the PumMa code, in fact, it only helps the user to identify atoms in the topology file. However, it needs to be a unique name inside this topology file. Therefore, a good habit is the put the topology atom number identifier in this first argument (as is done above by naming the atom A1). The third argument is the atom type for the atom at this position in the molecule (in this case the atom is of type H). While parsing this atom type is checked against the parameter file. If the atom type is not specified in the parameter file, the parser will produce an error and the simulation will terminate. The last argument is the charge on that atom in the molecule (in units of e). It is important to notice that the charge is the only true parameter of an atom type that is not set within the parameter file, but in the molecule file.
Bonds
Besides all the atom typing, the declaration of bonds can also be important, and looks like:
BOND A1 A3
Each individual bond is specified on its own line, indicated by the keyword BOND. The names that follow the declaration are the names assigned to the atoms with the atom declaration. In this small example atom A1 is bonded to atom A3. Using this format it is easy to remove bonds from molecules. Simply delete the line containing the bond to be removed. Although the molecule might now be split into two separate parts, the code still treats them as if they were one molecule (for instance when dumping coordinate and velocity files).
Angles
The format for angle assignement is quite alike the bonds, also the atom names that are assigned previously are used. An angle between three atoms can be described by
ANGL A3 A1 A2
This line tells the parser that for the angle between the bonds A3-A1 and A1-A2 an angle potential has to be calculated. The order in which the atom numbers appear in the line must be the order in which the atoms are found in the molecule, hence, in consecutive order. Thus, in this example, atom A1 is the central atom of the angle. As with the bonds, each angle appears on its own line.
Dihedrals
The next topology issue that has to be addressed in the topology file are the dihedrals, using the keyword TORS. Instead of two (bonds) or three (angles) atom names on one line, the dihedrals specification takes four atom names, for example:
TORS A5 A7 A9 A11
These four atoms also need to be in consecutive order and bonds between each following number must exist (in this example the bonds A5-A7, A7-A9 and A9-A11). The dihedral angle to be calculated is the angle between the plane specified by the first three atoms (A5, A7 and A9 in this example) and plane specified by the last three atoms (A7, A9 and A11). As before, each dihedral appears on its own line.
Impropers
An improper specification, using the keyword IMPR, also consist of four names. An example improper declaration might look like
IMPR A2 A6 A7 A8
In contrast to both angles and dihedrals, the numbers indicating the atoms do not follow each other in consecutive order. The first atom specified is the central atom of the improper, see improper potentials. Consequently, in this example, bonds between A2-A6, A2-A7 and A2-A8 have to exist. The improper angle is the angle between the plane specified by the first three atoms (A2, A6 and A7 in this example) and the last three (A6, A7 and A8). Of course every improper is specified on its own line.
Colors
Depending on how the topology file is constructed (by hand or by using the PumMaTK program) a final line indicating the color (using the keyword COLO and in integer RGB values) of the molecule can be present. This line is ignored by the PumMa code, and is only used within the PumMaTK program.
Example lipid topoplogy
The topology file used in the coarse grained bilayer simulations looks like
ATOM A1 G 0.000000 ATOM A2 G 0.000000 ATOM A3 G 0.000000 ATOM A4 G 0.000000 ATOM A5 T 0.000000 ATOM A6 T 0.000000 ATOM A7 T 0.000000 ATOM A8 T 0.000000 ATOM A9 T 0.000000 ATOM A10 T 0.000000 ATOM A11 T 0.000000 ATOM A12 T 0.000000 BOND A1 A2 BOND A2 A3 BOND A3 A4 BOND A4 A5 BOND A5 A6 BOND A6 A7 BOND A7 A8 BOND A3 A9 BOND A9 A10 BOND A10 A11 BOND A11 A12 ANGL A5 A6 A7 ANGL A6 A7 A8 ANGL A9 A10 A11 ANGL A10 A11 A12 COLO 3 12 207
Hence, a lipid in this model consists of 12 atoms, 11 bonds and 4 angles. The atom names A1 to A4 are reserved for uncharged G (head) particles, and the atom names A5 to A12 for T (tail) particles, which also carry no charge. Eight atoms have only two bonds, three atoms only one (atoms A1, A8 and A12), and one atom has three bonds (atom A3). The first eight atoms are in consecutive order, but a second chain is joined to the main chain at atom A3. This results in a two tailed lipid. Angles are only specified within the consecutive set of T particles. The last line indicates that the PumMaTK color code for this molecule is blueish. A graphical depiction of this lipid molecule would result in this:
A1 A2 A3 A9 A10 A11 A12
G -- G -- G -- T ++ T ++ T ++ T
|
G -- T ++ T ++ T ++ T
A4 A5 A6 A7 A8
The names indicate the atom names assignment within the topology files, the letters indicate the atom types, dashes bonds and crosses angles.
<< System configuration | Manual | Coordinates >>