Merge branch 'master' into link-ff-repos

Author: j-wags

The-SMIRNOFF-force-field-format.md

@@ -190,16 +190,14 @@ Currently, only classical fixed point charge models are supported, but future ex
 
 ### `<LibraryCharges>`: Library charges for polymeric residues and special solvent models
 
-.. warning:: This functionality is not yet implemented and will appear in a future version of the toolkit. Please see `Issue 25 on the Open Force Field Toolkit issue tracker <https://github.com/openforcefield/openforcefield/issues/25>`_.
-
 A mechanism is provided for specifying library charges that can be applied to molecules or residues that match provided templates.
 Library charges are applied first, and atoms for which library charges are applied will be excluded from alternative charging schemes listed below.
 
 For example, to assign partial charges for a non-terminal ALA residue from the [AMBER ff14SB](http://doi.org/10.1021/acs.jctc.5b00255) parameter set:
 ```XML
 <LibraryCharges version="0.3">
-   <!-- match a non-terminal alanine residue with AMBER ff14SB partial charges-->
-   <LibraryCharge name="ALA" smirks="[NX3:1]([#1:2])([#6])[#6H1:3]([#1:4])([#6:5]([#1:6])([#1:7])[#1:8])[#6:9](=[#8:10])[#7]" charge1="-0.4157*elementary_charge" charge2="0.2719*elementary_charge" charge3="0.0337*elementary_charge" charge4="0.0823*elementary_charge" charge5="-0.1825*elementary_charge" charge6="0.0603*elementary_charge" charge7="0.0603*elementary_charge" charge8="0.0603*elementary_charge" charge9="0.5973*elementary_charge" charge10="-0.5679*elementary_charge">
+   <!-- match a non-terminal alanine residue with AMBER ff14SB partial charges -->
+   <LibraryCharge name="ALA" smirks="[NX3:1]([#1:2])([#6])[#6H1:3]([#1:4])([#6:5]([#1:6])([#1:7])[#1:8])[#6:9](=[#8:10])[#7]" charge1="-0.4157*elementary_charge" charge2="0.2719*elementary_charge" charge3="0.0337*elementary_charge" charge4="0.0823*elementary_charge" charge5="-0.1825*elementary_charge" charge6="0.0603*elementary_charge" charge7="0.0603*elementary_charge" charge8="0.0603*elementary_charge" charge9="0.5973*elementary_charge" charge10="-0.5679*elementary_charge"/>
    ...
 </LibraryCharges>
 ```
@@ -214,10 +212,17 @@ For example, to ensure water molecules are assigned partial charges for [TIP3P](
 ```XML
 <LibraryCharges version="0.3">
    <!-- TIP3P water oxygen with charge override -->
-   <LibraryCharge name="TIP3P" smirks="[#1:1]-[#8X2H2+0:2]-[#1:3]" charge1="+0.417*elementary_charge" charge2="-0.834*elementary_charge" charge3="+0.417*elementary_charge"/>
+   <LibraryCharge name="TIP3P" smirks="[#1:1]-[#8X2H2+0:2]-[#1:3]" charge1="0.417*elementary_charge" charge2="-0.834*elementary_charge" charge3="0.417*elementary_charge"/>
 </LibraryCharges>
 ```
 
+
+| LibraryCharges section tag version | Tag attributes and default values    | Required parameter attributes   | Optional parameter attributes |
+|------------------------------------|--------------------------------------|---------------------------------|-------------------------------|
+| 0.3                                |                                      | `smirks`, `charges` (indexed)   | `name`, `id`, `parent_id`     |
+
+
+
 ### `<ChargeIncrementModel>`: Small molecule and fragment charges
 
 .. warning:: This functionality is not yet implemented and will appear in a future version of the toolkit. This area of the SMIRNOFF spec is under further consideration. Please see `Issue 208 on the Open Force Field Toolkit issue tracker <https://github.com/openforcefield/openforcefield/issues/208>`_.

docs/releasehistory.rst

@@ -11,6 +11,49 @@ Releases follow the ``major.minor.micro`` scheme recommended by `PEP440 <https:/
 Current Development
 -------------------
 
+New features
+""""""""""""
+- `PR #433 <https://github.com/openforcefield/openforcefield/pull/433>`_: Closes
+  `Issue #25 <https://github.com/openforcefield/openforcefield/issues/25>`_ by adding
+  initial support for the
+  `LibraryCharges tag in the SMIRNOFF specification <https://open-forcefield-toolkit.readthedocs.io/en/latest/smirnoff.html#librarycharges-library-charges-for-polymeric-residues-and-special-solvent-models>`_
+  using
+  :py:class:`LibraryChargeHandler <openforcefield.typing.engines.smirnoff.parameters.LibraryChargeHandler>`.
+  For a molecule to have charges assigned using LibraryCharges, all of its atoms must be covered by
+  at least one LibraryCharge. If an atom is covered by multiple LibraryCharges, then the last
+  one read will be applied (per the hierarchy rules in the SMIRNOFF format).
+
+  This functionality is thus able to apply per-residue charges similar to those in traditional
+  protein force fields. At this time, there is no concept of "residues" or "fragments" during
+  parametrization, so it is not possible to assign charges to `some` atoms in a molecule using
+  LibraryCharges, but calculate charges for other atoms in the same molecule using a different
+  method. To assign charges to a protein, LibraryCharges SMARTS must be provided for
+  the standard residues, as well as for any capping groups and post-translational modifications
+  that are present.
+
+Behavior changed
+""""""""""""""""
+- `PR #433 <https://github.com/openforcefield/openforcefield/pull/433>`_: If a molecule
+  can not be assigned charges by any charge-assignment method, an
+  ``openforcefield.typing.engines.smirnoff.parameters.UnassignedMoleculeChargeException``
+  will be raised. Previously, creating a system without either ``ToolkitAM1BCCHandler`` or
+  the ``charge_from_molecules`` keyword argument to ``ForceField.create_openmm_system`` would
+  produce a system where the molecule has zero charge on all atoms. However, given that we
+  will soon be adding more options for charge assignment, it is important that
+  failures not be silent. Molecules with zero charge can still be produced by setting the
+  ``Molecule.partial_charges`` array to be all zeroes, and including the molecule in the
+  ``charge_from_molecules`` keyword argument to ``create_openmm_system``.
+- `PR #433 <https://github.com/openforcefield/openforcefield/pull/433>`_: Due to risks
+  introduced by permitting charge assignment using partially-overlapping ``LibraryCharge``s,
+  the toolkit will now raise a
+  ``openforcefield.typing.engines.smirnoff.parameters.NonIntegralMoleculeChargeException``
+  if the sum of partial charges on a molecule are found to be more than 0.001 elementary charge units
+  different than the molecule's formal charge. This exception can be overridden by providing
+  the ``allow_nonintegral_charges=True`` keyword argument to ``ForceField.create_openmm_system``.
+
+
+
+
 Tests added
 """""""""""
 - `PR #430 <https://github.com/openforcefield/openforcefield/pull/430>`_: Added test for 
@@ -21,14 +64,21 @@ Tests added
 Bugfixes
 """"""""
 - `PR #431 <https://github.com/openforcefield/openforcefield/pull/431>`_: Fixes an issue
-  where ``ToolkitWrapper``s would improperly search for functionality in the
+  where ``ToolkitWrapper`` objects would improperly search for functionality in the
   ``GLOBAL_TOOLKIT_REGISTRY``, even though a specific ``ToolkitRegistry`` was requested for an
   operation.
 - `PR #439 <https://github.com/openforcefield/openforcefield/pull/439>`_: Fixes
- `Issue #438 <https://github.com/openforcefield/openforcefield/issues/438>`_, by replacing
+  `Issue #438 <https://github.com/openforcefield/openforcefield/issues/438>`_, by replacing
   call to NetworkX ``Graph.node`` with call to ``Graph.nodes``, per
   `2.4 migration guide <https://networkx.github.io/documentation/stable/release/release_2.4.html>`_.
 
+Files modified
+""""""""""""""
+- `PR #433 <https://github.com/openforcefield/openforcefield/pull/433>`_: Updates
+  the previously-nonfunctional ``test_forcefields/tip3p.offxml`` to a functional state
+  by updating it to the SMIRNOFF
+  0.3 specification, and specifying atomic charges using the ``LibraryCharges`` tag.
+
 
 0.5.1 - Adding the parameter coverage example notebook
 ------------------------------------------------------

docs/typing.rst

@@ -62,6 +62,7 @@ For more information, see ``examples/forcefield_modification``.
     ProperTorsionHandler.ProperTorsionType
     ImproperTorsionHandler.ImproperTorsionType
     vdWHandler.vdWType
+    LibraryChargeHandler.LibraryChargeType
     GBSAHandler.GBSAType
 
 Parameter Handlers
@@ -83,6 +84,7 @@ During system creation, each ``ParameterHandler`` registered to a ``ForceField``
     ImproperTorsionHandler
     vdWHandler
     ElectrostaticsHandler
+    LibraryChargeHandler
     ToolkitAM1BCCHandler
     GBSAHandler
 

examples/check_dataset_parameter_coverage/check_parameter_coverage.ipynb

@@ -1,26 +1,21 @@
 <?xml version="1.0" encoding='ASCII'?>
-
-<SMIRNOFF version="0.2" aromaticity_model="OEAroModel_MDL">
-
+<SMIRNOFF version="0.3" aromaticity_model="OEAroModel_MDL">
   <!-- SMIRks Native Open Force Field (SMIRNOFF) file -->
-  <Date>2019-05-17</Date>
-  <Author>J. D. Chodera, MSKCC; A. Rizzi, Weill Cornell; C. C. Bannan, UC Irvine</Author>
-
+  <Date>2019-10-26</Date>
+  <Author>J. D. Chodera, MSKCC; A. Rizzi, Weill Cornell; J. Wagner, Open Force Field; C. C. Bannan, UC Irvine</Author>
   <!-- SMIRNOFF file implementing TIP3P water model. -->
-  <vdW potential="Lennard-Jones-12-6" combining_rules="Lorentz-Berthelot" scale12="0.0" scale13="0.0" scale14="0.5" scale15="1" sigma_unit="nanometers" epsilon_unit="kilojoules_per_mole" switch_width="1.0" switch_width_unit="angstroms" cutoff="9.0" cutoff_unit="angstroms" method="cutoff">
-    <!-- TIP3P water oxygen with charge override -->
-    <!-- WARNING: charges are not supported yet (see issue openforcefield#25), and they are currently here only for documentation -->
-    <Atom smirks="[#1]-[#8X2H2+0:1]-[#1]" id="n1" sigma="0.31507524065751241" epsilon="0.635968" charge="-0.834"/>
-    <!-- TIP3P water hydrogen with charge override -->
-    <!-- WARNING: charges are not supported yet (see issue openforcefield#25), and they are currently here only for documentation -->
-    <Atom smirks="[#1:1]-[#8X2H2+0]-[#1]" id="n2" sigma="1" epsilon="0" charge="0.417"/>
+  <!-- These values are taken from OpenMM's TIP3P implementation: https://github.com/openmm/openmm/blob/f9106ddb6a0d72c960c73b23ed0e07cd7190a80f/wrappers/python/simtk/openmm/app/data/tip3p.xml -->
+  <vdW version="0.3" potential="Lennard-Jones-12-6" combining_rules="Lorentz-Berthelot" scale12="0.0" scale13="0.0" scale14="0.5" scale15="1" switch_width="1.0 * angstroms" cutoff="9.0 * angstroms" method="cutoff">
+    <Atom smirks="[#1]-[#8X2H2+0:1]-[#1]" id="n1" sigma="0.31507524065751241 * nanometers" epsilon="0.635968 * kilojoules_per_mole" />
+    <Atom smirks="[#1:1]-[#8X2H2+0]-[#1]" id="n2" sigma="1 * nanometers" epsilon="0 * kilojoules_per_mole" />
   </vdW>
-
-  <Constraints distance_unit="angstroms">
+  <LibraryCharges version="0.3">
+    <LibraryCharge name="TIP3P" smirks="[#1:1]-[#8X2H2+0:2]-[#1:3]" charge1="0.417*elementary_charge" charge2="-0.834*elementary_charge" charge3="0.417*elementary_charge"/>
+  </LibraryCharges>
+  <Constraints version="0.3">
     <!-- constrain water O-H bond to equilibrium bond length (overrides earlier constraint) -->
-    <Constraint smirks="[#1:1]-[#8X2H2+0:2]-[#1]" id="c1" distance="0.9572"/>
+    <Constraint smirks="[#1:1]-[#8X2H2+0:2]-[#1]" id="c1" distance="0.9572 * angstrom"/>
     <!-- constrain water H...H, calculating equilibrium length from H-O-H equilibrium angle and H-O equilibrium bond lengths -->
-    <Constraint smirks="[#1:1]-[#8X2H2+0]-[#1:2]" id="c2" distance="1.5139006545247014"/>
+    <Constraint smirks="[#1:1]-[#8X2H2+0]-[#1:2]" id="c2" distance="1.5139006545247014 * angstrom"/>
   </Constraints>
-
 </SMIRNOFF>