Introducing OPLSAA version 2023

• OPLSAA has been upgraded to the 2023 version with numerous changes.
• The OPLSAA examples (and the "loplsaa.lt" file used by LOPLS) have been updated as well.

Many thanks to Domenico Marson who wrote the program that converts BOSS files into moltemplate format!

To use the new "oplsaa.lt" file, you must change the @atom numbers in your .lt files

Many new atom types have introduced into OPLSAA since the previous (moltemplate) version (from 2008). The same atom types are present in the new version, but the @atom numbers assigned to them have changed (to make room for these new atom types). So you must update the @atom type numbers in your .lt files that use "oplsaa.lt".

Alternatively, you can continue using the old version of "oplsaa.lt" and "loplsaa.lt"

...without changing your @atom type numbers. But the .lt file names have changed. You must replace "import oplsaa.lt" with "import oplsaa2008.lt" everywhere it appears in your .lt files. (If you are using LOPLS, then also replace "import loplsaa.lt" with "import loplsaa2008.lt") To see how this is done, see the old examples.

WARNING: The new (2023 version) of OPLSAA is highly experimental.

Please understand the risks of using this new force field.

And please report any problems that you find with this new version.

Specific concerns with the 2023 vrsion:

• The improper interactions have not been tested carefully.
• The new version of OPLSAA gives you many additional choices for your dihedral, angle, and bond interactions. This makes it possible for you to improve your simulation accuracy, but it also requires more effort on your part. To see the list of choices, you must now run moltemplate with the "-report-duplicates bytype __" arguments. For example:

moltemplate.sh  system.lt  -report-duplicates bytype __

• If you see a file named "warning_duplicate_dihedrals.txt", "warning_duplicate_angles.txt", "warning_duplicate_bonds.txt", or "warning_duplicate_impropers.txt" after running moltemplate, then it is a good idea to read the first few warning messages
  in those files and modify your .lt files accordingly (for example, by adding a custom "Data Dihedrals" section). Several examples demonstrate how to do that, including butane.lt and benzoic_acid.lt

---

Remaining work to do:

