openforcefield.utils.toolkits.ToolkitRegistry¶

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

Registry for ToolkitWrapper objects

Examples

>>> from openforcefield.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 openforcefield.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.

Attributes

registered_toolkit_versions: Return a dict containing the version of each registered toolkit.
registered_toolkits: List registered toolkits.

Methods

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

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

Create an empty toolkit registry.

Parameters

toolkit_precedencelist, default=[]: List of toolkit wrapper classes, in order of desired precedence when performing molecule operations. If None, no toolkits will be registered.
exception_if_unavailablebool, optional, default=True: If True, an exception will be raised if the toolkit is unavailable
_register_imported_toolkit_wrappersbool, 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

toolkitsiterable 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_versionsdict[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_wrapperinstance or subclass of ToolkitWrapper: The toolkit wrapper to register or its class.
exception_if_unavailablebool, 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_wrapperinstance 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_wrapperopenforcefield.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_namestr: 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 openforcefield.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_namestr: The name of the method to execute
raise_exception_typeslist 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 openforcefield.topology import Molecule
>>> molecule = Molecule.from_smiles('Cc1ccccc1')
>>> toolkit_registry = ToolkitRegistry([OpenEyeToolkitWrapper, RDKitToolkitWrapper])
>>> smiles = toolkit_registry.call('to_smiles', molecule)