ToolkitRegistry

class openff.toolkit.utils.toolkits.ToolkitRegistry(toolkit_precedence: list[type[ToolkitWrapper]] | None = None, exception_if_unavailable: bool = True, _register_imported_toolkit_wrappers: bool = 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: list[type[ToolkitWrapper]] | None = None, exception_if_unavailable: bool = True, _register_imported_toolkit_wrappers: bool = False)[source]

Create an empty toolkit registry.

Parameters:

  • toolkit_precedence – List of toolkit wrapper classes, in order of desired precedence when performing molecule operations. If None, no toolkits will be registered.

  • exception_if_unavailable – If True, an exception will be raised if the toolkit is unavailable

  • _register_imported_toolkit_wrappers – 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[ToolkitWrapper]

List registered toolkits.

Warning

This API is experimental and subject to change.

Returns:

toolkits

property registered_toolkit_versions: dict[str, str]

Return a dict containing the version of each registered toolkit.

Warning

This API is experimental and subject to change.

Returns:

toolkit_versions – A dictionary mapping names and versions of wrapped toolkits

register_toolkit(toolkit_wrapper: ToolkitWrapper | type[ToolkitWrapper], exception_if_unavailable: bool = 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 – The toolkit wrapper to register or its class.

  • exception_if_unavailable – If True, an exception will be raised if the toolkit is unavailable

deregister_toolkit(toolkit_wrapper: ToolkitWrapper)[source]

Remove a ToolkitWrapper from the list of toolkits in this ToolkitRegistry

Warning

This API is experimental and subject to change.

Parameters:

toolkit_wrapper – The toolkit wrapper to remove from the registry

Raises:
add_toolkit(toolkit_wrapper: ToolkitWrapper)[source]

Append a ToolkitWrapper onto the list of toolkits in this ToolkitRegistry

Warning

This API is experimental and subject to change.

Parameters:

toolkit_wrapper – 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: str) → Callable[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 – 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: str, *args, raise_exception_types: list[type[Exception]] | None = 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 – The name of the method to execute

  • raise_exception_types – 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)