diff --git a/docs/conf.py b/docs/conf.py index 815863b1a..8d604e33b 100644 --- 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 index 240103b73..7ef7e1946 100644 --- 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 index 8b5852d48..780e16529 100644 --- 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 index 24a6a7f9b..2a0f6a72a 100644 --- 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 index 878513f81..f84758fd6 100644 --- 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 (