simplified the procedure for using the OPLSAA force field. (Checking for alternate dihedrals and their associated warnings is now clearly marked as optional. Consequently the OPLSAA examples now run moltemplate.sh the ordinary way using "moltemplate.sh system.lt")

Author: jewettaij

examples/all_atom/force_field_OPLSAA/README.md

@@ -6,25 +6,9 @@ There is no guarantee that simulations prepared using moltemplate will reproduce
 
 
 
-### Suggestion: Make a local copy of the "oplsaa2023.lt" file
+-------------------------
 
-WARNING: The OPLSAA force field changes slightly over time.
-When it happens, it can cause the names of the
-@atoms, @bonds, @angles, and @dihedrals types to change.
-This could break backward compatibility,
-and cause moltemplate.sh to fail when reading your .lt files.
-So if you are using OPLSAA, it's a good idea to make a backup copy of the
-[oplsaa2023.lt file](../../../moltemplate/force_fields/oplsaa2023.lt)
-(located in the
-[moltemplate/force_fields/](../../../moltemplate/force_fields/) folder).
-Copy it to the folder with your other .lt files for the simulation you are working on.  (Moltemplate will look in the local folder first for all the .lt files that it needs, including "oplsaa2023.lt".)
-This will protect you from force-field parameter changes, and you
-will be able to continue using your existing atom and bonded type names safely.
-
-
-
-
-### Atomic charges
+## Atomic charges
 
 In most of the OPLSAA examples,
 the atomic charges are determined by their @atom types
@@ -35,7 +19,6 @@ LT files will be ignored.)*
 **These charges can be overridden.**
 
 
-
 ### Customizing atomic charges in OPLSAA molecules
 
 #### Background information
@@ -86,39 +69,68 @@ of the [spce.lt](waterSPCE+methane/moltemplate_files/spce.lt) file.
 
 
 
+-------------------------
 
+## Minor issue: Bloated lammps input scripts
 
+By default, LAMMPS input scripts prepared using moltemplate contain
+the entire contents of the OPLSAA force-field, even when simulating
+small systems with just a few atom types.
+This is harmless, but if you want to get rid of this extra information,
+follow the instructions in the "README_remove_irrelevant_info.sh" files.
 
-### Optional: Duplicate dihedrals, angles, and bonds
 
-Sometimes, even after you have specified the (OPLSAA-specific) atom types
-for the atoms in your molecule, there may be multiple possible choices
-of dihedral, angle, or bond interactions between those atoms
-available in OPLSAA force field (stored in the "oplsaa2023.lt" file).
-When that happens, moltemplate.sh will *attempt to make a reasonable guess*,
-chosing the original (oldest, most common) version of the interaction between
-those atom types.  However, you can override this choice:
+-------------------------
 
-- The new (2023) version of OPLSAA contains many additional choices for your dihedral, angle, and bond interactions.  This gives you an opportunity 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 might be 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 example .lt files demonstrate how to do that, including:
-- butane/moltemplate_files/butane.lt
-- benzene+benzoic_acid/moltemplate_files/benzoic_acid.lt
+## *OPTIONAL*
+## Customizing dihedrals, angles, and bonds
 
+The OPLSAA force field contains many alternative parameter choices for
+dihedral, angle, and bond interactions.
+It's not always possible to for determine the optimal choice of dihedral angle
+parameters from the @atom types alone.  By default, moltemplate hides this
+issue, and will *attempt to make a reasonable guess*, chosing the most generic
+version of the interaction between those atom types.
+*(The same is true with most other molecule builder programs.)*
 
+***Most of the time, this is fine.***
+At the beginning when you are trying to get your simulation to run,
+don't worry about choosing the optimal dihedral, angle, or bond parameters.
+The default choice is often good enough.
 
-### Minor issue: Improper angles
+*Eventually, if you want to improve the accuracy of your simulation somewhat,
+then you can detect these ambiguous duplicate dihedrals and angles.
+Then you can override the default choice by following the (somewhat laborious)
+procedure below.*
 
