Add amber19-all, update documentation and tests

docs-source/usersguide/application/02_running_sims.rst

@@ -11,7 +11,7 @@ A First Example
 ***************
 
 Let’s begin with our first example of an OpenMM script. It loads a PDB file
-called :file:`input.pdb` that defines a biomolecular system, parameterizes it using the Amber14 force field and TIP3P-FB water
+called :file:`input.pdb` that defines a biomolecular system, parameterizes it using the Amber19 force field and TIP3P-FB water
 model, energy minimizes it, simulates it for 10,000 steps with a Langevin
 integrator, and saves a snapshot frame to a DCD file called :file:`output.dcd` every 1000 time
 steps.
@@ -25,7 +25,7 @@ steps.
         from sys import stdout
 
         pdb = PDBFile('input.pdb')
-        forcefield = ForceField('amber14-all.xml', 'amber14/tip3pfb.xml')
+        forcefield = ForceField('amber19-all.xml', 'amber14/tip3pfb.xml')
         system = forcefield.createSystem(pdb.topology, nonbondedMethod=PME,
                 nonbondedCutoff=1*nanometer, constraints=HBonds)
         integrator = LangevinMiddleIntegrator(300*kelvin, 1/picosecond, 0.004*picoseconds)
@@ -87,14 +87,14 @@ Make sure you include the single quotes around the file name.  OpenMM also can l
 files in the newer PDBx/mmCIF format: just change :class:`PDBFile` to :class:`PDBxFile`.
 ::
 
-    forcefield = ForceField('amber14-all.xml', 'amber14/tip3pfb.xml')
+    forcefield = ForceField('amber19-all.xml', 'amber14/tip3pfb.xml')
 
 This line specifies the force field to use for the simulation.  Force fields are
 defined by XML files.  OpenMM includes XML files defining lots of standard force fields (see Section :numref:`force-fields`).
 If you find you need to extend the repertoire of force fields available,
 you can find more information on how to create these XML files in Chapter :numref:`creating-force-fields`.
-In this case we load two of those files: :file:`amber14-all.xml`, which contains the
-Amber14 force field, and :file:`amber14/tip3pfb.xml`, which contains the TIP3P-FB water model.  The
+In this case we load two of those files: :file:`amber19-all.xml`, which contains the
+Amber19 force field, and :file:`amber14/tip3pfb.xml`, which contains the TIP3P-FB water model.  The
 :class:`ForceField` object is assigned to a variable called :code:`forcefield`\ .
 ::
 
@@ -456,11 +456,11 @@ the main force field, and possibly a second file to define the water model
 (either implicit or explicit).  For example:
 ::
 
-    forcefield = ForceField('amber14-all.xml', 'amber14/tip3pfb.xml')
+    forcefield = ForceField('amber19-all.xml', 'amber14/tip3pfb.xml')
 
-In some cases, one XML file may load several others.  For example, :file:`amber14-all.xml`
+In some cases, one XML file may load several others.  For example, :file:`amber19-all.xml`
 is really just a shortcut for loading several different files that together make up
-the AMBER14 force field.  If you need finer grained control over which parameters
+the Amber19 force field.  If you need finer grained control over which parameters
 are loaded, you can instead specify the component files individually.
 
 Be aware that some force fields and water models include "extra particles", such
@@ -472,23 +472,21 @@ must first add the extra particles to the :class:`Topology`.  See section
 The force fields described below are the ones that are bundled with OpenMM.
 Additional force fields are available online at https://github.com/openmm/openmmforcefields.
 
-Amber14
+Amber19
 -------
 
-The Amber14\ :cite:`Maier2015` force field is made up of various files that define
-parameters for proteins, DNA, RNA, lipids, water, and ions.
+The Amber19 force field is made up of various files that define parameters for
+proteins, DNA, RNA, water, and ions.
 
 .. tabularcolumns:: |l|L|
 
-===================================  ============================================
+===================================  ===========================================
 File                                 Parameters
