`ToolkitRegistry`

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

Registry for ToolkitWrapper objects

Examples

>>> 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>

>>> 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=None, exception_if_unavailable=True, _register_imported_toolkit_wrappers=False)[source]

Create an empty toolkit registry.

Parameters:

toolkit_precedence (list, optional, default=None) – 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]

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 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 import Molecule
>>> molecule = Molecule.from_smiles('Cc1ccccc1')
>>> toolkit_registry = ToolkitRegistry([OpenEyeToolkitWrapper, RDKitToolkitWrapper])
>>> smiles = toolkit_registry.call('to_smiles', molecule)