-The style of improper interaction used by OPLS force fields depends on an angle which depends on the order of the atoms surrounding the central atom. When multiple atoms have the same type, this creates ambiguity in atom order. Since there is no guarantee that moltemplate will choose the same atom order as other molecule builders (such as VMD), this can lead to small unavoidable discrepancies in energies and forces computed by LAMMPS and NAMD.  But their effect should be neglegible.
-*(Please let us know if this is not the case.)*
-
-
-
-### Minor issue: Bloated lammps input scripts
-
-By default, LAMMPS input scripts prepared using moltemplate contain the entire contents of the OPLS force-field, even when simulating small systems with just a few atom types.
+Again, moltemplate hides this issue by default.
+To be informed when moltemplate detects multiple ambiguous dihedrals
+(or angles), you must run moltemplate.sh with the optional
+`-report-duplicates bytype __` arguments.
+For example:
+```
+moltemplate.sh  system.lt  -report-duplicates bytype __
+```
+- If you see a file named "warning_duplicate_dihedrals.txt" after running
+moltemplate.sh, then moltemplate found multiple plausible
+dihedral interactions between the same set of atoms in your molecules.
+If you see this file, then read the first few warning messages in that file.
+*(This file is typically long and redundant, since there are typically many
+copies of the same molecules in a simulation.)*
+Then modify your .lt files accordingly.
+*(This requires adding a custom "Data Dihedrals" section where you specify
+the version of the @dihedral that you want to use for those atoms.
+Several example .lt files demonstrate how to do that in detail, including
+[butane.lt](./butane/moltemplate_files/butane.lt) and
+[benzoic_acid_optimizations.lt](./benzene+benzoic_acid/moltemplate_files/optimized_version_using_custom_dihedrals/benzoic_acid_optimizations.lt).)*
+- Each time you add a line to your "Data Dihedrals" section, the corresponding
+warning(s) in the "warning_duplicate_dihedrals.txt" file will be removed.
+So read the first warning, add a corresponding line to the "Data Dihedrals"
+section to address that warning, and run moltemplate.sh again.  Repeat this
+until the "warning_duplicate_dihedrals.txt" file is no longer being generated.
+- If you see a file named "warning_duplicate_angles.txt"
+or "warning_duplicate_bonds.txt", then follow the same procedure.
+Read those warning messages and add a custom "Data Angles" or "Data Bonds"
+section to your .lt files to override the default choice of
+@angle or @bond type.
 
-This is harmless, but if you want to get rid of this extra information, follow the instructions in the "README_remove_irrelevant_info.sh" files.

examples/all_atom/force_field_OPLSAA/alkane_chain_single/README_setup.sh

@@ -4,19 +4,22 @@ cd moltemplate_files
 
   # run moltemplate
 
-  # This was the original (simple) way to run moltemplate:
-  # moltemplate.sh  system.lt  <-- COMMENTING OUT
-  # Instead, this is the recommended way to run moltemplate with OPLSAA:
+  moltemplate.sh  system.lt
 
-  moltemplate.sh  system.lt  -report-duplicates bytype __
-
-  # (The optional "-report-duplicates bytype __" arguments check to make
-  #  sure that there was no ambiguity in the dihedrals that were generated.
-  #  This is an issue with OPLSAA.  If there was, then moltemplate will create
-  #  a file named "warning_duplicate_dihedrals.txt".)
+  # --- OPTIONAL: ---
+  # You can also check for missing angle,dihedral params this way:
+  #    moltemplate.sh -checkff system.lt 
   #
-  # (Note: You can also check for missing angle,dihedral params this way:)
-  # moltemplate.sh -checkff system.lt 
+  # You can also check for alternative possible OPLSAA parameters this way:
+  #    moltemplate.sh  system.lt  -report-duplicates bytype __
+  # This will check to make sure that there was no ambiguity in the OPLSAA
+  # force-field parameters.  Unfortunately, if you do that, moltemplate
+  # will create a "warning_duplicate_dihedrals.txt" which often contains
+  # more spurious warnings than you could possibly hope to read.  Most
+  # OPLSAA molecule builder programs do not warn you about these ambiguities.
+  # Moltemplate does warn you, but in my experience, it's often not worth the
+  # trouble to worry about them.  Just use: "moltemplate.sh system.lt"
+  # --- OPTIONAL: ---
 
 
   # Moltemplate generates various files with names ending in *.in* and *.data.

examples/all_atom/force_field_OPLSAA/alkane_chain_single/run.in.min

@@ -1,7 +1,7 @@
 # PREREQUISITES:
 #
-#     You must use moltemplate.sh to create 3 files:
-#        system.data  system.in.init  system.in.settings
+#     You must use moltemplate.sh to create 4 files:
+#        system.data  system.in.init  system.in.settings  system.in.charges
 #
 # ------------------------------- Initialization Section --------------------
 

examples/all_atom/force_field_OPLSAA/alkane_chain_single/run.in.nvt

@@ -1,7 +1,7 @@
 # PREREQUISITES:
 #
-#   1) You must use moltemplate.sh to create 3 files:
-#        system.data  system.in.init  system.in.settings
+#   1) You must use moltemplate.sh to create 4 files:
+#        system.data  system.in.init  system.in.settings  system.in.charges
 #      (Follow the instructions in README_setup.sh, 
 #       or run the file as a script using ./README_setup.sh)
 #   2) You must minimize the system beforehand by using "run.in.min".

examples/all_atom/force_field_OPLSAA/benzene+benzoic_acid/README_setup.sh

@@ -4,19 +4,23 @@ cd moltemplate_files
 
   # run moltemplate
 
-  # This was the original (simple) way to run moltemplate:
-  # moltemplate.sh  system.lt  <-- COMMENTING OUT
-  # Instead, this is the recommended way to run moltemplate with OPLSAA:
+  moltemplate.sh  system.lt
 
