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]
A registry and precedence list for
ToolkitWrapper
objects.ToolkitRegistry
allows the OpenFF Toolkit to provide a concise, universal API that can call out to other well-established libraries rather than re-implement algorithms with well-established implementations, while still giving users control over dependencies. It contains a list ofToolkitWrapper
objects, each of which provides some collection of methods that may be requested from the registry. Thecall()
method takes a name and calls the method of that name on each wrapper until it finds a working implementation, whose result it returns. For details on how this search is conducted and what counts as a working implementation, see that method’s API docs.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 >>> GLOBAL_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.
Call a method on the registered toolkit wrapper with the highest precedence:
>>> molecule = toolkit_registry.call('from_smiles', 'Cc1ccccc1')
For more, see the
call()
method.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 a method with the first registered toolkits that supports it.
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)Get a method with the given name from the first registered toolkit that provides it.
Attributes
Return a dict containing the version of each registered toolkit.
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
- call(method_name: str, *args, raise_exception_types: list[type[Exception]] | None = None, **kwargs)[source]
Execute a method with the first registered toolkits that supports it.
This method searches the registry’s precedence list for the first wrapper that has an attribute named
method_name
and attempts to call it as a method using the arguments in*args
and**kwargs
. If that method raises no exception, its return value is returned.By default, if a wrapper with an appropriately-named method raises an exception of any type, then iteration over the registered toolkits stops early and that exception is raised. To limit this behavior to only certain exceptions and otherwise continue iteration, customize this behavior using the optional
raise_exception_types
keyword argument. If iteration finishes without finding a wrapper that can successfully call the requested method, aValueError
is raised, containing a message listing the registered toolkits and any exceptions that occurred.- 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
, the first exception encountered will be raised. To ignore all exceptions, set this to the empty list[]
.
- Raises:
ValueError – If no suitable toolkit wrapper was found in the registry.
Exception – 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, ... ToolkitRegistry, ... AmberToolsToolkitWrapper, ... RDKitToolkitWrapper, ... ) >>> molecule = Molecule.from_smiles('Cc1ccccc1') >>> toolkit_registry = ToolkitRegistry([ ... AmberToolsToolkitWrapper, ... RDKitToolkitWrapper, ... ]) >>> smiles = toolkit_registry.call('to_smiles', molecule)
Stop if a partial charge assignment method encounters an error during the partial charge calculation (
ChargeCalculationError
), but proceed to the next wrapper for any other exception such as the wrapper not supporting the charge method:>>> from openff.toolkit import GLOBAL_TOOLKIT_REGISTRY >>> from openff.toolkit.utils.exceptions import ChargeCalculationError >>> GLOBAL_TOOLKIT_REGISTRY.call( ... "assign_partial_charges", ... molecule=Molecule.from_smiles('C'), ... partial_charge_method="gasteiger", ... raise_exception_types=[ChargeCalculationError], ... )
Calling a method that exists on none of the wrappers raises a
ValueError
:>>> from openff.toolkit import ToolkitRegistry, RDKitToolkitWrapper >>> toolkit_registry = ToolkitRegistry([RDKitToolkitWrapper]) >>> toolkit_registry.call("there_is_no_spoon") Traceback (most recent call last): ... ValueError: No registered toolkits can provide the capability "there_is_no_spoon" for args "()" and kwargs "{}" Available toolkits are: [ToolkitWrapper around The RDKit version ...]
- 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:
InvalidToolkitError – If toolkit_wrapper is not a ToolkitWrapper or subclass
ToolkitUnavailableException – If toolkit_wrapper is not found in the registry
- 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]
Get a method with the given name from the first registered toolkit that provides it.
Resolve the requested method name by checking all registered toolkits in order of precedence for one that provides the requested method. Note that this may not be the method used by
call()
if theraise_exception_types
argument is passed.- 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)