• The list of improper interactions generated by the "oplsaa2lt.py" script is incorrect. (I'll worry about this later.) But this should not be an issue for users who just want to use the existing "oplsaa.lt" file included with this release. (That file was corrected by hand.)

-report-duplicates warns when multiple choices exist for the same bonded interactions

Added the "-report_duplicates" which warns the user when multiple bonds, angles, dihedrals, or impropers were automatically generated for the same set of atoms. This kind of ambiguity occurs frequently. This is especially important for the upcoming 2023 version of the OPLSAA force-field, which contains many duplicate or ambiguous bonded interaction definitions.

This feature makes it possible for users to find out when other possible bonded interactions exist. If so, they can override the default choice manually.

This feature is probably not very useful unless you are using the 2023 version of OPLSAA force field (which has not yet been released).

OPLSAA impropers were corrected

Summary

For OPLSAA, the strength of the improper forces was corrected.
Previously simulations prepared with the OPLSAA force field, had improper forces which were too weak by a factor of 2.
After this correction, those improper forces have been strengthened to the correct value.

The impact of this change is expected to be small. (See below.)

How this happened

All of this time, I have been relying on the TINKER version of the OPLS parameters. Apparently I have been misinterpreting the numbers in the improper section of that file.

Impact

In OPLSAA, improper forces are only used to impose planar constraints. The strength of these interactions was already quite strong. Strengthening them by a factor of 2 only serves to make these atoms a little bit more co-planar than they were before. So hopefully this correction should not have a large effect on the shape or flexibility of a molecule.

Most papers describing force fields (including OPLS) omit a detailed explanation of improper forces (and their symmetries).
I apologize for this mistake, but there may be additional errors in the way improper interactions are calculated. (See below.)

Remaining sources of error: Symmetry

In the current implementation of OPLSAA for moltemplate, multiple improper interactions are generated for atoms bonded in a Y-shape. (For example, ethylene contains 6 improper interactions, even though the Y-shape only appears twice. See here for details.) That's because the improper angle used to calculate the forces depends on the order of these atoms. The improper interaction is calculated 3 times using all 3 (=3!/2) different ways of ordering the 3 outer atoms.

It is not clear whether the original authors of the OPLS force fields intended all 3 of these (somewhat redundant) interactions to be calculated, or if the strength of these interactions should have been weakened (by 1/3) accordingly.

(If anyone knows the answer, please contact me. Currently moltemplate calculates all 3 and does not weaken these interactions.)

Contributors

I'd like to thank Domenico Marson who found the new parameters used by BOSS and explained them to me.
He has been working on getting the 2023 version of OPLSAA converted to moltemplate format. That version will hopefully be available in moltemplate shortly. (See #104 for details.)

-overlay-all behaves consistently on different OSs

• The option -overlay-all has been redefined to have a consistent behaviour on different OSs.
• Cosmetic changes to the cleaning of processed files: removing head tab spaces.

(Credit: Otello Roscioni)

atom creation is now optional

Change of philosophy: moltemplate now handles the case where atoms are not created. It requires the option -nocheck to render the input deck successfully. This way, moltemplate can create valid input decks for more heterogeneous tasks such as rerun, create_atoms etc.
I verified that the program produces a valid input deck for standard usage, with the "new MOLECULE" command invoked.

This change generalizes the kinds of files that moltemplate.sh can create.

Thanks to Otello Roscioni (hothello) for contributing this change!

fixed bug in cleanup_moltemplate.sh

Fixed bug #86 which prevented cleanup_moltemplate.sh from working whenever "moltemplate" was installed using pip or pip3.

(This bug did not effect the small number of users like me who install moltemplate by other means.)

All credit belongs to github user PhnRvTjN (Phani Ravi Teja Nunna) for solving the bug, and to github user yurivict for reporting the bug!

python3 is now default intepreter for .py executables

I replaced

#!/usr/bin/env python

with

#!/usr/bin/env python3

...everywhere.

This means users are no longer required to use "python" instead of "python3" when trying to run .py executable files directly from the shell (such as mol22lt.py, ltemplify.py, and genpoly_lt.py). This will enable most users to be able to invoke these python programs directly by their names, without having to predicate them with "python3".

Comment:

I'm sorry I didn't make this change earlier. I've been using anaconda python for a long time, and anaconda automatically adds a link from "python3" to "python", so that users can type "python" instead of "python3". I didn't realize that for most users, "python" isn't even defined.

better support for LT files not named "system.lt"

When the LT file is not named "system.lt":

• generated "run.in.EXAMPLE" files are renamed to avoid file name collisions (so that users can run moltemplate.sh on multiple LT files in the same directory)
• The "cleanup_moltemplate.sh" script can also handle files with names that do not begin with "system" (by including the "-base" argument).
• The "cleanup_moltemplate.sh" script no longer assumes that the python interpreter is named "python". (It could be named "python" or "python2".)

bugfixes for cleanup_moltemplate.sh and several OPLS water models

1. I fixed an edge-case bug causing "cleanup_moltemplate.sh" to fail without printing out an error message. This would happen whenever the user ran moltemplate.sh on a file not named "system.lt", and then attempted to run "cleanup_moltemplate.sh" afterwards. (This is a situation that "cleanup_moltemplate.sh" does not handle gracefully.) I did not fix this limitation. But now whenever a user does this, it prints out a detailed error message explaining how to get around this limitation.
2. I fixed some serious mistakes in the "spc_oplsaa.lt" and "tip3p_oplsaa.lt" files (for the SPC and TIP3P water models). Thanks to github user feifzhou for pointing them out!

updated GAFF2, amber2lt.py, and a few alkane examples

The @atom:hw and @atom:ow atom types in "gaff2.lt" now have been given epsilon and sigma parameters (of 0.0 and 1.0). These parameters are not correct, but at least users who don't need these atom types and want to use "gaff2.lt" will be able to do so (without LAMMPS complaining about missing pair_coeffs).

Similarly the amber2lt.py program will now supply default epsilon and sigma parameters (of 0.0 and 1.0) for atoms when this information is lacking in the FRCMOD or DAT file containing the force-field parameters (such as "gaff2.dat").

The amber2lt.py program accepts a slightly wider range of FRCMOD file formats.

Thanks to Karteek Bejegam and Jonathan Campeggio for their debugging help and suggestions!