-  moltemplate.sh  system.lt  -report-duplicates bytype __
-
-  # (The optional "-report-duplicates bytype __" arguments check to make
-  #  sure that there was no ambiguity in the dihedrals that were generated.
-  #  This is an issue with OPLSAA.  If there was, then moltemplate will create
-  #  a file named "warning_duplicate_dihedrals.txt".)
-  #
-  # (Note: You can also check for missing angle,dihedral params this way:)
+  # --- OPTIONAL: ---
+  # You can also check for missing angle,dihedral params this way:
   # moltemplate.sh -checkff system.lt 
+  #
+  # You can also check for alternative possible OPLSAA parameters this way:
+  # moltemplate.sh  system.lt  -report-duplicates bytype __
+  #
+  # The optional "-report-duplicates bytype __" arguments check to make
+  # sure that there was no ambiguity in the chosen dihedrals parameters
+  # Often moltemplate.sh will create a "warning_duplicate_dihedrals.txt"
+  # file containing more warnings than you could possibly hope to read.  Most
+  # OPLSAA molecule builder programs do not warn you about these ambiguities.
+  # Moltemplate does warn you, but in my experience, it's not worth the
+  # trouble to worry about them.  Just use: "moltemplate.sh system.lt"
+  # --- OPTIONAL: ---
 
 
   # Moltemplate generates various files with names ending in *.in* and *.data.

examples/all_atom/force_field_OPLSAA/benzene+benzoic_acid/moltemplate_files/benzene.lt

@@ -6,27 +6,27 @@ import "oplsaa2023.lt"
 #   @atom:146    "H - HA | Benzene H"
 # The "oplsaa2023.lt" file is located at:
 # https://github.com/jewettaij/moltemplate/tree/master/moltemplate/force_fields/
-# If you want to customize oplsaa2023.lt, download it and copy it to this folder.
+# If you want to customize oplsaa2023.lt, download it and copy it to this folder
 
 
 
 Benzene inherits OPLSAA {
 
-  # atom-id mol-id atom-type  charge  X     Y      Z         #  comment
+  # atom-id mol-id atom-type  charge  X     Y      Z
 
   write("Data Atoms") {
-    $atom:c1  $mol  @atom:145  0.00 -0.739  1.189 -0.00733   # @atom:145 --> C - CA | Benzene C
-    $atom:c2  $mol  @atom:145  0.00  0.614  1.208  0.35167   # @atom:145 --> C - CA | Benzene C
-    $atom:c3  $mol  @atom:145  0.00  1.353  0.019  0.35867   # @atom:145 --> C - CA | Benzene C
-    $atom:c4  $mol  @atom:145  0.00  0.739 -1.189  0.00667   # @atom:145 --> C - CA | Benzene C
-    $atom:c5  $mol  @atom:145  0.00 -0.614 -1.208 -0.35133   # @atom:145 --> C - CA | Benzene C
-    $atom:c6  $mol  @atom:145  0.00 -1.353 -0.019 -0.35833   # @atom:145 --> C - CA | Benzene C
-    $atom:h1  $mol  @atom:146  0.00 -1.309  2.106 -0.01233   # @atom:146 --> H - HA | Benzene H
-    $atom:h2  $mol  @atom:146  0.00  1.088  2.14   0.62267   # @atom:146 --> H - HA | Benzene H
-    $atom:h3  $mol  @atom:146  0.00  2.397  0.034  0.63467   # @atom:146 --> H - HA | Benzene H
-    $atom:h4  $mol  @atom:146  0.00  1.309 -2.106  0.01267   # @atom:146 --> H - HA | Benzene H
-    $atom:h5  $mol  @atom:146  0.00 -1.088 -2.14  -0.62233   # @atom:146 --> H - HA | Benzene H
-    $atom:h6  $mol  @atom:146  0.00 -2.397 -0.034 -0.63533   # @atom:146 --> H - HA | Benzene H
+    $atom:c1  $mol  @atom:145  0.00 -0.739  1.189 -0.00733
+    $atom:c2  $mol  @atom:145  0.00  0.614  1.208  0.35167
+    $atom:c3  $mol  @atom:145  0.00  1.353  0.019  0.35867
+    $atom:c4  $mol  @atom:145  0.00  0.739 -1.189  0.00667
+    $atom:c5  $mol  @atom:145  0.00 -0.614 -1.208 -0.35133
+    $atom:c6  $mol  @atom:145  0.00 -1.353 -0.019 -0.35833
+    $atom:h1  $mol  @atom:146  0.00 -1.309  2.106 -0.01233
+    $atom:h2  $mol  @atom:146  0.00  1.088  2.14   0.62267
+    $atom:h3  $mol  @atom:146  0.00  2.397  0.034  0.63467
+    $atom:h4  $mol  @atom:146  0.00  1.309 -2.106  0.01267
+    $atom:h5  $mol  @atom:146  0.00 -1.088 -2.14  -0.62233
+    $atom:h6  $mol  @atom:146  0.00 -2.397 -0.034 -0.63533
   }
 
   # Note: You don't have to specify the charge in this example because we are