GAFFTemplateGenerator#

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

OpenMM ForceField residue template generator for GAFF/AM1-BCC using pre-cached OpenFF toolkit molecules.

One template generator can be registered in multiple OpenMM ForceField objects.

Examples

Create a template generator for GAFF 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 GAFF template generator
>>> from openmmforcefields.generators import GAFFTemplateGenerator
>>> template_generator = GAFFTemplateGenerator(molecules=molecule, forcefield='gaff-2.2.20')
>>> # 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 for a specific GAFF version and register multiple molecules:

>>> molecule1 = Molecule.from_smiles('c1ccccc1')
>>> molecule2 = Molecule.from_smiles('CCO')
>>> template_generator = GAFFTemplateGenerator(molecules=[molecule1, molecule2], forcefield='gaff-2.2.20')

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 = GAFFTemplateGenerator(cache='gaff-molecules.json', forcefield='gaff-2.2.20')

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

You can see which force fields are supported with

>>> template_generator.INSTALLED_FORCEFIELDS
['gaff-1.4', 'gaff-1.8', 'gaff-1.81', 'gaff-2.1', 'gaff-2.11', 'gaff-2.2.20']

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

Create a GAFFTemplateGenerator 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 antechamber as needed. The parameters will be cached in case they are encountered again the future.
forcefield (str) – GAFF force field to use, one of [‘gaff-1.4’, ‘gaff-1.8’, ‘gaff-1.81’, ‘gaff-2.1’, ‘gaff-2.11’, ‘gaff-2.2.20’] GAFFTemplateGenerator.INSTALLED_FORCEFIELDS contains a complete up-to-date list of supported force fields.
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.
template_generator_kwargs (dict, optional, default=None) – Additional parameters for the template generator (ignored by GAFFTemplateGenerator).

Examples

Create a GAFF template generator for a single molecule (benzene, created from SMILES) and register it:

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

Create a template generator for multiple molecules read from an SDF file:

>>> molecules = Molecule.from_file('molecules.sdf')
>>> gaff = GAFFTemplateGenerator(molecules=molecules, forcefield='gaff-2.2.20')

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

>>> molecule = Molecule.from_smiles("CCO")
>>> gaff.add_molecules(molecule)

>>> molecule1, molecule2 = [Molecule.from_smiles(smiles) for smiles in ["CC", "c1ccccc1"]]
>>> gaff.add_molecules([molecule1, molecule2])

To check which GAFF versions are supported, check the INSTALLED_FORCEFIELDS attribute:

>>> print(GAFFTemplateGenerator.INSTALLED_FORCEFIELDS)
['gaff-1.4', 'gaff-1.8', 'gaff-1.81', 'gaff-2.1', 'gaff-2.11', 'gaff-2.2.20']

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

>>> gaff = GAFFTemplateGenerator(cache='gaff-molecules.json', forcefield='gaff-2.2.20')

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

Methods

`__init__`([molecules, forcefield, cache, ...])	Create a GAFFTemplateGenerator with some OpenFF toolkit molecules
`add_molecules`([molecules])	Add specified list of Molecule objects to cached molecules that will be recognized.
`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

Attributes

`INSTALLED_FORCEFIELDS`
`forcefield`	The name or a description of the current force field in use
`gaff_dat_filename`	File path to the GAFF .dat AMBER force field file
`gaff_major_version`	The current GAFF major version in use
`gaff_minor_version`	The current GAFF minor version in use
`gaff_version`	The current GAFF version in use
`gaff_xml_filename`	File path to the GAFF .ffxml OpenMM force field file

property gaff_version#: The current GAFF version in use

property gaff_major_version#: The current GAFF major version in use

property gaff_minor_version#: The current GAFF minor version in use

property gaff_dat_filename#: File path to the GAFF .dat AMBER force field file

property gaff_xml_filename#: File path to the GAFF .ffxml OpenMM force field file

generator(forcefield, residue)[source]#

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

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 antechamber 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])

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