Utilities

Toolkit wrappers

The toolkit wrappers provide a simple uniform API for accessing minimal functionality of cheminformatics toolkits.

These toolkit wrappers are generally used through a ToolkitRegistry, which can be constructed with a desired precedence of toolkits:

>>> from openff.toolkit.utils.toolkits import ToolkitRegistry, OpenEyeToolkitWrapper, RDKitToolkitWrapper, AmberToolsToolkitWrapper
>>> toolkit_registry = ToolkitRegistry()
>>> toolkit_precedence = [OpenEyeToolkitWrapper, RDKitToolkitWrapper, AmberToolsToolkitWrapper]
>>> [ toolkit_registry.register_toolkit(toolkit) for toolkit in toolkit_precedence if toolkit.is_available() ]
[None, None, None]

The toolkit wrappers can then be accessed through the registry:

>>> from openff.toolkit.utils.toolkits import GLOBAL_TOOLKIT_REGISTRY as toolkit_registry
>>> from openff.toolkit import Molecule
>>> molecule = Molecule.from_smiles('Cc1ccccc1')
>>> smiles = toolkit_registry.call('to_smiles', molecule)

The order of toolkits, as specified in toolkit_precedence above, determines the order in which the called method is resolved, i.e. if the toolkit with highest precedence has a to_smiles method, that is the toolkit that will be called. If the toolkit with highest precedence does not have such a method, it is attempted with other toolkits until one is found. By default, if a toolkit with an appropriately-named method raises an exception of any type, then iteration over the registered toolkits stops and that exception is raised. To continue iteration if specific exceptions are encountered, customize this behavior using the optional raise_exception_types keyword argument to ToolkitRegistry.call. If no registered toolkits have the method, a ValueError is raised, containing a message listing the registered toolkits and exceptions (if any) that were ignored.

Alternatively, the global toolkit registry (which will attempt to register any available toolkits) can be used:

>>> from openff.toolkit.utils.toolkits import GLOBAL_TOOLKIT_REGISTRY as toolkit_registry
>>> len(toolkit_registry.registered_toolkits)
4

Individual toolkits can be registered or deregistered to control the backend that ToolkitRegistry calls resolve to. This can be useful for debugging and exploring subtley different behavior between toolkit wrappers.

To temporarily change the state of GLOBAL_TOOLKIT_REGISTRY, we provide the toolkit_registry_manager context manager.

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

To remove ToolkitWrappers permanently from a ToolkitRegistry, the deregister_toolkit method can be used:

>>> from openff.toolkit.utils.toolkits import OpenEyeToolkitWrapper, BuiltInToolkitWrapper
>>> from openff.toolkit.utils.toolkits import GLOBAL_TOOLKIT_REGISTRY as toolkit_registry
>>> print(len(toolkit_registry.registered_toolkits))
4
>>> toolkit_registry.deregister_toolkit(RDKitToolkitWrapper)
>>> print(len(toolkit_registry.registered_toolkits))
3
>>> toolkit_registry.register_toolkit(RDKitToolkitWrapper)
>>> print(len(toolkit_registry.registered_toolkits))
4

For example, differences in to_smiles functionality between OpenEye toolkits and The RDKit can be explored by selecting which toolkit(s) are and are not registered.

>>> from openff.toolkit.utils.toolkits import OpenEyeToolkitWrapper, GLOBAL_TOOLKIT_REGISTRY as toolkit_registry
>>> from openff.toolkit import Molecule
>>> molecule = Molecule.from_smiles('Cc1ccccc1')
>>> smiles_via_openeye = toolkit_registry.call('to_smiles', molecule)
>>> print(smiles_via_openeye)
[H]c1c(c(c(c(c1[H])[H])C([H])([H])[H])[H])[H]

>>> toolkit_registry.deregister_toolkit(OpenEyeToolkitWrapper)
>>> smiles_via_rdkit = toolkit_registry.call('to_smiles', molecule)
>>> print(smiles_via_rdkit)
[H][c]1[c]([H])[c]([H])[c]([C]([H])([H])[H])[c]([H])[c]1[H]

ToolkitRegistry

Registry for ToolkitWrapper objects

ToolkitWrapper

Toolkit wrapper base class.

OpenEyeToolkitWrapper

OpenEye toolkit wrapper

RDKitToolkitWrapper

RDKit toolkit wrapper

AmberToolsToolkitWrapper

AmberTools toolkit wrapper

NAGLToolkitWrapper

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

BuiltInToolkitWrapper

Built-in ToolkitWrapper for very basic functionality.

toolkit_registry_manager

A context manager that temporarily changes the ToolkitWrappers in the GLOBAL_TOOLKIT_REGISTRY.

Serialization support

Serializable

Mix-in to add serialization and deserialization support via JSON, YAML, BSON, TOML, MessagePack, and XML.

Collections

Custom collections for the toolkit

ValidatedList

A list that runs custom converter and validators when new elements are added.

ValidatedDict

A dict that runs custom converter and validators when new elements are added.

Miscellaneous utilities

Miscellaneous utility functions.

inherit_docstrings

Inherit docstrings from parent class

all_subclasses

Recursively retrieve all subclasses of the specified class

temporary_cd

Context to temporary change the working directory.

get_data_file_path

Get the full path to one of the reference files in testsystems.

convert_0_1_smirnoff_to_0_2

Convert an 0.1-compliant SMIRNOFF dict to an 0.2-compliant one.

convert_0_2_smirnoff_to_0_3

Convert an 0.2-compliant SMIRNOFF dict to an 0.3-compliant one.

get_molecule_parameterIDs

Process a list of molecules with a specified SMIRNOFF ffxml file and determine which parameters are used by which molecules, returning collated results.

unit_to_string

Exceptions

Exceptions raised by the Toolkit.