Troubleshooting Tips

Issues with force fields:

Moltemplate was not designed to build all-atom simulations. So when using it to build all-atom simulations, it is more difficult to use than other tools which are specialized for this task. It is dangerous to run moltemplate without reading the force field file and choosing your atom types carefully. Determining the correct atom types to use in a simulation can be difficult, and is a frequent source of error when preparing simulations using moltemplate. This topic is discussed further here.

More general issues with moltemplate:

Unfortunately moltemplate sometimes creates files that LAMMPS refuses to read. (Even when not using force fields.)

This can be due to mistakes in the user's LT files. However it can be difficult to figure out where that mistake is.

This is because variables are created automatically in moltemplate. (IE. counters beginning with $atom:, $bond, $angle,... or @atom, @bond, @angle, etc...)

This means the user must be very careful to spell atom names, bond names, or angle names consistently. (The spelling of these atoms, bonds, angles... does not matter, but you must be careful to spell them the same way every time you refer to them.) Otherwise, moltemplate thinks that you want to create a new atom, new bond, or new angles, and it does this quietly (without telling you). The problems this causes can be difficult to find.

Debugging Moltemplate LT files:

Error examples (using SPC/E water)

Suppose for example, you are trying to simulate a customized molecular system containing SPC/E water molecules. I will assume you borrowed the SPC/E water molecules from the example in the manual and have made minor modifications to them. (For reference, the relevant files in this example can be downloaded here: spce_simple.lt and system.lt .)

Suppose LAMMPS complains when you try to load the system.data and system.in files that moltemplate generated. (Frequently, LAMMPS might complain that "coeffs" are missing, or that it found an unexpected header in your data file.)

Search the "output_ttree/ttree_assignments.txt" file for misspelled variables

Again, this is probably an error in your LT files. To help you find it, after you run moltemplate, go to the "output_ttree/" directory and look for the file named "ttree_assignments.txt". This file contains a list of all of the counter variables in your system, as well as the numbers they are assigned to, and the location in your ".LT" files where they first appear.


 # Atom-Types:
@/atom:SPCE/O             1       #"spce_simple.lt", line 34
@/atom:SPCE/H             2       #"spce_simple.lt", line 35

 # Bond-Types:
@/bond:SPCE/OH            1       #"spce_simple.lt", line 61

 # Angle-Types:
@/angle:SPCE/HOH          1       #"spce_simple.lt", line 67

 # Atom-IDs:
$/atom:wat[0][0][0]/O     1       #"spce_simple.lt", line 26
$/atom:wat[0][0][0]/H1    2       #"spce_simple.lt", line 27
$/atom:wat[0][0][0]/H2    3       #"spce_simple.lt", line 28
$/atom:wat[0][0][1]/O     4       #"spce_simple.lt", line 26
$/atom:wat[0][0][1]/H1    5       #"spce_simple.lt", line 27
$/atom:wat[0][0][1]/H2    6       #"spce_simple.lt", line 28
:
 # Molecule-IDs:
$/mol:wat[0][0][0]        1       #"spce_simple.lt", line 26
$/mol:wat[0][0][1]        2       #"spce_simple.lt", line 26
$/mol:wat[0][0][2]        3       #"spce_simple.lt", line 26
:
 # Bond-IDs:
$/bond:wat[0][0][0]/OH1   1       #"spce_simple.lt", line 41
$/bond:wat[0][0][0]/OH2   2       #"spce_simple.lt", line 42
$/bond:wat[0][0][1]/OH1   3       #"spce_simple.lt", line 41
$/bond:wat[0][0][1]/OH2   4       #"spce_simple.lt", line 42
:
 # Angle-IDs:
$/angle:wat[0][0][0]/HOH  1       #"spce_simple.lt", line 48
$/angle:wat[0][0][1]/HOH  2       #"spce_simple.lt", line 48
$/angle:wat[0][0][2]/HOH  3       #"spce_simple.lt", line 48
:

Make sure that all of these variable-names seem reasonable. The variables above are correct. (Don't worry about the presence or absence of slash "/" characters at the beginning of the variable name. They are redundant and harmless.)

If you find a misspelled variable in the ttree_assignments.txt file (for example "@/atom:OOPS"), then it will be followed by comment indicating a location in one of your ".LT" files near to the place where this variable first appears. Correct the mistake in that file and run moltemplate.sh again.

(You can also find where this variable appears in your generated LAMMPS files by typing "grep atom:OOPS *.template" into the shell. There are many files ending with ".template" in the "output_ttree" directory. Each of them typically corresponds to a different section from the LAMMPS data file or input script.)

Examples of misspelled or incorrect variables:

1) $/atom:H1 or @/atom:H

In this example of a box of water, these two variables should probably be something like $/atom:wat[0][0][0]/H1, and @/atom:SPCE/H, to indicate that the atom belongs to the molecule named "wat[0][0][0]", and the atom type is defined in the "SPCE" (water) molecule.

The variables in the "ttree_assignments.txt" use full-name format. The full-name atom variables contain the atom name, in addition to the molecule to which the atom belongs. (For comparison, variables like "$atom:H1" or "@atom:H" which appear in your ".LT" files omit this information. For details, see the chapter titled "short-names vs. full-names" in the manual.)

If a variable in the ttree_assignments file lacks this information, then you probably accidentally put a "write("Data Atoms") {...}" statement somewhere in the global frame (in other words somewhere outside any molecule definition). This is not necessarily wrong, but it often is. (You can do that, but these atoms won't belong to any water molecules.) Be sure this is what you intended.

(Recent versions of moltemplate usually detect and report these kinds of mistakes.)

Here is another error example:

2) $/atom:wat[0][0][0]/H

The correct atom name would be $/atom:wat[0][0][0]/H1. (Because the atom-name/id is "H1", not "H". "H" is the atom type. "$atom" variables are unique atom names, not types, so this variable should be $atom:wat[0][0][0]/H1. The type should be @atom:SPCE/H. Again, the "wat[0][0][0]" just indicates which molecule the atom belongs to, and "SPCE" indicates the type of molecule it belongs to.

(Recent versions of moltemplate usually detect and report these kinds of mistakes.)

3) $/atom:wat[0][0][0]/HOH

There's nothing wrong with this atom name, except that "HOH" is also the name of one of the angle variables in the water molecule. If you see this (especially if it appears in the "Data Angles.template" file), then it probably means you made a typo and wrote "$atom:HOH" instead of "$angle:HOH" somewhere in one of your LT files.

(Recent versions of moltemplate usually detect and report these kinds of mistakes.)

Good luck, and please let me know if you get stuck or have feedback.
November 21 2016
Andrew Jewett