Moltemplate

*(I will eventually remove the original "oplsaa.lt" file because the changing atom type numbers in that file are causing difficulties for moltemplate users and maintainers.)*

In addition to changing the name of that file, I also changed all of the references to that file name, which appear in many places throughout the examples.

Unfortunately this means that the old version of moltemplate which is currently on pypi *(which does not include "oplsaa2024.lt")* needs to be updated in order for all of these examples to work.

This release updates the name of this file so that the examples will work again for pip and conda users.

- Corrected a bug in OPLSAA ("oplsaa.lt") which incorrectly named several angle and dihedral types (angle:NB_OA_CR, angle:NB_OA_CR, dihedral:H~_N~_CT_CT) to something else. Those angle and dihedral type names have been restored. This bug was introduced by the the previous release (v2.22.1) one day earlier. Hopefully, very few users (if any) will be affected in this short time interval.
- The "oplsaa2lt.py" conversion script has been debugged and cleaned up.

*Again, I recommend that all OPLSAA users copy the "oplsaa.lt" file (in the "moltemplate/force_fields/" folder) to their local directory containing the other .lt files they are working on. That will protect users from updates to OPLSAA that can break backwards compatibility. That way users can continue using the same atom, angle, and dihedral type names that they were using before.*

Better default choices for OPLSAA dihedrals, angles, or bonds when multiple such choices exist. Moltemplate will choose a reasonable default choice automatically. Users still have the option to override these default choices.

NOTE: Unfortunately, a few OPLSAA atom types have changed, breaking backward compatibility! *Very few atom types were changed. But for future safetly, I suggest copying the oplsaa.lt file you are using into your local folder with your other .lt files to prevent these kinds of disruptions in the future. Moltemplate.sh will look in your local folder first for all the .lt files that it needs, including oplsaa.lt. The OPLSAA documentation was updated with these suggestions.*

*UPDATE(2025-3-19): To prevent backwards-compatibility-breaking changes in the future, the "oplsaa.lt" file has been renamed to "oplsaa2024.lt" (commit f671547). If you use "import oplsaa2024.lt", then the atom type names should remain stable. (This assumes nobody finds any serious issues that completely break the "oplsaa2024.lt" file. Otherwise, future updates will go in different oplsaaXXXX.lt files.)*

- Fixed a bug in moltemplate.sh. *(The bug was introduced when releasing OPLSAA(2023) in version 2.21.1)*
- OPLSAA 2023 water models were tested and are working.
- Numerous examples were debugged and updated.
- File names and atom type names have changed *(for water models and the alkane examples)*.

- I corrected several serious mistakes in the improper interactions defined in the oplsaa.lt file (2023 version). If you updated your version of moltemplate to 2.21.1, please update it again. The version of oplsaa.lt from version 2.21.1 will not work.
- I am now confident that the improper interactions in the latest oplsaa.lt file are correct! *(I verified the new version of oplsaa.lt is correct by confirming that the number and magnitude of the impropers generated by moltemplate (for ethylene and benzioc-acid) agree with impropers generated by the ligpargen server for these molecules. There is one exception: allenes. The original BOSS files have non-sensical improper interactions for allenes. So the oplsaa2lt.py conversion script comments those out.)*
- The conversion script (oplsaa2lt.py) is also working, so there is no longer a need to hand-edit the generated oplsaa.lt file afterwards.

The improper interactions were the only remaining part of the OPLSAA.lt that I still had serious doubts about.
***Now that they seem to be working, I'm happy to recommend that people start using the new (2023) version of the "oplsaa.lt" file.***
*(I trust it more than the (2008) version that moltemplate users have been relying on for years. That's because the 2023 version is based on a direct conversion from the original BOSS files.)*

- 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**](https://github.com/jewettaij/moltemplate/tree/master/examples/all_atom/legacy_force_field_examples/force_field_OPLSAA_2008/).*


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**](https://github.com/jewettaij/moltemplate/blob/master/examples/all_atom/force_field_OPLSAA/butane/moltemplate_files/butane.lt) and [**benzoic_acid.lt**](https://github.com/jewettaij/moltemplate/blob/master/examples/all_atom/force_field_OPLSAA/benzene%2Bbenzoic_acid/moltemplate_files/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.)*