-===================================  ============================================
-:file:`amber14/protein.ff14SB.xml`   Protein (recommended)
-:file:`amber14/protein.ff15ipq.xml`  Protein (alternative)
-:file:`amber14/DNA.OL15.xml`         DNA (recommended)
-:file:`amber14/DNA.bsc1.xml`         DNA (alternative)
+===================================  ===========================================
+:file:`amber19/protein.ff19SB.xml`   Protein\ :cite:`Tian2020` (recommended, includes residue-specific CMAP terms)
+:file:`amber19/protein.ff19ipq.xml`  Protein (alternative)
+:file:`amber19/DNA.OL21.xml`         DNA\ :cite:`Zgarbova2021`
 :file:`amber14/RNA.OL3.xml`          RNA
-:file:`amber14/lipid17.xml`          Lipid
 :file:`amber14/GLYCAM_06j-1.xml`     Carbohydrates and glycosylated proteins\ :cite:`Kirschner2007`
 :file:`amber14/tip3p.xml`            TIP3P water model\ :cite:`Jorgensen1983` and ions
 :file:`amber14/tip3pfb.xml`          TIP3P-FB water model\ :cite:`Wang2014` and ions
@@ -497,22 +495,22 @@ File                                 Parameters
 :file:`amber14/spce.xml`             SPC/E water model\ :cite:`Berendsen1987` and ions
 :code:`amber14/opc.xml`              OPC water model\ :cite:`Izadi2014` and ions
 :code:`amber14/opc3.xml`             OPC3 water model\ :cite:`Izadi2016` and ions
-===================================  ============================================
+===================================  ===========================================
 
-As a convenience, the file :file:`amber14-all.xml` can be used as a shortcut to include
-:file:`amber14/protein.ff14SB.xml`, :file:`amber14/DNA.OL15.xml`, :file:`amber14/RNA.OL3.xml`,
-and :file:`amber14/lipid17.xml`.  In most cases, you can simply include that file,
-plus one of the water models, such as :file:`amber14/tip3pfb.xml` for the TIP3P-FB
-water model and ions\ :cite:`Wang2014`:
+As a convenience, the file :file:`amber19-all.xml` can be used as a shortcut to
+include :file:`amber19/protein.ff19SB.xml`, :file:`amber19/DNA.OL21.xml`, and
+:file:`amber14/RNA.OL3.xml`.  In most cases, you can simply include that file,
+plus one of the water models, such as :file:`amber14/tip3pfb.xml` for the
+TIP3P-FB water model and ions\ :cite:`Wang2014`:
 ::
 
-    forcefield = ForceField('amber14-all.xml', 'amber14/tip3pfb.xml')
+    forcefield = ForceField('amber19-all.xml', 'amber14/tip3pfb.xml')
 
 GLYCAM is not included by default, since it is quite large.  If your system contains
 carbohydrates, include that file as well:
 ::
 
-    forcefield = ForceField('amber14-all.xml', 'amber14/tip3pfb.xml', 'amber14/GLYCAM_06j-1.xml')
+    forcefield = ForceField('amber19-all.xml', 'amber19/tip3pfb.xml', 'amber19/GLYCAM_06j-1.xml')
 
 Be aware that GLYCAM works somewhat differently from most force fields.  It uses
 its own nonstandard `naming convention <https://glycam.org/docs/forcefield/glycam-naming-2/index.html>`_
@@ -520,39 +518,63 @@ for carbohydrates, and requires your input file to follow it.  If any residues h
 names different from what it expects, GLYCAM will be unable to assign parameters
 to them.
 
+.. tip::
+   Files in the :code:`amber14` directory are used by the older Amber14 force
+   field described below, but those also listed in the table above are shared between
+   the Amber14 and Amber19 force fields and can be used with the files in the
+   :code:`amber19` directory.
+
 .. tip:: The solvent model XML files included under the :file:`amber14/` directory
          include both water *and* ions compatible with that water model, so if you
          mistakenly specify :file:`tip3p.xml` instead of :file:`amber14/tip3p.xml`,
          you run the risk of having :class:`ForceField` throw an exception since
          :file:`tip3p.xml` will be missing parameters for ions in your system.
 
