EspalomaTemplateGenerator#

class openmmforcefields.generators.EspalomaTemplateGenerator(molecules=None, cache=None, forcefield=None, model_cache_path=None, template_generator_kwargs=None)[source]#

OpenMM ForceField residue template generator for espaloma force fields using pre-cached OpenFF toolkit molecules.

Espaloma uses a graph net approach to chemical perception to assign parameters and charges.

Espaloma docs and papers: https://docs.espaloma.org/
Espaloma code and models: choderalab/espaloma
Open Force Field Initiative: http://openforcefield.org

Warning

This API is experimental and subject to change.

Examples

Create a template generator for a single Molecule and register it with ForceField:

>>> # Define a Molecule using the OpenFF Molecule object
>>> from openff.toolkit import Molecule
>>> molecule = Molecule.from_smiles('c1ccccc1')
>>> # Create the Espaloma template generator
>>> from openmmforcefields.generators import EspalomaTemplateGenerator
>>> template_generator = EspalomaTemplateGenerator(molecules=molecule, forcefield='espaloma-0.3.2')
>>> # Create an OpenMM ForceField
>>> from openmm.app import ForceField
>>> amber_forcefields = ['amber/protein.ff14SB.xml', 'amber/tip3p_standard.xml', 'amber/tip3p_HFE_multivalent.xml']
>>> forcefield = ForceField(*amber_forcefields)
>>> # Register the template generator
>>> forcefield.registerTemplateGenerator(template_generator.generator)

Create a template generator and register multiple molecules:

>>> molecule1 = Molecule.from_smiles('c1ccccc1')
>>> molecule2 = Molecule.from_smiles('CCO')
>>> template_generator = EspalomaTemplateGenerator(
...     molecules=[molecule1, molecule2],
...     forcefield='espaloma-0.3.2',
... )

Alternatively, you can specify a local .pt parameter file for Espaloma:

>>> template_generator = EspalomaTemplateGenerator(
...     molecules=[molecule1, molecule2],
...     forcefield='espaloma-0.3.2.pt',
... )

You can also add some Molecules later on after the generator has been registered:

>>> template_generator.add_molecules(molecule)
>>> template_generator.add_molecules([molecule1, molecule2])

You can optionally create or use a tiny database cache of pre-parameterized molecules:

>>> template_generator = EspalomaTemplateGenerator(cache='espaloma-molecules.json', forcefield='espaloma-0.3.2')

Newly parameterized molecules will be written to the cache, saving time next time!

__init__(molecules=None, cache=None, forcefield=None, model_cache_path=None, template_generator_kwargs=None)[source]#

Create an EspalomaTemplateGenerator with some OpenFF toolkit molecules

Requires the OpenFF toolkit: http://openforcefield.org and espaloma: choderalab/espaloma

Parameters:

molecules (openff.toolkit.Molecule or list of Molecules, optional, default=None) – Can be a Molecule or a list of Molecule objects. If specified, these molecules will be recognized and parameterized with espaloma as needed. The parameters will be cached in case they are encountered again the future.
cache (str, optional, default=None) – Filename for global caching of parameters. If specified, parameterized molecules will be stored in a TinyDB instance as a JSON file.
forcefield (str, optional, default=None) – Name of installed Espaloma force field version (e.g. ‘espaloma-0.3.2’) to retrieve remotely, a local Espaloma .pt parmaeters filename (with extension), or a URL to an online espaloma force field.
model_cache_path (str, optional, default=None) – If specified, use this directory to cache espaloma models default: ~/.espaloma/
template_generator_kwargs (dict, optional, default=None) – An optional dictionary containing additional optional arguments: {“reference_forcefield”: str, Openff force field supported by openforcefield/openff-forcefields without .offxml extension} {“charge_method”: str, Charge method supported by espaloma [‘nn’, ‘am1-bcc’, ‘gasteiger’, ‘from-molecule’]}

Default behavior is to use openff_unconstrained-2.2.1 for reference_forcefield and nn for charge_method. User defined charges can be assigned by setting the charge_method to from_molecule if charges are assigned to openff.toolkit.Molecule.

Examples

Create an Espaloma template generator for a single molecule (benzene, created from SMILES) and register it with ForceField:

>>> from openff.toolkit import Molecule
>>> molecule = Molecule.from_smiles('c1ccccc1')
>>> from openmmforcefields.generators import EspalomaTemplateGenerator
>>> espaloma_generator = EspalomaTemplateGenerator(molecules=molecule, forcefield='espaloma-0.3.2')
>>> from openmm.app import ForceField
>>> amber_forcefields = ['amber/protein.ff14SB.xml', 'amber/tip3p_standard.xml', 'amber/tip3p_HFE_multivalent.xml']
>>> forcefield = ForceField(*amber_forcefields)

>>> espaloma_generator.forcefield
'espaloma-0.3.2'

You can check which espaloma parameter set force field filename is in use with

>>> espaloma_generator.espaloma_filename
'/.../espaloma-0.3.2.pt'

Create a template generator for a specific SMIRNOFF force field for multiple molecules read from an SDF file or list of SMILES strings:

