SMIRNOFFTemplateGenerator#

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

OpenMM ForceField residue template generator for Open Force Field Initiative SMIRNOFF force fields using pre-cached OpenFF toolkit molecules.

Open Force Field Initiative: http://openforcefield.org SMIRNOFF force field specification: https://open-forcefield-toolkit.readthedocs.io/en/latest/smirnoff.html

Examples

Create a template generator for a single Molecule using a selected OpenFF small molecule force field 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 SMIRNOFF template generator
>>> from openmmforcefields.generators import SMIRNOFFTemplateGenerator
>>> template_generator = SMIRNOFFTemplateGenerator(molecules=molecule, forcefield='openff-2.3.0')
>>> # 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)

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

>>> molecule1 = Molecule.from_smiles('CCO')
>>> molecule2 = Molecule.from_smiles('c1ccoc1')
>>> molecule3 = Molecule.from_smiles('C=CC')
>>> template_generator.add_molecules(molecule1)
>>> template_generator.add_molecules([molecule2, molecule3])

See SMIRNOFFTemplateGenerator.__init__() for more examples of customizing template generator creation.

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

Create a SMIRNOFFTemplateGenerator with some OpenFF toolkit molecules

Requires the OpenFF toolkit: http://openforcefield.org

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 SMIRNOFF 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, bytes, file-like object, or iterable, optional, default=None) – Names of known SMIRNOFF force fields (those present in SMIRNOFFTemplateGenerator.INSTALLED_FORCEFIELDS), paths to OFFXML force field files installed with OpenFF or present locally, or file-like objects, strings, or bytes to parse SMIRNOFF XML from.
template_generator_kwargs (dict, optional, default=None) – Additional parameters for the template generator (ignored by SMIRNOFFTemplateGenerator).

Examples

Create a SMIRNOFF template generator for a predefined force field (here, OpenFF Sage 2.3.0)

>>> from openff.toolkit import Molecule
>>> molecule = Molecule.from_smiles('c1ccccc1')
>>> from openmmforcefields.generators import SMIRNOFFTemplateGenerator
>>> smirnoff = SMIRNOFFTemplateGenerator(molecules=molecule, forcefield='openff-2.3.0')

You can see the list of predefined force field names with

>>> SMIRNOFFTemplateGenerator.INSTALLED_FORCEFIELDS
['openff-1.0.0', 'openff-1.0.1', 'openff-1.1.0', 'openff-1.1.1', ...]

In addition to force field names, you can provide an explicit filename:

>>> smirnoff = SMIRNOFFTemplateGenerator(molecules=molecule, forcefield='openff_unconstrained-2.3.0.offxml')

This can either be any OFFXML force field file installed with the OpenFF Toolkit, or a relative or absolute path to a custom file:

>>> smirnoff = SMIRNOFFTemplateGenerator(molecules=molecule, forcefield='my_custom_ff.offxml')

The template generator will also recognize file objects, or strings or bytes containing OFFXML data directly. Any of these items can also be provided as items in a list to load a SMIRNOFF force field from multiple sources:

>>> smirnoff = SMIRNOFFTemplateGenerator(molecules=molecule, forcefield=['openff-2.3.0', 'tip5p.offxml'])

You can check which force field files were actually loaded:

>>> smirnoff.smirnoff_filenames
['/.../openff_unconstrained-2.3.0.offxml', '/.../tip5p.offxml']

Note that the predefined names default to the “unconstrained” variants of OpenFF force fields. You can explicitly load a “constrained” variant by specifying its filename, e.g., openff-2.3.0.offxml.

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

>>> smirnoff = SMIRNOFFTemplateGenerator(molecules=molecule, cache='smirnoff.json', forcefield='openff-2.3.0')

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

Methods

`__init__`([molecules, cache, forcefield, ...])	Create a SMIRNOFFTemplateGenerator 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

`INSTALLED_FORCEFIELDS`
`forcefield`	The name or a description of the current force field in use
`smirnoff_filenames`	Full paths to the SMIRNOFF force field files for each force field item given during SMIRNOFFTemplateGenerator creation.

property smirnoff_filenames#: Full paths to the SMIRNOFF force field files for each force field item given during SMIRNOFFTemplateGenerator creation. If a path cannot be identified for a given item, it will be None.

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 SMIRNOFF 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.
This method preserves stereochemistry during AM1-BCC charge parameterization.
Atom names in molecules will be assigned Tripos atom names if any are blank or not unique.

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