-The converted parameter sets come from the `AmberTools 17 release <http://ambermd.org/AmberTools.php>`_
+.. warning::
+   The updated Lipid21 lipid force field is not yet supported in this port of
+   Amber19, as it makes use of Amber features not yet supported in
+   `ParmEd <https://github.com/parmed/parmed>`_.  Amber19 should be preferred
+   over Amber14 for simulations not requiring a lipid force field, but Amber14
+   should be used if the Lipid17 force field is desired.  Alternatively, to use
+   Amber19 with Lipid21, you can prepare your system with AmberTools_ before
+   loading it into OpenMM, as described in Section :numref:`using_amber_files`.
+
+The converted parameter sets come from the `AmberTools 24 release <http://ambermd.org/AmberTools.php>`_
 and were converted using the openmmforcefields_ package and `ParmEd <https://github.com/parmed/parmed>`_.
 
-Amber19
+Amber14
 -------
 
-Updated protein and DNA force fields from the
-`AmberTools 24 release <http://ambermd.org/AmberTools.php>`_ are also available.
+Similarly to the Amber19 force field, Amber14\ :cite:`Maier2015` is made up of
+various files that define parameters for proteins, DNA, RNA, lipids, water, and
+ions.  The file :file:`amber14-all.xml` can be used as a shortcut to include
+:file:`amber14/protein.ff14SB.xml`, :file:`amber14/DNA.OL15.xml`,
+:file:`amber14/RNA.OL3.xml`, and :file:`amber14/lipid17.xml`.  The same remarks
+for Amber19 regarding water, ions, and GLYCAM apply to Amber14.
 
 .. tabularcolumns:: |l|L|
 
-===================================  ===========================================
+===================================  ============================================
 File                                 Parameters
-===================================  ===========================================
-:file:`amber19/protein.ff19SB.xml`   Protein\ :cite:`Tian2020` (recommended, includes residue-specific CMAP terms)
-:file:`amber19/protein.ff19ipq.xml`  Protein (alternative)
-:file:`amber19/DNA.OL21.xml`         DNA\ :cite:`Zgarbova2021`
-===================================  ===========================================
-
-The OL3 RNA force field (:file:`amber14/RNA.OL3.xml`) and GLYCAM
-(:file:`amber14/GLYCAM_06j-1.xml`) described above are recommended for use with
-these updated protein and DNA force field files.  The :file:`amber14` directory
-also contains water models that can be used with these force fields.
+===================================  ============================================
+:file:`amber14/protein.ff14SB.xml`   Protein (recommended)
+:file:`amber14/protein.ff15ipq.xml`  Protein (alternative)
+:file:`amber14/DNA.OL15.xml`         DNA (recommended)
+:file:`amber14/DNA.bsc1.xml`         DNA (alternative)
+:file:`amber14/RNA.OL3.xml`          RNA
+:file:`amber14/lipid17.xml`          Lipid
+:file:`amber14/GLYCAM_06j-1.xml`     Carbohydrates and glycosylated proteins\ :cite:`Kirschner2007`
+:file:`amber14/tip3p.xml`            TIP3P water model\ :cite:`Jorgensen1983` and ions
+:file:`amber14/tip3pfb.xml`          TIP3P-FB water model\ :cite:`Wang2014` and ions
+:file:`amber14/tip4pew.xml`          TIP4P-Ew water model\ :cite:`Horn2004` and ions
+:file:`amber14/tip4pfb.xml`          TIP4P-FB water model\ :cite:`Wang2014` and ions
+:file:`amber14/spce.xml`             SPC/E water model\ :cite:`Berendsen1987` and ions
+:code:`amber14/opc.xml`              OPC water model\ :cite:`Izadi2014` and ions
+:code:`amber14/opc3.xml`             OPC3 water model\ :cite:`Izadi2016` and ions
+===================================  ============================================
 
