Moltemplate Manual-(1), November 3, 2017

Moltemplate Manual-(1)(Andrew Jewett, Jensen Lab (Caltech), Shea Lab (UCSB))

 

Warning: This manual does not explain how to run “active-matter" simulations or use all-atom force fields.
        However numerous examples and README files are available to demonstrate how to run these kinds of simulations. Downloading these examples is highly recommended. (See section 2.)

 

        A simple file format has been created to store molecule definitions and force-fields (the LAMMPS-template format, LT). LT files are templates containing all of the text relevant to a particular molecule (including coordinates, bond-topology, angles, force-field parameters, constraints, groups and fixes).Moltemplate can then duplicate the molecule, customize it, and use it as a building-block for constructing larger, more complex molecules. (These molecules can be used to build even larger molecules.) Once built, individual molecules and subunits can be customized (atoms and bonds, and subunits can be inserted, moved, deleted and/or replaced).

 

        Popular force-fields such as AMBER GAFF and OPLS-AA have been converted into LT format, allowing users to quickly create molecules using moltemplate. (With help, more popular force-fields can be converted.) This way moltemplate users can build a molecule by specifying only a list of atoms in the molecule and the bonds connecting them.However they still have the freedom to easily customize individual interactions when needed.

 

1.1  Converting LT files to LAMMPS input/data files

 

The moltemplate.sh program converts LT-files (which contain molecule definitions) into complete LAMMPS input-scripts and data-files:

moltemplate.sh -atomstyle "full" system.lt
or
moltemplate.sh -xyz coords.xyz -atomstyle "full" -vmd system.lt

 

        In the first example, the coordinates of the atoms in the system are built from commands inside the "system.lt" file.

        In the second example coordinates for the atoms are read from an XYZ-file, and then invokes VMD to visualizethe system just created. (PDB-files and other coordinate formats are also supported. Note: The "full" atom style was used in this example, but otherLAMMPS atom styles are supported, including hybrid styles.)
        Either of these commands will construct a LAMMPS data file and a LAMMPS input script (and possibly one or more auxiliary input files), which can be directly run in LAMMPS with minimal editing.

 

1.2  Converting LAMMPS input/data files to LT files

 Existing LAMMPS input/data files can be converted into .LT" files using the ltemplify.py" utility. (Some additional manual editing may be required. See appendix B.)

 

Additional tools
The VMD topotools plugin [1] is useful for converting PDB files into LAMMPS format. These files can then be converted to LT" format using the ltemplify.py" utility. VMD [2] and topotools are also useful for visualizing the data files created by moltemplate.sh (See section 4.3.)

