Toolkit Wrappers and Registries

The toolkit wrappers provide a simple uniform API for accessing some functionality of cheminformatics toolkits. They are used internally by the OpenFF Toolkit to avoid re-implementing existing scientific algorithms, and can be used by users to specify exactly what software is used for any given section of code.

These toolkit wrappers are generally used through a ToolkitRegistry, which facilitates combining software with different capabilities and can be constructed with a list of toolkit wrappers ordered by precedence.

>>> from openff.toolkit import (
...     ToolkitRegistry,
...     OpenEyeToolkitWrapper,
...     RDKitToolkitWrapper,
...     AmberToolsToolkitWrapper,
... )
>>> toolkit_registry = ToolkitRegistry(
...     [
...         OpenEyeToolkitWrapper,
...         RDKitToolkitWrapper,
...         AmberToolsToolkitWrapper,
...     ]
... )

The toolkit wrappers’ functionality can then be accessed through the registry. The first toolkit in the list that provides a method with the given name will be used:

>>> from openff.toolkit import Molecule
>>> molecule = Molecule.from_smiles('Cc1ccccc1')
>>> smiles ='to_smiles', molecule)

For further details on how this search is performed and how it handles exceptions, see the API docs.

Many functions in the OpenFF Toolkit API include a toolkit_registry argument that can be used to specify the toolkit wrappers used by a call to that function. The value of this argument can be either a single toolkit wrapper instance, or an entire toolkit registry:

>>> smiles = molecule.to_smiles(toolkit_registry=RDKitToolkitWrapper())
>>> smiles = molecule.to_smiles(toolkit_registry=toolkit_registry)

For example, differences in to_smiles functionality between the OpenEye and RDKit can be explored by specifying the desired toolkit wrapper:

>>> molecule.to_smiles(toolkit_registry=RDKitToolkitWrapper())
>>> molecule.to_smiles(toolkit_registry=OpenEyeToolkitWrapper())

The default value of this argument is the GLOBAL_TOOLKIT_REGISTRY, which by default includes all the toolkits that OpenFF recommends for everyday use:

>>> from openff.toolkit import GLOBAL_TOOLKIT_REGISTRY
>>> len(GLOBAL_TOOLKIT_REGISTRY.registered_toolkits)

The toolkit_registry_manager context manager allows GLOBAL_TOOLKIT_REGISTRY to be changed temporarily:

>>> from openff.toolkit.utils import toolkit_registry_manager
>>> print(len(GLOBAL_TOOLKIT_REGISTRY.registered_toolkits))
>>> with toolkit_registry_manager(ToolkitRegistry([RDKitToolkitWrapper(), AmberToolsToolkitWrapper()])):
...     print(len(GLOBAL_TOOLKIT_REGISTRY.registered_toolkits))

For more information about modifying GLOBAL_TOOLKIT_REGISTRY, see the GLOBAL_TOOLKIT_REGISTRY API docs.


A registry and precedence list for ToolkitWrapper objects.


Base class for wrappers around external software toolkits.


OpenEye toolkit wrapper


RDKit toolkit wrapper


AmberTools toolkit wrapper


NAGL toolkit wrapper for applying partial charges with a GCN model.


Built-in ToolkitWrapper for very basic functionality.


The toolkit registry used by default when no registry or wrapper is specified.


A context manager that temporarily changes the GLOBAL_TOOLKIT_REGISTRY.