-.. warning:: The updated :code:`Lipid21` lipid force field is not yet supported,
-             as it makes use of Amber features not yet supported in
-             `ParmEd <https://github.com/parmed/parmed>`_.
+The converted parameter sets come from the `AmberTools 17 release <http://ambermd.org/AmberTools.php>`_
+and were converted using the openmmforcefields_ package and `ParmEd <https://github.com/parmed/parmed>`_.
 
 CHARMM36
 --------
@@ -635,7 +657,7 @@ Born implicit solvent models from AMBER.  To use them, include an extra file whe
 creating the ForceField.  For example,
 ::
 
-    forcefield = ForceField('amber14-all.xml', 'implicit/gbn2.xml')
+    forcefield = ForceField('amber19-all.xml', 'implicit/gbn2.xml')
 
 .. tabularcolumns:: |l|L|
 
@@ -763,7 +785,7 @@ Water Models
 ------------
 
 The following files define popular water models.  They can be used with force fields
-that do not provide their own water models.  When using Amber14 or CHARMM36, use
+that do not provide their own water models.  When using Amber19, Amber14 or CHARMM36, use
 the water files included with those force fields instead, since they also include
 ion parameters.
 

examples/simulatePdb.py

@@ -4,7 +4,7 @@ from openmm.unit import *
 from sys import stdout
 
 pdb = PDBFile('input.pdb')
-forcefield = ForceField('amber14-all.xml', 'amber14/tip3pfb.xml')
+forcefield = ForceField('amber19-all.xml', 'amber14/tip3pfb.xml')
 system = forcefield.createSystem(pdb.topology, nonbondedMethod=PME, nonbondedCutoff=1*nanometer, constraints=HBonds)
 integrator = LangevinMiddleIntegrator(300*kelvin, 1/picosecond, 0.004*picoseconds)
 simulation = Simulation(pdb.topology, system, integrator)

wrappers/python/openmm/app/data/amber19-all.xml

+<ForceField>
+ <Include file="amber19/protein.ff19SB.xml"/>
+ <Include file="amber19/DNA.OL21.xml"/>
+ <Include file="amber14/RNA.OL3.xml"/>
+</ForceField>

wrappers/python/setup.py

@@ -153,7 +153,7 @@ def buildKeywordDictionary(major_version_num=MAJOR_VERSION_NUM,
                                           "openmm.app.internal.pdbx.writer"]
     setupKeywords["data_files"]        = []
     setupKeywords["package_data"]      = {"openmm" : [],
-                                          "openmm.app" : ['data/*.xml', 'data/*.pdb', 'data/amber14/*.xml', 'data/charmm36/*.xml', 'data/implicit/*.xml'],
+                                          "openmm.app" : ['data/*.xml', 'data/*.pdb', 'data/amber14/*.xml', 'data/amber19/*.xml', 'data/charmm36/*.xml', 'data/implicit/*.xml'],
                                           "openmm.app.internal" : []}
     setupKeywords["install_requires"]  = ["numpy"]
     setupKeywords["platforms"]         = ["Linux", "Mac OS X", "Windows"]

wrappers/python/tests/TestForceField.py

@@ -1336,7 +1336,7 @@ class TestForceField(unittest.TestCase):
     def test_Disulfides(self):
         """Test that various force fields handle disulfides correctly."""
         pdb = PDBFile('systems/bpti.pdb')
-        for ff in ['amber99sb.xml', 'amber14-all.xml', 'charmm36.xml', 'amberfb15.xml', 'amoeba2013.xml']:
+        for ff in ['amber99sb.xml', 'amber14-all.xml', 'amber19-all.xml', 'charmm36.xml', 'charmm36_2024.xml', 'amberfb15.xml', 'amoeba2013.xml']:
             forcefield = ForceField(ff)
             system = forcefield.createSystem(pdb.topology)