The PACKMOL [3] program is useful for generating coordinates of dense heterogeneous mixtures of molecules, which can be read by moltemplate.
(The VMD solvate" plugin may also be helpful.)

 

Moltemplate files (LT files) share the same file format and syntax structure as LAMMPS DATA files and INPUT scripts.

 

4.1 Simulating a box of water using moltemplate and LAMMPS

 

Figure 1: Coordinates of a single water molecule in our example. (Atomic radii not to scale.)

Here we show an example of a lammps-template file for water. (The settings shown here are borrowed from the simple-point-charge [4] SPC/E model.)

In addition to coordinates, topology and force-field settings, “LT" files can optionally include any other kind of LAMMPS settings including SHAKE constraints, k-space settings, and even group definitions.

 

# (NOTE: Text following ’#’ characters are comments)
#
# file "spce_simple.lt"
#
# H1    H2
#      /
#      O
#
SPCE {
## Atom properties and molecular topology go in the various "Data ..." sections
# We selected "atom_style full". That means we use this column format:

# atomID  molID  atomType  charge   coordX    coordY   coordZ
write("Data Atoms") {
$atom:o   $mol:.  @atom:O  -0.8476  0.0000000  0.000000  0.00000
$atom:h1  $mol:.  @atom:H  0.4238  0.8164904  0.5773590  0.00000
$atom:h2  $mol:.  @atom:H  0.4238  -0.8164904  0.5773590  0.00000
}
# Variables beginning with $ or @ will be replaced by numbers（被数字替代）LAMMPS will
# eventually read. Each of the three atoms" will be assigned unique
# atomIDs (denoted here by "$atom:o", "$atom:h1", "$atom:h2"), even if
# they belong to different molecules. However, the atom types
# (denoted "@atom:O", "@atom:H") are shared for atoms in all molecules.
# All 3 atoms share same molID number (represeted here by "$mol:.")
# however that number is different for different water molecules.
write_once("Data Masses") {
# atomType mass
@atom:O 15.9994
@atom:H 1.008
}
write("Data Bonds") {
# bondID bondType atomID1 atomID2
$bond:oh1 @bond:OH $atom:o $atom:h1
$bond:oh2 @bond:OH $atom:o $atom:h2
}
write("Data Angles") {
# angleID angleType atomID1 atomID2 atomID3
$angle:hoh @angle:HOH $atom:h1 $atom:o $atom:h2
}
# --- Force-field parameters go in the "In Settings" section: ---
write_once("In Settings") {
# -- Non-bonded (Pair) interactions --
# atomType1 atomType2 parameter-list (epsilon, sigma)
pair_coeff @atom:O @atom:O 0.1553 3.166
pair_coeff @atom:H @atom:H 0.0 2.058
# (mixing rules determine interactions between types @atom:O and @atom:H)
# -- Bonded interactions --

# -- Bonded interactions --

#	bondType	parameter list (k_bond, r0)
bond_coeff	@bond:OH	1000.00 1.0
#	angleType	parameter-list (k_theta, theta0)
angle_coeff	@angle:HOH	1000.0  109.47

# Group definitions and constraints can also go in the "In Settings" section
group spce type @atom:O @atom:H
fix fSHAKE spce shake 0.0001 10 100 b @bond:OH a @angle:HOH
# (lammps quirk: Remember to "unfix fSHAKE" during minimization.)
}
# LAMMPS supports a large number of force-field styles. We must select
# which ones we need. This information belongs in the "In Init" section.
write_once("In Init") {

units	real	# angstroms, kCal/mole, Daltons, Kelvin
atom_style	full	# select column format for Atoms section
pair_style	lj/charmm/coul/long 9.0 10.0 10	# params needed: epsilon sigma
bond_style	harmonic	# parameters needed: k_bond, r0
angle_style	harmonic	# parameters needed: k_theta, theta0
kspace_style	pppm 0.0001	# long-range electrostatics sum method
pair_modify	mix arithmetic	# using Lorenz-Berthelot mixing rules

}
} # SPCE

Words which are preceded by “$" or “@" characters are counter variables and will be replaced by integers. (See section 5.2 for details.) Users can include SPCE water in their simulations using commands like these:

# -- file "system.lt" --
import "spce_simple.lt"
wat = new SPCE [1000]
You can now use moltemplate.sh" to create simulation input files for LAMMPS
moltemplate.sh -pdb coords.pdb -atomstyle "full" system.lt
This command will create lammps input files for the molecular system described in “system.lt", using the desired atom style (“full" by default). In this example, moltemplate is relying on an external file (“coords.pdb") to supply the atomic coordinates of the water molecules, as well as the periodic boundary conditions. Coordinates in XYZ format are also supported using “-xyz coords.xyz".

 

Details
Note that since XYZ files lack boundary information, you must also include a “Boundary" section in your “.lt" file, as demonstrated in section 4.2. In both cases, the order of the atom types in a PDB or XYZ file (after sorting) should match the order they are created by moltemplate (which is determined by the order of the “new" commands in the LT file). Unfortunately this may require careful manual editing of the PDB or XYZ file.

 

4.2 Coordinate generation

It is not necessary to provide a separate file with atomic coordinates. It is more common to manually specify the location (and orientation) of the molecules in your system using the “.move()" and “.rot()" commands in the LT file itself (discussed in section 6). For example you can replace the line:

wat = new SPCE [1000]

from the example above with 1000 lines:

 

wat1 = new SPCE

wat2 = new SPCE.move(3.450, 0.0, 0.0)

wat3 = new SPCE.move(6.900, 0.0, 0.0)

wat4 = new SPCE.move(10.35, 0.0, 0.0)

: :

wat1000 = new SPCE.move(34.50, 34.50, 34.50)

 

Specifying geometry this way is tedious. Alternatively, moltemplate has simple commands for arranging multiple copies of a molecule in periodic, crystalline, toroidal, and helical 1-D, 2-D, and 3-D lattices. For example, you can generate a simple cubic lattice of 10×10×10 water molecules (with a 3.45 Angstrom spacing) using a single command (which in this example we split into multiple lines)

wat = new SPCE [10].move(0,0,3.45)
               [10].move(0,3.45,0)
               [10].move(3.45,0,0)

 

(See section 6 for more details and examples.) This will create 1000 molecules with names like “wat[0][0][0]", “wat[0][0][1]",: : :, “wat[9][9][9]". You can always access individual atomIDs, molIDs, bondIDs, angleIDs, and dihedralIDs (if present), for any molecule elsewhere in your LT files using this notation: $atom:wat[2][3][4]/h1", $bond:wat[0][5][1]/oh1", “$angle:wat[2][8][3]/hoh",“$mol:wat[0][1][2]". This allows you to define interactions which link different molecules together (see section 6).

Boundary Conditions:
LAMMPS simulations have finite volume and are usually periodic. We must specify the dimensions of the simulation boundary using the “write once(“Data Boundary")" command.
write_once("Data Boundary") {
0.0 34.5 xlo xhi
0.0 34.5 ylo yhi
0.0 34.5 zlo zhi
}

This is usually specified in the outermost LT file (“system.lt" in this example). (Note: Boundary conditions do not have to be rectangular or even periodic.  For triclinic cells, additional “xy", “xz", and “yz" tilt parameters can be added. For details, lookup the “read data" and “boundary" commands in the official LAMMPS documentation.)

 

This system is shown in figure 2a). After you have specified the geometry, then you can run moltemplate.sh this way:

moltemplate.sh -atomstyle "full" system.lt (本人电脑需用sh moltemplate.sh -atomstyle "full" system.lt)

 

 

Figure 2: A box of 1000 water molecules (before and after pressure equilibration), generated by moltemplate and visualized by VMD with the topotools plugin. (The VMD console commands used for visualization were: “topo readlammpsdata system.data full"（system.data文件须在vmd安装目录下）, “animate write psf system.psf", “pbc wrap -compound res -all", and “pbc box". See sections 4.3, and C for details.

 

To view a data file:
a) start VMD
b) from the menu, select Extensions!Tk Console

c) enter:
topo readlammpsdata system.data full
animate write psf system.psf

 

