Troubleshooting Tips

Unfortunately, emoltemplate sometimes creates files that ESPResSo will refuse to read.

This can be due to mistakes in the user's ET files. However it can be difficult to figure out where those mistakes are.

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

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, emoltemplate 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 Emoltemplate ET 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_flex.et and system.et .)

Suppose ESPResSo complains when you try to load the system.tcl file that emoltemplate generated.

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

Again, this is probably an error in your ET files. To help you find it, after you run emoltemplate, 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 ".ET" files where they first appear.


 # Atom-Types:
@/atom:SPCE/O             2       #"system.et", line 52
@/atom:SPCE/H             3       #"system.et", line 54

 # Bond-Types:
@/bond:SPCE/b_OH          0       #"spce.et", line 19
@/bond:SPCE/b_HH          1       #"spce.et", line 20

 # Atom-IDs:
$/atom:wat[0][0][0]/o     0       #"spce.et", line 5
$/atom:wat[0][0][0]/h1    1       #"spce.et", line 6
$/atom:wat[0][0][0]/h2    2       #"spce.et", line 7
$/atom:wat[0][0][1]/o     3       #"spce.et", line 5
$/atom:wat[0][0][1]/h1    4       #"spce.et", line 6
$/atom:wat[0][0][1]/h2    5       #"spce.et", line 7
:

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 ".ET" files near to the place where this variable first appears. Correct the mistake in that file and run emoltemplate.sh again.

(You can also find where this variable appears in your generated ESPResSo 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 ESPResSo 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 ".ET" 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.

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.

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

There's nothing wrong with this atom name ("HOH"), however you may be mistaking it for a 3-body "angle" bonded interaction of the same name ("HOH") which enforces the ~104-109 degree bond angle in water. 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 "$bond:HOH" somewhere in one of your ET files. To remove this ambiguity, bonds, angles, and dihedral names in emoltemplate are (by convention) preceeded by "b_", "a_", and "d_", respectively. So, in this case, one should probably name this interaction "$bond:a_HOH".

Good luck, and please let me know if you get stuck or have feedback.
December 6th 2016
Andrew Jewett