openff.toolkit.utils.toolkits.ToolkitRegistry

class openff.toolkit.utils.toolkits.ToolkitRegistry(toolkit_precedence=[], exception_if_unavailable=True, _register_imported_toolkit_wrappers=False)[source]

Registry for ToolkitWrapper objects

Examples

Register toolkits in a specified order, skipping if unavailable

>>> from openff.toolkit.utils.toolkits import ToolkitRegistry
>>> toolkit_precedence = [OpenEyeToolkitWrapper, RDKitToolkitWrapper, AmberToolsToolkitWrapper]
>>> toolkit_registry = ToolkitRegistry(toolkit_precedence)
>>> toolkit_registry
ToolkitRegistry containing OpenEye Toolkit, The RDKit, AmberTools

Register all available toolkits (in the order OpenEye, RDKit, AmberTools, built-in)

>>> toolkits = [OpenEyeToolkitWrapper, RDKitToolkitWrapper, AmberToolsToolkitWrapper, BuiltInToolkitWrapper]
>>> toolkit_registry = ToolkitRegistry(toolkit_precedence=toolkits)
>>> toolkit_registry
ToolkitRegistry containing OpenEye Toolkit, The RDKit, AmberTools, Built-in Toolkit

Retrieve the global singleton toolkit registry, which is created when this module is imported from all available toolkits:

>>> from openff.toolkit.utils.toolkits import GLOBAL_TOOLKIT_REGISTRY as toolkit_registry
>>> toolkit_registry
ToolkitRegistry containing OpenEye Toolkit, The RDKit, AmberTools, Built-in Toolkit

Note that this will contain different ToolkitWrapper objects based on what toolkits are currently installed.

Warning

This API is experimental and subject to change.

__init__(toolkit_precedence=[], exception_if_unavailable=True, _register_imported_toolkit_wrappers=False)[source]

Create an empty toolkit registry.

Parameters

  • toolkit_precedence (list, default=[]) – List of toolkit wrapper classes, in order of desired precedence when performing molecule operations. If None, no toolkits will be registered.

  • exception_if_unavailable (bool, optional, default=True) – If True, an exception will be raised if the toolkit is unavailable

  • _register_imported_toolkit_wrappers (bool, optional, default=False) – If True, will attempt to register all imported ToolkitWrapper subclasses that can be found in the order of toolkit_precedence, if specified. If toolkit_precedence is not specified, the default order is [OpenEyeToolkitWrapper, RDKitToolkitWrapper, AmberToolsToolkitWrapper, BuiltInToolkitWrapper].

Methods

__init__([toolkit_precedence, ...])

Create an empty toolkit registry.

add_toolkit(toolkit_wrapper)

Append a ToolkitWrapper onto the list of toolkits in this ToolkitRegistry

call(method_name, *args[, raise_exception_types])

Execute the requested method by attempting to use all registered toolkits in order of precedence.

deregister_toolkit(toolkit_wrapper)

Remove a ToolkitWrapper from the list of toolkits in this ToolkitRegistry

register_toolkit(toolkit_wrapper[, ...])

Register the provided toolkit wrapper class, instantiating an object of it.

resolve(method_name)

Resolve the requested method name by checking all registered toolkits in order of precedence for one that provides the requested method.

Attributes

registered_toolkit_versions

Return a dict containing the version of each registered toolkit.

registered_toolkits

List registered toolkits.
property registered_toolkits

List registered toolkits.

Warning

This API is experimental and subject to change.

Returns

toolkits (iterable of toolkit objects)

property registered_toolkit_versions

Return a dict containing the version of each registered toolkit.

Warning

This API is experimental and subject to change.

Returns

toolkit_versions (dict[str, str]) – A dictionary mapping names and versions of wrapped toolkits

register_toolkit(toolkit_wrapper, exception_if_unavailable=True)[source]

Register the provided toolkit wrapper class, instantiating an object of it.

Warning

This API is experimental and subject to change.

Parameters

  • toolkit_wrapper (instance or subclass of ToolkitWrapper) – The toolkit wrapper to register or its class.

  • exception_if_unavailable (bool, optional, default=True) – If True, an exception will be raised if the toolkit is unavailable

deregister_toolkit(toolkit_wrapper)[source]

Remove a ToolkitWrapper from the list of toolkits in this ToolkitRegistry

Warning

This API is experimental and subject to change.

Parameters

toolkit_wrapper (instance or subclass of ToolkitWrapper) – The toolkit wrapper to remove from the registry

Raises

  • InvalidToolkitError – If toolkit_wrapper is not a ToolkitWrapper or subclass

  • ToolkitUnavailableException – If toolkit_wrapper is not found in the registry

add_toolkit(toolkit_wrapper)[source]

Append a ToolkitWrapper onto the list of toolkits in this ToolkitRegistry

Warning

This API is experimental and subject to change.

Parameters

toolkit_wrapper (openff.toolkit.utils.ToolkitWrapper) – The ToolkitWrapper object to add to the list of registered toolkits

Raises

InvalidToolkitError – If toolkit_wrapper is not a ToolkitWrapper or subclass

resolve(method_name)[source]

Resolve the requested method name by checking all registered toolkits in order of precedence for one that provides the requested method.

Parameters

method_name (str) – The name of the method to resolve

Returns

method – The method of the first registered toolkit that provides the requested method name

Raises

NotImplementedError if the requested method cannot be found among the registered toolkits –

Examples

Create a molecule, and call the toolkit to_smiles() method directly

>>> from openff.toolkit.topology import Molecule
>>> molecule = Molecule.from_smiles('Cc1ccccc1')
>>> toolkit_registry = ToolkitRegistry([OpenEyeToolkitWrapper, RDKitToolkitWrapper, AmberToolsToolkitWrapper])
>>> method = toolkit_registry.resolve('to_smiles')
>>> smiles = method(molecule)
call(method_name, *args, raise_exception_types=None, **kwargs)[source]

Execute the requested method by attempting to use all registered toolkits in order of precedence.

*args and **kwargs are passed to the desired method, and return values of the method are returned

This is a convenient shorthand for toolkit_registry.resolve_method(method_name)(*args, **kwargs)

Parameters

  • method_name (str) – The name of the method to execute

  • raise_exception_types (list of Exception subclasses, default=None) – A list of exception-derived types to catch and raise immediately. If None, this will be set to [Exception], which will raise an error immediately if the first ToolkitWrapper in the registry fails. To try each ToolkitWrapper that provides a suitably-named method, set this to the empty list ([]). If all ToolkitWrappers run without raising any exceptions in this list, a single ValueError will be raised containing the each ToolkitWrapper that was tried and the exception it raised.

Raises

  • NotImplementedError if the requested method cannot be found among the registered toolkits –

  • ValueError if no exceptions in the raise_exception_types list were raised by ToolkitWrappers, and –

  • all ToolkitWrappers in the ToolkitRegistry were tried. –

  • Other forms of exceptions are possible if raise_exception_types is specified. –

  • These are defined by the ToolkitWrapper method being called. –

Examples

Create a molecule, and call the toolkit to_smiles() method directly

>>> from openff.toolkit.topology import Molecule
>>> molecule = Molecule.from_smiles('Cc1ccccc1')
>>> toolkit_registry = ToolkitRegistry([OpenEyeToolkitWrapper, RDKitToolkitWrapper])
>>> smiles = toolkit_registry.call('to_smiles', molecule)