0.10.0 release prep (#1037)

* add/fix various docstrings and API references * Update 0.10.0 releasehistory and fix links * fix releasehistory link formatting * use stub cudatoolkit package so RTD stops crashing
openforcefield · Aug 2, 2021 · 1497eec · 1497eec
1 parent ee4fa10
commit 1497eec
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 38 deletions.
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -1,5 +1,7 @@
 name: openforcefield
 channels:
+    # Avoids crashing RTD machines by pulling an empty cudatoolkit pacakge
+    - jaimergp/label/unsupported-cudatoolkit-shim
     - conda-forge
     - defaults
 dependencies:

diff --git a/docs/releasehistory.md b/docs/releasehistory.md
@@ -6,58 +6,66 @@ Releases follow the `major.minor.micro` scheme recommended by [PEP440](https://w
 * `minor` increments add features but do not break API compatibility
 * `micro` increments represent bugfix releases or improvements in documentation
 
-## Current Development
+## 0.10.0 Improvements for force field fitting
 
 ### New features and behaviors changed
 
-- [PR #1027](https://github.com/openforcefield/openforcefield/pull/1027): Corrects interconversion of Molecule objects with OEMol objects by ensuring atom names are correctly accessible via the `OEAtomBase.GetName()` and `OEAtomBase.SetName()` methods, rather that the non-standard `OEAtomBase.GetData("name")` and `OEAtomBase.SetData("name", name)`.
+- [PR #1027](https://github.com/openforcefield/openforcefield/pull/1027): Corrects interconversion of Molecule objects 
+  with OEMol objects by ensuring atom names are correctly accessible via the `OEAtomBase.GetName()` and 
+  `OEAtomBase.SetName()` methods, rather that the non-standard `OEAtomBase.GetData("name")` and 
+  `OEAtomBase.SetData("name", name)`.
 - [PR #1007](https://github.com/openforcefield/openforcefield/pull/1007): Resolves
   [Issue #456](https://github.com/openforcefield/openff-toolkit/issues/456) by adding the 
   `normalize_partial_charges` (default is `True`) keyword argument to 
   [`Molecule.assign_partial_charges`](openff.toolkit.topology.Molecule.assign_partial_charges),
-  ['AmberToolsToolkitWrapper.assign_partial_charges'](openff.toolkit.utils.toolkits.AmberToolsToolkitWrapper.assign_partial_charges),  
-  ['OpenEyeToolkitWrapper.assign_partial_charges'](openff.toolkit.utils.toolkits.OpenEyeToolkitWrapper.assign_partial_charges), 
-  ['RDKitToolkitWrapper.assign_partial_charges'](openff.toolkit.utils.toolkits.RDKitToolkitWrapper.assign_partial_charges), and
-  ['BuiltInToolkitWrapper.assign_partial_charges'](openff.toolkit.utils.toolkits.BuiltInToolkitWrapper.assign_partial_charges).
+  [`AmberToolsToolkitWrapper.assign_partial_charges`](openff.toolkit.utils.toolkits.AmberToolsToolkitWrapper.assign_partial_charges),  
+  [`OpenEyeToolkitWrapper.assign_partial_charges`](openff.toolkit.utils.toolkits.OpenEyeToolkitWrapper.assign_partial_charges), 
+  [`RDKitToolkitWrapper.assign_partial_charges`](openff.toolkit.utils.toolkits.RDKitToolkitWrapper.assign_partial_charges), and
+  [`BuiltInToolkitWrapper.assign_partial_charges`](openff.toolkit.utils.toolkits.BuiltInToolkitWrapper.assign_partial_charges).
   This adds an offset to each atom's partial charge to ensure that their sum is equal to the net charge on the molecule
-  (to the limit of a python float's precision, generally less than 1e-6 electron charge). Note that, because this new 
-  behavior is **ON** default, it may slightly affect the energies of systems generated by running
-  `create_openmm_system`.
+  (to the limit of a python float's precision, generally less than 1e-6 electron charge). **Note that, because this new 
+  behavior is ON by default, it may slightly affect the partial charges and energies of systems generated by running
+  [`create_openmm_system`](openff.toolkit.typing.engines.smirnoff.ForceField.create_openmm_system).**
 - [PR #954](https://github.com/openforcefield/openforcefield/pull/954): Adds
   [`LibraryChargeType.from_molecule`](openff.toolkit.typing.engines.smirnoff.parameters.LibraryChargeHandler.LibraryChargeType.from_molecule)
-  which returns a `LibraryChargeType` object that will match the full molecule being parameterized, and assign
+  which returns a 
+  [`LibraryChargeType`](openff.toolkit.typing.engines.smirnoff.parameters.LibraryChargeHandler.LibraryChargeType)
+   object that will match the full molecule being parameterized, and assign
   it the same partial charges as are set on the input molecule.
 - [PR #923](https://github.com/openforcefield/openforcefield/pull/923): Adds
   [`Molecule.nth_degree_neighbors`](openff.toolkit.topology.Molecule.nth_degree_neighbors),
   [`Topology.nth_degree_neighbors`](openff.toolkit.topology.Topology.nth_degree_neighbors),
   [`TopologyMolecule.nth_degree_neighbors`](openff.toolkit.topology.TopologyMolecule.nth_degree_neighbors),
-  which returns pairs of atoms that are separated in a t molecule or topology ny _excactly_ N atoms.
+  which returns pairs of atoms that are separated in a molecule or topology by _exactly_ N atoms.
 - [PR #917](https://github.com/openforcefield/openforcefield/pull/917):
-  [`ForceField.create_openmm_system`] Ensures that the cutoff of the `NonbondedForce` is set to
+  [`ForceField.create_openmm_system`](openff.toolkit.typing.engines.smirnoff.forcefield.ForceField.create_openmm_system) 
+  now ensures that the cutoff of the `NonbondedForce` is set to
   the cutoff of the `vdWHandler` when it and a `Electrostatics` handler are present in the force field.
 - [PR #850](https://github.com/openforcefield/openforcefield/pull/850):
   [`OpenEyeToolkitWrapper.is_available`](openff.toolkit.utils.toolkits.OpenEyeToolkitWrapper.is_available)
   now returns `True` if _any_ OpenEye tools are licensed (and installed). This allows, i.e,
   use of functionality that requires `OEChem` without having an `OEOmega` license.
 - [PR #909](https://github.com/openforcefield/openforcefield/pull/909): Virtual site positions can now
   be computed directly in the toolkit. This functionality is accessed through
-  - :py:meth:`FrozenMolecule.compute_virtual_site_positions_from_conformer`
-  - :py:meth:`VirtualSite.compute_virtual_site_positions_from_conformer`
-  - :py:meth:`VirtualParticle.compute_position_from_conformer`
-  - :py:meth:`FrozenMolecule.compute_virtual_site_positions_from_atom_positions`
-  - :py:meth:`VirtualSite.compute_virtual_site_positions_from_atom_positions`
-  - :py:meth:`VirtualParticle.compute_position_from_atom_positions`
+  - [`FrozenMolecule.compute_virtual_site_positions_from_conformer`](openff.toolkit.topology.FrozenMolecule.compute_virtual_site_positions_from_conformer)
+  - [`VirtualSite.compute_positions_from_conformer`](openff.toolkit.topology.VirtualSite.compute_positions_from_conformer)
+  - [`VirtualParticle.compute_position_from_conformer`](openff.toolkit.topology.VirtualParticle.compute_position_from_conformer)
+  - [`FrozenMolecule.compute_virtual_site_positions_from_atom_positions`](openff.toolkit.topology.FrozenMolecule.compute_virtual_site_positions_from_atom_positions)
+  - [`VirtualSite.compute_positions_from_atom_positions`](openff.toolkit.topology.VirtualSite.compute_positions_from_atom_positions)
+  - [`VirtualParticle.compute_position_from_atom_positions`](openff.toolkit.topology.VirtualParticle.compute_position_from_atom_positions)
     where the positions can be computed from a stored conformer, or an input vector of atom positions.
   - Tests have been added (`TestMolecule.test_*_virtual_site_position`) to check for sane behavior. The tests do
     not directly compare OpenMM position equivalence, but offline tests show that they are equivalent.
-  - The helper method :py:meth:`VirtualSiteHandler._create_openff_virtual_sites` is now public,
-    which returns a modified topology with virtual sites added.
+  - The helper method 
+    [`VirtualSiteHandler.create_openff_virtual_sites`](openff.toolkit.typing.engines.smirnoff.parameters.VirtualSiteHandler.create_openff_virtual_sites) 
+    is now public, which returns a modified topology with virtual sites added.
   - Virtual sites now expose the parameters used to create its local frame via the read-only properties
-    - :py:meth:`VirtualSite.local_frame_weights`
-    - :py:meth:`VirtualSite.local_frame_positions`
+    - [`VirtualSite.local_frame_weights`](openff.toolkit.topology.VirtualSite.local_frame_weights)
+    - [`VirtualSite.local_frame_position`](openff.toolkit.topology.VirtualSite.local_frame_position)
   - Adding virtual sites via the `Molecule` API now have defaults for `sigma`, `epsilon`, and `charge_increment`
     set to 0 with appropriate units, rather than `None`
-- [PR #956](https://github.com/openforcefield/openforcefield/pull/956): Added `ForceField.get_partial_charges()`
+- [PR #956](https://github.com/openforcefield/openforcefield/pull/956): Added 
+  [`ForceField.get_partial_charges()`](openff.toolkit.typing.engines.smirnoff.forcefield.ForceField.get_partial_charges)
   to more easily compute the partial charges assigned by a force field for a molecule.
 - [PR  #1006](https://github.com/openforcefield/openff-toolkit/pull/1006):
   Two behavior changes in the SMILES output for `to_file()` and `to_file_obj()`:
@@ -75,14 +83,14 @@ Releases follow the `major.minor.micro` scheme recommended by [PEP440](https://w
 - [PR #1003](https://github.com/openforcefield/openforcefield/pull/1003): Fixes
   [Issue #1000](https://github.com/openforcefield/openff-toolkit/issues/1000), where a stereochemistry
   warning is sometimes erroneously emitted when loading a stereogenic molecule using
-  [Molecule.from_pdb_and_smiles](openff.toolkit.topology.Molecule.from_pdb_and_smiles)
+  [`Molecule.from_pdb_and_smiles`](openff.toolkit.topology.Molecule.from_pdb_and_smiles)
 - [PR #1002](https://github.com/openforcefield/openforcefield/pull/1002): Fixes a bug in which OFFXML files could
   inadvertently be loaded from subdirectories.
 - [PR #969](https://github.com/openforcefield/openforcefield/pull/969): Fixes a bug in which the cutoff distance
   of the `NonbondedForce` generated by
   [`ForceField.create_openmm_system`](openff.toolkit.typing.engines.smirnoff.forcefield.ForceField.create_openmm_system)
   was not set to the value specified by the vdW and Electrostatics handlers.
-- [PR #909](https://github.com/openforcefield/openforcefield/pull/909): It is now possible to create an
+- [PR #909](https://github.com/openforcefield/openforcefield/pull/909): Fixed several bugs related to creating an
   OpenMM system with virtual sites created via the `Molecule` virtual site API
 - [PR  #1006](https://github.com/openforcefield/openff-toolkit/pull/1006):
   Many small fixes to the toolkit wrapper I/O for better error
@@ -91,20 +99,16 @@ Releases follow the `major.minor.micro` scheme recommended by [PEP440](https://w
   toolkit wrappers. For the full list see
   [Issue #1005](https://github.com/openforcefield/openff-toolkit/issues/1005). Some
   of the more significant fixes are:
-  - RDKitToolkitWrapper's `from_file_obj()` now uses the same
+  - [`RDKitToolkitWrapper.from_file_obj()`](openff.toolkit.utils.toolkits.RDKitToolkitWrapper.from_file_obj) now uses the same
     structure normaliation as `from_file()`.
   - `from_smiles()` now raises an `openff.toolkit.utils.exceptions.SMILESParsingError` if
   the SMILES could not be parsed.
   - OEChem input and output files now raise an OSError if the file
   could not be opened.
   - All input file object readers now support file objects open in binary mode.
 
-### Examples added and updated
+### Examples added
 
-- [PR #1033](https://github.com/openforcefield/openff-toolkit/pull/1033): Incorporated findings from
-  [Issue #1019](https://github.com/openforcefield/openff-toolkit/issues/1005), addressing a problem with using ParmEd
-  to combine systems. Previously 1-4 interactions were scaled to 0 when ParmEd was used to combine OpenFF-derived 
-  ligand parameters with terms from AMBER prmtop files. (Thanks @callumjd!)
 - [PR #763](https://github.com/openforcefield/openff-toolkit/pull/763):
   Adds an introductory example showcasing the toolkit parameterizing a protein-ligand simulation.
 - [PR #955](https://github.com/openforcefield/openff-toolkit/pull/955): Refreshed the force field modification example
@@ -124,13 +128,8 @@ Releases follow the `major.minor.micro` scheme recommended by [PEP440](https://w
 - [PR #997](https://github.com/openforcefield/openff-toolkit/pull/997):
   Several XML snippets in `test_forcefield.py` that were scattered around inside of classes and
   functions are now moved to the module level.
-
-
-### Improved documentation and warnings
-
-- [PR #995](https://github.com/openforcefield/openff-toolkit/pull/995):
-  Add a ["cookbook"](users/molecule_cookbook) demonstrating every way to make a `Molecule` object.
-
+
+
 ## 0.9.2 Minor feature and bugfix release
 
 ### New features and behaviors changed

diff --git a/docs/typing.rst b/docs/typing.rst
@@ -63,6 +63,10 @@ For more information, see ``examples/forcefield_modification``.
     LibraryChargeHandler.LibraryChargeType
     GBSAHandler.GBSAType
     ChargeIncrementModelHandler.ChargeIncrementType
+    VirtualSiteHandler.VirtualSiteBondChargeType
+    VirtualSiteHandler.VirtualSiteMonovalentLonePairType
+    VirtualSiteHandler.VirtualSiteDivalentLonePairType
+    VirtualSiteHandler.VirtualSiteTrivalentLonePairType
 
 Parameter Handlers
 ~~~~~~~~~~~~~~~~~~
@@ -87,6 +91,7 @@ During ``System`` creation, each ``ParameterHandler`` registered to a ``ForceFie
     ToolkitAM1BCCHandler
     GBSAHandler
     ChargeIncrementModelHandler
+    VirtualSiteHandler
 
 Parameter I/O Handlers
 ~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/utils.rst b/docs/utils.rst
@@ -79,6 +79,7 @@ be explored by selecting which toolkit(s) are and are not registered.
     OpenEyeToolkitWrapper
     RDKitToolkitWrapper
     AmberToolsToolkitWrapper
+    BuiltInToolkitWrapper
 
 Serialization support
 ---------------------

diff --git a/openff/toolkit/topology/topology.py b/openff/toolkit/topology/topology.py
@@ -1320,6 +1320,26 @@ def amber_impropers(self):
         )
 
     def nth_degree_neighbors(self, n_degrees: int):
+        """
+        Return canonicalized pairs of atoms whose shortest separation is `exactly` n bonds.
+        Only pairs with increasing atom indices are returned.
+        Parameters
+        ----------
+        n: int
+            The number of bonds separating atoms in each pair
+        Returns
+        -------
+        neighbors: iterator of tuple of TopologyAtom
+            Tuples (len 2) of atom that are separated by ``n`` bonds.
+        Notes
+        -----
+        The criteria used here relies on minimum distances; when there are multiple valid
+        paths between atoms, such as atoms in rings, the shortest path is considered.
+        For example, two atoms in "meta" positions with respect to each other in a benzene
+        are separated by two paths, one length 2 bonds and the other length 4 bonds. This
+        function would consider them to be 2 apart and would not include them if ``n=4`` was
+        passed.
+        """
         return self._convert_to_topology_atom_tuples(
             self._reference_molecule.nth_degree_neighbors(n_degrees=n_degrees)
         )
@@ -1966,6 +1986,26 @@ def amber_impropers(self):
                 yield amber_improper
 
     def nth_degree_neighbors(self, n_degrees: int):
+        """
+        Return canonicalized pairs of atoms whose shortest separation is `exactly` n bonds.
+        Only pairs with increasing atom indices are returned.
+        Parameters
+        ----------
+        n: int
+            The number of bonds separating atoms in each pair
+        Returns
+        -------
+        neighbors: iterator of tuple of TopologyAtom
+            Tuples (len 2) of atom that are separated by ``n`` bonds.
+        Notes
+        -----
+        The criteria used here relies on minimum distances; when there are multiple valid
+        paths between atoms, such as atoms in rings, the shortest path is considered.
+        For example, two atoms in "meta" positions with respect to each other in a benzene
+        are separated by two paths, one length 2 bonds and the other length 4 bonds. This
+        function would consider them to be 2 apart and would not include them if ``n=4`` was
+        passed.
+        """
         for topology_molecule in self._topology_molecules:
             for pair in topology_molecule.nth_degree_neighbors(n_degrees=n_degrees):
                 yield pair