Implementing support for partial charge I/O in SDF

docs/releasehistory.rst

@@ -7,8 +7,50 @@ Releases follow the ``major.minor.micro`` scheme recommended by `PEP440 <https:/
 * ``minor`` increments add features but do not break API compatibility
 * ``micro`` increments represent bugfix releases or improvements in documentation
 
-0.6.1 - Bugfixes
-----------------
+0.7.0 - Current development
+---------------------------
+
+Behavior changed
+""""""""""""""""
+- `PR #508 <https://github.com/openforcefield/openforcefield/pull/508>`_:
+  In order to provide the same results for the same chemical species, regardless of input
+  conformation, fractional bond order calculation methods now default to ignore input conformers
+  and generate a new conformer of the molecule before running semiempirical calculations.
+  Users can override this behavior by specifying the keyword argument
+  ``use_conformers=molecule.conformers``
+- `PR #281 <https://github.com/openforcefield/openforcefield/pull/281>`_: Closes
+  `Issue #250 <https://github.com/openforcefield/openforcefield/issues/250>`_
+  by adding support for partial charge I/O in SDF. The partial charges are stored as a property in the
+  SDF molecule block under the tag ``<atom.dprop.PartialCharge>``.
+- `PR #281 <https://github.com/openforcefield/openforcefield/pull/281>`_: If an OFFMol's
+  ``partial_charges`` attribute is set to ``None`` (the default value), calling ``to_openeye`` will
+  now produce a OE molecule with partial charges set to ``nan``. This would previously produce an OE
+  molecule with partial charges of 0.0, which was a loss of information, since it wouldn't be clear
+  whether the original OFFMol's partial charges were REALLY all-zero as opposed to ``None``. OpenEye toolkit
+  wrapper methods such as ``from_smiles`` and ``from_file`` now produce OFFMols with
+  ``partial_charges = None`` when appropriate (previously these would produce OFFMols with
+  all-zero charges, for the same reasoning as above).
+- `PR #281 <https://github.com/openforcefield/openforcefield/pull/281>`_: ``Molecule.to_rdkit``
+  now sets partial charges on the RDAtom's ``PartialCharges`` property (this was previously set
+  on the ``partial_charges`` property). If the OFFMol's partial_charges attribute is None, this property
+  will not be defined on the RDAtoms.
+- `PR #281 <https://github.com/openforcefield/openforcefield/pull/281>`_:
+  Enforce the behavior during SDF I/O that a SDF may contain multiple MOLECULES, but that the OFF Toolkit
+  DOES NOT assume that it contains multiple CONFORMERS of the same molecule. This is an
+  important distinction, since otherwise there is ambiguity around whether properties of one
+  entry in a SDF are shared among several molecule blocks or not, or how to resolve conflicts if properties
+  are defined differently for several "conformers" of chemically-identical species (More info
+  `here <https://docs.eyesopen.com/toolkits/python/oechemtk/oemol.html#dude-where-s-my-sd-data>`_.
+  If the user requests the OFF
+  Toolkit to write a multi-conformer ``Molecule`` to SDF, only the first conformer will be written.
+  For more fine-grained control of writing properties, conformers, and partial charges, consider
+  using ``Molecule.to_rdkit`` or ``Molecule.to_openeye`` and using the functionality offered by
+  those packages.
+- `PR #281 <https://github.com/openforcefield/openforcefield/pull/281>`_: Due to different
+  constraints placed on the data types allowed by external toolkits, we make our best effort to
+  preserve ``offmol.properties`` when converting molecules to other packages, but users should be aware that
+  no guarantee of data integrity is made. The only data format for keys and values in the property dict that
+  we will try to support through a roundtrip to another toolkit's Molecule object is ``string``.
 
 API-breaking changes
 """"""""""""""""""""
@@ -202,7 +244,7 @@ Bugfixes
 Example added
 """""""""""""
 - `PR #472 <https://github.com/openforcefield/openforcefield/pull/472>`_: Adds an example notebook
-  `QCarchive_interface.ipynb <https://github.com/openforcefield/openforcefield/blob/master/examples/QCArchive_interface/QCarchive_interface.ipynb>`
+  `QCarchive_interface.ipynb <https://github.com/openforcefield/openforcefield/blob/master/examples/QCArchive_interface/QCarchive_interface.ipynb>`_
   which shows users how to instance the :py:class:`Molecule <openforcefield.topology.Molecule>` from
   a QCArchive entry level record and calculate the energy using RDKit through QCEngine.
 

openforcefield/data/molecules/ethanol_partial_charges.sdf

@@ -0,0 +1,26 @@
+*****
+ OpenBabel02041915453D
+
+  9  8  0  0  0  0  0  0  0  0999 V2000
+    1.0616   -0.2681   -0.0006 C   0  0  0  0  0  0  0  0  0  0  0  0
+    1.9101    0.9126   -0.4220 C   0  0  0  0  0  0  0  0  0  0  0  0
+    1.5170    1.3236   -1.7228 O   0  0  0  0  0  0  0  0  0  0  0  0
+    2.0787    2.0794   -1.9612 H   0  0  0  0  0  0  0  0  0  0  0  0
+    1.3393   -0.6108    1.0001 H   0  0  0  0  0  0  0  0  0  0  0  0
+   -0.0000   -0.0002   -0.0006 H   0  0  0  0  0  0  0  0  0  0  0  0
+    1.1801   -1.0990   -0.7040 H   0  0  0  0  0  0  0  0  0  0  0  0
+    2.9684    0.6361   -0.4446 H   0  0  0  0  0  0  0  0  0  0  0  0
+    1.7730    1.7499    0.2687 H   0  0  0  0  0  0  0  0  0  0  0  0
+  1  2  1  0  0  0  0
+  1  5  1  0  0  0  0
+  1  6  1  0  0  0  0
+  1  7  1  0  0  0  0
+  2  3  1  0  0  0  0
+  2  8  1  0  0  0  0
+  2  9  1  0  0  0  0
+  3  4  1  0  0  0  0
+M  END
+>  <atom.dprop.PartialCharge>  (1) 
+-0.40000000000000002 -0.29999999999999999 -0.20000000000000001 -0.10000000000000001 0.01 0.10000000000000001 0.20000000000000001 0.29999999999999999 0.40000000000000002
+
+$$$$

openforcefield/data/molecules/methane_multiconformer.sdf

@@ -0,0 +1,32 @@
+
+  -OEChem-02042019153D
+
+  5  4  0     0  0  0  0  0  0999 V2000
+    0.9999    1.0000    1.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
+    0.9433    2.0874    0.9141 H   0  0  0  0  0  0  0  0  0  0  0  0
+    1.6195    0.6029    0.1928 H   0  0  0  0  0  0  0  0  0  0  0  0
+   -0.0043    0.5764    0.9304 H   0  0  0  0  0  0  0  0  0  0  0  0
+    1.4416    0.7334    1.9627 H   0  0  0  0  0  0  0  0  0  0  0  0
+  1  2  1  0  0  0  0
+  1  3  1  0  0  0  0
+  1  4  1  0  0  0  0
+  1  5  1  0  0  0  0
+M  END
+
+$$$$
+
+  -OEChem-02042019153D
+
+  5  4  0     0  0  0  0  0  0999 V2000
+    2.2299    2.2300    2.2300 C   0  0  0  0  0  0  0  0  0  0  0  0
+    2.1733    3.3174    2.1441 H   0  0  0  0  0  0  0  0  0  0  0  0
+    2.8495    1.8329    1.4228 H   0  0  0  0  0  0  0  0  0  0  0  0
+    1.2257    1.8064    2.1604 H   0  0  0  0  0  0  0  0  0  0  0  0
+    2.6716    1.9634    3.1927 H   0  0  0  0  0  0  0  0  0  0  0  0
+  1  2  1  0  0  0  0
+  1  3  1  0  0  0  0
+  1  4  1  0  0  0  0
+  1  5  1  0  0  0  0
+M  END
+
+$$$$

openforcefield/data/molecules/methane_multiconformer_properties.sdf

@@ -0,0 +1,45 @@
+
+  -OEChem-02042019153D
+
+  5  4  0     0  0  0  0  0  0999 V2000
+    0.9999    1.0000    1.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
+    0.9433    2.0874    0.9141 H   0  0  0  0  0  0  0  0  0  0  0  0
+    1.6195    0.6029    0.1928 H   0  0  0  0  0  0  0  0  0  0  0  0
+   -0.0043    0.5764    0.9304 H   0  0  0  0  0  0  0  0  0  0  0  0
+    1.4416    0.7334    1.9627 H   0  0  0  0  0  0  0  0  0  0  0  0
+  1  2  1  0  0  0  0
+  1  3  1  0  0  0  0
+  1  4  1  0  0  0  0
+  1  5  1  0  0  0  0
+M  END
+> <test_property_key>
+test_property_value
+
+> <atom.dprop.PartialCharge>
+-0.108680 0.027170 0.027170 0.027170 0.027170
+
+$$$$
+
+  -OEChem-02042019153D
+
+  5  4  0     0  0  0  0  0  0999 V2000
+    2.2299    2.2300    2.2300 C   0  0  0  0  0  0  0  0  0  0  0  0
+    2.1733    3.3174    2.1441 H   0  0  0  0  0  0  0  0  0  0  0  0
+    2.8495    1.8329    1.4228 H   0  0  0  0  0  0  0  0  0  0  0  0
+    1.2257    1.8064    2.1604 H   0  0  0  0  0  0  0  0  0  0  0  0
+    2.6716    1.9634    3.1927 H   0  0  0  0  0  0  0  0  0  0  0  0
+  1  2  1  0  0  0  0
+  1  3  1  0  0  0  0
+  1  4  1  0  0  0  0
+  1  5  1  0  0  0  0
+M  END
+> <test_property_key>
+test_property_value2
+
+> <another_test_property_key>
+another_test_property_value
+
+> <atom.dprop.PartialCharge>
+0.027170 0.027170 0.027170 0.027170 -0.108680
+
+$$$$