Recommendations for using moltemplate with force fields:

WARNING

Moltemplate and LAMMPS are both very general software tools. The particles in a LAMMPS simulation need not be atoms. Moltemplate assumes nothing about what these particles are.

The forces acting on an atom in a molecule depend on it's hybridization state, bond-partners, partial charge, as well as the electrostatic environment created by nearby atoms. Molecular modelling programs must be made aware of these details. Typical all-atom force fields distinguish between different types of carbon atoms (for example) depending upon where they appearing in different chemical groups. (And these carbon atoms are given different names, such as: c3a, c1o, c3', c4, etc...) Some molecule building software can automatically identify which of these (carbon) atom types is appropriate from the context in which it appears. Unfortunately moltemplate does not do this (as of 2017-3-15). Instead, the user must carefully choose each atom type manually. The validity of the simulation depends on choosing them correctly.

(Fortunately this needs only be done once for each type of molecule in the simulation, not redundantly for every atom in the simulation.)

Where to find atom type information in an .LT file:

The user must acquaint themselves with the various kinds of atoms defined in the force field they are using. (For example: c3a, c1o, c3', c4, ...)

Either way, these sections are located near the beginning of the .LT file.

Details: Even if an atom's type description is ambiguous, it is usually possible to make a reasonable choice by taking into account the mass, partial charge (if indicated), number-of-bonds (if indicated), as well as the kinds of atoms that this atom tends to be bonded to. (For the later, you will need to look at the "Data Bonds By Type" section in the LT file. For many force fields, one must also take into account the fact that atom type names used for looking up bonds (and angles, dihedrals, impropers) (which typically take the form "@atom:*,bNAME,a*,d*,i*") frequently differ from the original atom name (which typically take the form similar to "@atom:c4", or "@atom:hw") If so, then the "equivalence" (lookup) table that maps one to the other is located where the "replace" commands are located, near the beginning of the .LT file. (Note: Not all force-fields use "equivalence" tables.)

In addition, some force-field files contain templates or SMILES strings, or biotypes which can tell you how to choose which atom types are appropriate for your molecule. When this information is available, we try to put it at the end of the .LT file. (See the "compass_published.lt" file for an example.)

Fortunately moltemplate can sometimes detect your mistakes and and warn you. Here are some strategies to detect mistaken atom type assignments:

How to check your atom types:

Check for charge neutrality

Some force fields, such as OPLSAA, assign a different partial charge to each type of atom. When using these force fields, a mistake in choosing the correct atom type usually results in a system which is not charge neutral. Fortunately LAMMPS will complain if you attempt to simulate a such a system (while using long range electrostatics). For this reason, force fields like "oplsaa.lt" are comparatively safe to use in moltemplate.

Other force fields, like "gaff.lt" or "compass_published.lt" use other methods to assign charges to each atom. Extra care must be used with these force fields.

Use the "-checkff" argument

If the user fails to choose atom types correctly, then moltemplate will likely not be able to lookup all of the expected force-field parameters for atoms in your molecules. (This could happen if you attempted to place SP3 carbon at the center of a formaldehyde molecule (CH2O), for example.) This can be a useful way to check if you have assigned atom types incorrectly. Running moltemplate with the "-checkff" argument will force it to print an error message if there are undefined angle, and dihedral interactions anywhere in your system.

  moltemplate.sh -checkff system.lt

Failure to find such an interaction typically means 1) the user has probably made a mistake choosing one of their atom types, or (less commonly) 2) the force-field you are using cannot be used to simulate the molecule you are trying to build.

Note: This does not guarantee that your system is correct. Some errors (such as putting an SP2 carbon at the center of a methane molecule) may not be detected.

Explicit Water

Be careful to avoid using the "-checkff" argument if your simulation includes explicit water (such as "spce.lt"), or any other molecules which do not inherit their force field parameters from the force field you are using (such as "oplsaa.lt"). This will confuse moltemplate.

If you wish to use "-checkff", then edit the system.lt and comment out out any the lines where these water molecules appear. Later, after you have verified that you have chosen your atom types correctly, uncomment these lines and run moltemplate again without "-checkff".

How to remove unused atom types and force-field parameters:

By default, the simulation input files created by moltemplate are quite bloated because they include definitions for all of the atom types and force-field parameters contained in the force field(s) you are using (...even though you are almost certainly not using most of these atom types). This extra information is harmless, and, in my experience, it does not appear to slow down a LAMMPS simulation down noticeably. However it makes it difficult to visualize the system. (See below.) You can remove this extra information by invoking the following script without any arguments:
  cleanup_moltemplate.sh
This script is located in the same directory containing moltemplate.sh. Invoke this script (without any arguments) in the same directory where your "system.data", "system.in.settings", and "system.in.init" files (created by running moltemplate.sh) are located.

(Note: This script does not work well with .LT files that use many-body nonbonded forces, DREIDING H-bonds, or create their own custom text files which do not obey LAMMPS input/data file conventions. Most popular molecular force fields do not have these exotic features.)

Visualization:

Instructions for visualizing your system using VMD/topotools are included in the README_visualize.txt file, as well as the moltemplate manual . However, I recommend that you use the "cleanup_moltemplate.sh" script (discussed above) to eliminate unused atom types from your DATA file before visualizing it in VMD. (This means that you should probably not moltemplate.sh with the "-vmd" argument in this case. Instead run VMD manually after using cleanup_moltemplate.sh.)

Detailed Explanation: VMD only considers the first character in the atom type's name in the system.data file created by moltemplate. Given that moltemplate assigns each atom type to an integer (starting at 1) this means you cannot have more than 9 atom types. (You can increase this to 36 atom types, by manually editing the data file to add #comments to the right of each atom in the "Masses" section of the data file and providing each atom type with an alpha-numeric name.)

Modern force-fields have hundreds of atom types. When you attempt to visualize your system with VMD, only the first 9 atom types will be assigned unique colors. Since these are probably not the atom types you happen to be using, it's a good idea to reduce the number of atom types in your data file as much as possible before visualizing with VMD.