The first command will display all of the atoms and bonds in your system in VMD’s 3-D window. (We use full" because we are using the full" atom style in this particular example. If you are using a different atom style, then change the command above accordingly.)

The second command will create a PSF file (system.psf") which will be useful later for viewing a trajectory file created during a LAMMPS simulation. (See section 4.5.)

Most likely, atoms and bonds will be represented by ugly dots and lines by default. To change the way molecules are displayed, control their color, display periodic boundaries, and wrap atomic coordinates, read the short VMD tutorial in appendix C

 

4.4 Running a LAMMPS simulation (after using moltemplate)
To run a simulation of one or more molecules, LAMMPS requires an input script and a data file. Input scripts typically contain force field styles, parameters and run settings. (They sometimes also contain atom coordinates.) Data files typically contain atom coordinates and bonded topology data. (They sometimes also contain force-field parameters.)

Moltemplate will create the following files: system.data", system.in", system.in.init", system.in.settings", (and possibly other files including system.in.coords").

These are LAMMPS input/data files, and they can be run in LAMMPS with minimal modification (see below).

 

The main input script file is named system.in", and it usually contains just three lines:

include "system.in.init"
read_data "system.data"
include "system.in.settings"

 

To run a simulation, you will have to edit this file in order to add a couple of run commands. These commands tell LAMMPS about the simulation conditions you want to use (temperature, pressure), how long to run the simulation, how to integrate the equations of motion, and how to write the results to a file (file format, frequency, etc). Moltemplate.sh can not do this for you. Some simple examples (which you can paste into your input script) are provided in the online examples which can be downloaded from http://moltemplate.org. (These example input scripts typically have names like un.in.nvt" and un.in.npt".)

 

5.1 Basics: The write() and write once() commands
Each LT file typically contains one or more write" or write once" commands. These commands have the following syntax

write_once(filename) {text_block}

This creates a new file with the desired file name and fills it with the text enclosed in curly brackets {}. Text blocks usually span multiple lines and contain counter variables (beginning with @" or $"). which are replaced with numbers. However the write()" command will repeatedly append the same block of text to the file every time the molecule (in which the write command appears) is generated or copied (using the ew" command, after incrementing the appropriate counters, as explained in 5.2.2).

 

5.2 Basics: counter variables
Words following a @" or a $" character are counter variables. (These are not to be confused with LAMMPS variables http://lammps.sandia.gov/doc/variable.html). By default, all counter variables are substituted with a numeric counter before they are written to a file. These counters begin at 1 (by default), and are incremented as the system size and complexity grows (see below).

These words typically contain a colon (:) followed by more text. The text preceding this colon is the category name. (For example: $atom:", $bond:", $angle:", @atom:", @bond:", @angle:") Variables belonging to different categories are counted independently.
Users can override these assignment rules and create custom categories. (See appendices D.1 and D.2 for details.)

 

5.2.1 Static counters begin with @"
@" variables generally correspond to types: such as atom types, bond types, angle types, dihedral types, improper types.  These are simple variables and they assigned to unique integers in the order they are read from your LT files.  Each uniquely named variable in each category is assigned to a different integer. For example, @bond:" type variables are numbered from 1" to the number of bond types. (Pairs of bonded atoms are assigned a bond type. Later, LAMMPS will use this integer to lookup the bond-length and Hooke’s-law elastic constant describing the force between these two atoms.)

 

5.2.2 Instance counters begin with $"
On the other hand, $" variables correspond to unique ID numbers: atomIDs, bond-IDs, angle-IDs, dihedral-IDs, improper-IDs, and molecule-IDs.
These variables are created whenever a copy of a molecule is created (using the ew" command). If you create 1000 copies of a water molecule using a command like

wat = new SPCE[10][10][10]

then moltemplate creates 3000 $atom" variables with names like

 

$atom:wat[0][0][0]/o
$atom:wat[0][0][0]/h1
$atom:wat[0][0][0]/h2
$atom:wat[0][0][1]/o
$atom:wat[0][0][1]/h1
$atom:wat[0][0][1]/h2
...
$atom:wat[9][9][9]/o
$atom:wat[9][9][9]/h1
$atom:wat[9][9][9]/h2

 

5.2.3 Variable names: short-names vs. full-names
In the example above, the $ variables have full-names like $atom:wat[8][3][7]/h1", not $atom:h1". However inside the definition of the water molecule, you don’t specify the full name. You can refer to this atom as $atom:h1". Likewise, the full-name for the @atom variables is actually @atom:SPCE/H", not @atom:H".

However inside the definition of the water molecule, you typically use the shorthand notation @atom:H".

 

5.2.4 Numeric substitution
Before being written to a file, every variable (either $ or @) with a unique full-name will be assigned to a unique integer, starting at 1 by default.
The various $atom variables in the water example will be substituted with integers from 1 to 3000 (assuming no other molecules are present).
But the “@atom:O" and “@atom:H" variables (which are shorthand for @atom:SPCE/O" and @atom:SPCE/H") will be assigned to 1" and 2" (again, assuming no other molecule types are present). So, in summary, @ variables increase with the complexity of your system  (IE the number of molecule types or force-field parameters), but $ variables increase with the size of your system.

 

5.2.5 Variable scope
This effectively means that all variables are specific to local molecules they were defined in. In other words, an atom type named @atom:H" inside the SPCE" molecule,  will be assigned to a different number than an atom named @atom:H" in an Arginine" molecule. This is because the two variables will have different full names (@atom:SPCE/H", and @atom:Arginine/H").

Sharing atom types or other variables between molecules
There are several ways to share atom types between two molecules. The recommended way is to define them in a separate file and refer to them when needed. This approach is demonstrated in section 6.1.
(Alternately, you can define them outside the current molecule definition, and use file-system-path-like syntax (../", or ../../" or /") to access atoms (or molecules) outside of the current molecule. For example, two different molecule types can share the same type of hydrogen atom by referring to it using this syntax: @atom:../H". For details, see section 9.6. and appendix G.)

 

5.3 Troubleshooting using the output ttree directory
Users can see what numbers were assigned to each variable by inspecting the contents of the output ttree" subdirectory created by moltemplate. Unfortunately, it not unusual for LAMMPS to crash the first time you attempt to run it on a DATA file created by moltemplate. This often occurs if you failed to spell atom types and other variables consistently. The LAMMPS error message (located at the end of the log.lammps" file created by LAMMPS) will help you determine what type of mistake you made. (For example, what type of variable was misspelled or placed in the wrong place?) To help you, the output ttree" directory contains a file named tree assignments.txt". This is a simple 2-column text file containing a list of all of the variables you have created in one column, and the numbers they were assigned to in the second column. (There is also a comment on each line beginning with a #" character which indicates the file and line number where this variable is first used.)

 

The output ttree" directory also contains all of the files that you created. The versions with a .template" extension contain text interspersed with full variable names (before numeric substitution). (A spelling mistake, like using $atom:h" when you meant to say $atom:h1" or @atom:H" will show up in these files if you inspect them carefully.) This can help you identify where the mistake occurred in your LT files. Once a molecular system is debugged and working, users can ignore or discard the contents of this directory.

 

5.4 Data" and In"
Again, LAMMPS requires an input script and a data file to run. Moltemplate’s job is to generate these files. Input scripts typically contain force-field styles,  parameters and run settings Data files typically contain atom coordinates and bonded topology data. If you are familiar with LAMMPS, you may have noticed the file names above (in the example from section 4.1) sound suspiciously like sections from LAMMPS data files or input scripts, such as Data Boundary", Data toms", Data Bonds", Data Masses", Data Angles", Data Dihedrals", Data Impropers", In Init", In Settings"). All files whose names begin with In " or Data " are special. For the user’s convenience, the moltemplate.sh script copies the contents of these files into the corresponding section (Atoms", Bonds", Angles", etc.) of the DATA file or INPUT scripts generated by moltemplate (system.data", system.in.settings", etc). (Then the original files are moved to the output ttree/" directory, in an effort to clean things up and hide them from view.) Users can create their own custom sections to a LAMMPS data file. (See section 5.6. More generally, the write()" and write once()" commands can be used to create any other files you may need to run your simulations, which refer to the same @atom and @bond types. (See section 5.5 for an example.)