>>> molecules = Molecule.from_file('molecules.sdf')
>>> molecules = [Molecule.from_smiles(smiles) for smiles in ["CCO", "c1ccccc1"]]
>>> espaloma_generator = EspalomaTemplateGenerator(molecules=molecules, forcefield='espaloma-0.3.2')

You can also add molecules later on after the generator has been registered:

>>> espaloma_generator.add_molecules(molecules[-1])

You can optionally create or use a cache of pre-parameterized molecules:

>>> espaloma_generator = EspalomaTemplateGenerator(cache='smirnoff.json', forcefield='espaloma-0.3.2')

Newly parameterized molecules will be written to the cache, saving time next time!

You can also pass a template_generator_kwargs to specify the reference_forcefield and/or charge_method in EspalomaTemplateGenerator:

>>> template_generator_kwargs = {"reference_forcefield": "openff_unconstrained-2.2.1", "charge_method": "nn"}
>>> espaloma_generator = EspalomaTemplateGenerator(cache='smirnoff.json', forcefield='espaloma-0.3.2', template_generator_kwargs=template_generator_kwargs)

Methods

`__init__`([molecules, cache, forcefield, ...])	Create an EspalomaTemplateGenerator with some OpenFF toolkit molecules
`add_molecules`([molecules])	Add specified list of Molecule objects to cached molecules that will be recognized.
`cache_system`(smiles, system)	Transiently cache a copy of the OpenMM System object
`clear_system_cache`()	Initialize the OpenMM System cache
`convert_system_to_ffxml`(molecule, system[, ...])	Convert OpenMM System object to molecule-specific OpenMM ffxml
`generate_residue_template`(molecule)	Generate a residue template and additional parameters for the specified Molecule.
`generator`(forcefield, residue)	Residue template generator method to register with openmm.app.ForceField
`get_openmm_system`(molecule)	Retrieve the OpenMM System object generated for a particular molecule for testing/validation.

Attributes

`CHARGE_METHODS`
`INSTALLED_FORCEFIELDS`
`espaloma_filename`	Full path to the SMIRNOFF force field file
`forcefield`	The name or a description of the current force field in use

add_molecules(molecules=None)#

Add specified list of Molecule objects to cached molecules that will be recognized.

Parameters:: molecules (openff.toolkit.Molecule or list of Molecules, optional, default=None) – Can be a Molecule or a list of Molecule objects. If specified, these molecules will be recognized and parameterized as needed. The parameters will be cached in case they are encountered again the future.

Examples

Add some Molecules later on after the generator has been registered:

>>> from openff.toolkit import Molecule
>>> smiles = ('c1ccccc1', 'O=Cc1ccc(O)c(OC)c1', 'CN1CCC[C@H]1c2cccnc2')
>>> mol1, mol2, mol3 = [Molecule.from_smiles(s, allow_undefined_stereo=True) for s in smiles]
>>> generator.add_molecules(mol1)
>>> generator.add_molecules([mol2, mol3])

cache_system(smiles, system)#

Transiently cache a copy of the OpenMM System object

Parameters:

smiles (str) – The SMILES corresponding to the System object
system (openmm.System) – The OpenMM System to cache

clear_system_cache()#: Initialize the OpenMM System cache

convert_system_to_ffxml(molecule, system, improper_atom_ordering='smirnoff')#

Convert OpenMM System object to molecule-specific OpenMM ffxml

Parameters:

molecule (openff.toolkit.Molecule) – The Molecule to be converted
system (openmm.System) – The System corresponding to molecule
improper_atom_ordering (str, optional, default=’smirnoff’) – OpenMM openmm.app.ForceField improper atom ordering scheme to use

Returns:

ffxml_contents – The OpenMM ffxml contents for the given molecule.

Return type:

str

property forcefield#: The name or a description of the current force field in use

generator(forcefield, residue)#

Residue template generator method to register with openmm.app.ForceField

Parameters:

forcefield (openmm.app.ForceField) – The ForceField object to which residue templates and/or parameters are to be added.
residue (openmm.app.Topology.Residue) – The residue topology for which a template is to be generated.

Returns:

success – If the generator is able to successfully parameterize the residue, True is returned. If the generator cannot parameterize the residue, it should return False and not modify forcefield.

Return type:

bool

get_openmm_system(molecule)#

Retrieve the OpenMM System object generated for a particular molecule for testing/validation.

Parameters:: molecule (openff.toolkit.Molecule) – The Molecule object
Returns:: system – If the Molecule object has already been parameterized by this instance, this molecule is returned. Otherwise, None is returned.
Return type:: openmm.System or None

property espaloma_filename#: Full path to the SMIRNOFF force field file

generate_residue_template(molecule)[source]#

Generate a residue template and additional parameters for the specified Molecule.

Parameters:: molecule (openff.toolkit.Molecule) – A molecule to generate a residue template for. The molecule will be parameterized with espaloma as needed. The parameters will be cached in case it is encountered again the future.
Returns:: ffxml_contents – Contents of ForceField ffxml file containing additional parameters and residue template.
Return type:: str

Notes

The residue template will be named after the SMILES of the molecule.