Add NAGLToolkitWrapper to docs (#1795)

* Add NAGLToolkitWrapper to API docs * Write docstrings for NAGLToolkitWrapper * Update changelog --------- Co-authored-by: Jeff Wagner <[email protected]>
openforcefield · Feb 7, 2024 · 0375d5f · 0375d5f
1 parent b08243e
commit 0375d5f
Show file tree

Hide file tree

Showing 5 changed files with 49 additions and 0 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -92,6 +92,10 @@
         "https://docs.openforcefield.org/projects/units/en/stable/",
         None,
     ),
+    "openff.nagl": (
+        "https://docs.openforcefield.org/projects/nagl/en/stable/",
+        None,
+    ),
     "openff.docs": (
         "https://docs.openforcefield.org/en/latest/",
         None,

diff --git a/docs/releasehistory.md b/docs/releasehistory.md
@@ -18,6 +18,8 @@ Releases follow the `major.minor.micro` scheme recommended by [PEP440](https://w
 
 ### Improved documentation and warnings
 
+- [PR #1795](https://github.com/openforcefield/openff-toolkit/pull/1795): Add `NAGLToolkitWrapper` to API reference
+
 
 ## 0.15.2
 

diff --git a/docs/utils.rst b/docs/utils.rst
@@ -99,6 +99,7 @@ be explored by selecting which toolkit(s) are and are not registered.
     OpenEyeToolkitWrapper
     RDKitToolkitWrapper
     AmberToolsToolkitWrapper
+    NAGLToolkitWrapper
     BuiltInToolkitWrapper
 
 .. currentmodule:: openff.toolkit.utils.toolkit_registry

diff --git a/openff/toolkit/utils/nagl_wrapper.py b/openff/toolkit/utils/nagl_wrapper.py
@@ -17,6 +17,12 @@
 
 
 class NAGLToolkitWrapper(ToolkitWrapper):
+    """NAGL toolkit wrapper for applying partial charges with a GCN model.
+
+    :external+openff.nagl:doc:`index` computes partial charges directly from the
+    molecular graph and independent of conformer coordinates using a Graph
+    Convolutional Network."""
+
     _toolkit_name = "OpenFF NAGL"
     _toolkit_installation_instructions = (
         "See https://docs.openforcefield.org/projects/nagl/en/latest/installation.html"
@@ -58,6 +64,40 @@ def assign_partial_charges(
         normalize_partial_charges: bool = True,
         _cls: Optional[type["FrozenMolecule"]] = None,
     ):
+        """
+        Compute partial charges with NAGL and store in ``self.partial_charges``
+
+        .. warning :: This API is experimental and subject to change.
+
+        Parameters
+        ----------
+        molecule
+            Molecule for which partial charges are to be computed
+        partial_charge_method
+            The NAGL model to use. May be a path or the name of a model in a
+            directory from the ``openforcefield.nagl_model_path`` entry point.
+        use_conformers
+            This argument is ignored as NAGL does not generate or consider
+            coordinates during inference.
+        strict_n_conformers
+            This argument is ignored as NAGL does not generate or consider
+            coordinates during inference.
+        normalize_partial_charges : bool, default=True
+            Whether to offset partial charges so that they sum to the total
+            formal charge of the molecule. This is used to prevent accumulation
+            of rounding errors when the partial charge generation method has
+            low precision.
+        _cls : class
+            Molecule constructor
+
+        Raises
+        ------
+        ChargeMethodUnavailableError
+            if the requested charge method can not be handled by this toolkit
+
+        ChargeCalculationError
+            if the charge method is supported by this toolkit, but fails
+        """
         from openff.nagl import GNNModel
         from openff.nagl_models import validate_nagl_model_path
 

diff --git a/openff/toolkit/utils/toolkits.py b/openff/toolkit/utils/toolkits.py
@@ -39,6 +39,7 @@
     "OpenEyeToolkitWrapper",
     "RDKitToolkitWrapper",
     "AmberToolsToolkitWrapper",
+    "NAGLToolkitWrapper",
     "BuiltInToolkitWrapper",
     "ChargeMethodUnavailableError",
     "IncorrectNumConformersError",
@@ -86,6 +87,7 @@
     ToolkitUnavailableException,
     UndefinedStereochemistryError,
 )
+from openff.toolkit.utils.nagl_wrapper import NAGLToolkitWrapper
 from openff.toolkit.utils.openeye_wrapper import OpenEyeToolkitWrapper
 from openff.toolkit.utils.rdkit_wrapper import RDKitToolkitWrapper
 from openff.toolkit.utils.toolkit_registry import (