Utilities¶

Toolkit wrappers¶

The toolkit wrappers provide a simple uniform API for accessing minimal functionality of cheminformatics toolkits.

These toolkit wrappers are generally used through a ToolkitRegistry, which can be constructed with a desired precedence of toolkits:

>>> from openforcefield.utils.toolkits import ToolkitRegistry, OpenEyeToolkitWrapper, RDKitToolkitWrapper, AmberToolsToolkitWrapper
>>> toolkit_registry = ToolkitRegistry()
>>> toolkit_precedence = [OpenEyeToolkitWrapper, RDKitToolkitWrapper, AmberToolsToolkitWrapper]
>>> [ toolkit_registry.register_toolkit(toolkit) for toolkit in toolkit_precedence if toolkit.is_available() ]
[None, None, None]

The toolkit wrappers can then be accessed through the registry:

>>> from openforcefield.utils.toolkits import GLOBAL_TOOLKIT_REGISTRY as toolkit_registry
>>> from openforcefield.topology.molecule import Molecule
>>> molecule = Molecule.from_smiles('Cc1ccccc1')
>>> smiles = toolkit_registry.call('to_smiles', molecule)

The order of toolkits, as specified in toolkit_precedence above, determines the order in which the called method is resolved, i.e. if the toolkit with highest precedence has a to_smiles method, that is the toolkit that will be called. If the toolkit with highest precedence does not have such a method, it is attempted with other toolkits until one is found. By default, if a toolkit with an appropriately-named method raises an exception of any type, then iteration over the registered toolkits stops and that exception is raised. To continue iteration if specific exceptions are encountered, customize this behavior using the optional raise_exception_types keyword argument to ToolkitRegistry.call. If no registered toolkits have the method, a ValueError is raised, containing a message listing the registered toolkits and exceptions (if any) that were ignored.

Alternatively, the global toolkit registry (which will attempt to register any available toolkits) can be used:

>>> from openforcefield.utils.toolkits import GLOBAL_TOOLKIT_REGISTRY as toolkit_registry
>>> len(toolkit_registry.registered_toolkits)
4

Individual toolkits can be registered or deregistered to control the backend that ToolkitRegistry calls resolve to. This can be useful for debugging and exploring subtley different behavior between toolkit wrappers.

from openforcefield.utils.toolkits import OpenEyeToolkitWrapper, BuiltInToolkitWrapper
from openforcefield.utils.toolkits import GLOBAL_TOOLKIT_REGISTRY as toolkit_registry
toolkit_registry.deregister_toolkit(OpenEyeToolkitWrapper)
toolkit_registry.register_toolkit(BuiltInToolkitWrapper)
toolkit_registry.registered_toolkits

For example, differences in to_smiles functionality between OpenEye toolkits and The RDKit can be explored by selecting which toolkit(s) are and are not registered.

>>> from openforcefield.utils.toolkits import OpenEyeToolkitWrapper, GLOBAL_TOOLKIT_REGISTRY as toolkit_registry
>>> from openforcefield.topology.molecule import Molecule
>>> molecule = Molecule.from_smiles('Cc1ccccc1')
>>> smiles_via_openeye = toolkit_registry.call('to_smiles', molecule)
>>> print(smiles_via_openeye)
[H]c1c(c(c(c(c1[H])[H])C([H])([H])[H])[H])[H]

>>> toolkit_registry.deregister_toolkit(OpenEyeToolkitWrapper)
>>> smiles_via_rdkit = toolkit_registry.call('to_smiles', molecule)
>>> print(smiles_via_rdkit)
[H][c]1[c]([H])[c]([H])[c]([C]([H])([H])[H])[c]([H])[c]1[H]

`ToolkitRegistry`	Registry for ToolkitWrapper objects
`ToolkitWrapper`	Toolkit wrapper base class.
`OpenEyeToolkitWrapper`	OpenEye toolkit wrapper
`RDKitToolkitWrapper`	RDKit toolkit wrapper
`AmberToolsToolkitWrapper`	AmberTools toolkit wrapper

Serialization support¶

Serializable

Mix-in to add serialization and deserialization support via JSON, YAML, BSON, TOML, MessagePack, and XML.

Miscellaneous utilities¶

Miscellaneous utility functions.

`inherit_docstrings`	Inherit docstrings from parent class
`all_subclasses`	Recursively retrieve all subclasses of the specified class
`temporary_cd`	Context to temporary change the working directory. Parameters ———- dir_path : str The directory path to enter within the context Examples ——– >>> dir_path = ‘/tmp’ >>> with temporary_cd(dir_path): … pass # do something in dir_path.
`get_data_file_path`	Get the full path to one of the reference files in testsystems. In the source distribution, these files are in `openforcefield/data/`, but on installation, they’re moved to somewhere in the user’s python site-packages directory. Parameters ———- name : str Name of the file to load (with respect to the repex folder).
`convert_0_1_smirnoff_to_0_2`	Convert an 0.1-compliant SMIRNOFF dict to an 0.2-compliant one.
`convert_0_2_smirnoff_to_0_3`	Convert an 0.2-compliant SMIRNOFF dict to an 0.3-compliant one.
`get_molecule_parameterIDs`	Process a list of molecules with a specified SMIRNOFF ffxml file and determine which parameters are used by which molecules, returning collated results.