SystemGenerator#

class openmmforcefields.generators.SystemGenerator(forcefields=None, small_molecule_forcefield=None, forcefield_kwargs=None, nonperiodic_forcefield_kwargs=None, periodic_forcefield_kwargs=None, template_generator_kwargs=None, barostat=None, molecules=None, cache=None, postprocess_system=None)[source]#

Common interface for generating OpenMM Systems from OpenMM Topology objects that may contain both molecules with parameters provided by OpenMM XML force fields and molecules with parameters provided by template generators.

Currently, this class supports

GAFF, via GAFFTemplateGenerator: see GAFFTemplateGenerator.INSTALLED_FORCEFIELDS
SMIRNOFF, via SMIRNOFFTemplateGenerator: see SMIRNOFFTemplateGenerator.INSTALLED_FORCEFIELDS
Espaloma, via EspalomaTemplateGenerator: see EspalomaTemplateGenerator.INSTALLED_FORCEFIELDS

Warning

This API is experimental and subject to change.

__init__(forcefields=None, small_molecule_forcefield=None, forcefield_kwargs=None, nonperiodic_forcefield_kwargs=None, periodic_forcefield_kwargs=None, template_generator_kwargs=None, barostat=None, molecules=None, cache=None, postprocess_system=None)[source]#

Initializes a SystemGenerator.

Parameters:

forcefields (list of str, optional, default=None) – List of the names of ffxml force field files that will be used in System creation to attempt to parameterize molecules.
small_molecule_forcefield (str, bytes, file-like object, or iterable, optional) – Specification of the force field(s) to use for the template generator that will attempt to parameterize any molecules that could not be parameterized by the provided ffxml force fields. Whatever is provided must be a supported force field name or other object that can be understood by one of GAFFTemplateGenerator, SMIRNOFFTemplateGenerator, or EspalomaTemplateGenerator. See these classes for details of the force fields supported.
forcefield_kwargs (dict, optional, default=None) – Keyword arguments to be passed to openmm.app.ForceField.createSystem() during System object creation.
nonperiodic_forcefield_kwargs (dict, optional, default={‘nonbondedMethod’ : NoCutoff}) – Keyword arguments added to forcefield_kwargs when the Topology is non-periodic.
periodic_forcefield_kwargs (NonbondedMethod, optional, default={‘nonbondedMethod’ : PME}) – Keyword arguments added to forcefield_kwargs when the Topology is periodic.
template_generator_kwargs (dict, optional, default=None) – The value of an extra keyword argument called template_generator_kwargs to be passed to subclasses of openmmforcefields.generators.template_generators.SmallMoleculeTemplateGenerator. Currently only used for openmmforcefields.generators.template_generators.EspalomaTemplateGenerator.
barostat (openmm.MonteCarloBarostat, optional, default=None) – If not None, a new MonteCarloBarostat with matching parameters (but a different random number seed) will be created and added to each newly created System.
molecules (openff.toolkit.topology.Molecule or list, 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.
cache (filename, optional, default=None) – If not None, filename for caching small molecule residue templates.
postprocess_system (method, optional, default=None) – If not None, this method will be called as system = postprocess_system(system) to post-process the System object for create_system(topology) before it is returned.

Examples

Here’s an example that uses GAFF 2.2.20 along with the new ff14SB generation of AMBER force fields (and compatible solvent models) to generate an OpenMM System object from an Open Force Field Topology object:

>>> # Define the keyword arguments to feed to ForceField
>>> from openmm import unit
>>> from openmm import app
>>> # Define standard OpenMM biopolymer and solvent force fields to use

To initialize the SystemGenerator, we specify the OpenMM force fields, the small molecule force field, and any kwargs to be fed to the OpenMM openmm.app.ForceField.createSystem() method:

>>> from openmmforcefields.generators import SystemGenerator
>>> amber_forcefields = [
...     "amber/protein.ff14SB.xml",
...     "amber/tip3p_standard.xml",
...     "amber/tip3p_HFE_multivalent.xml",
... ]
>>> small_molecule_forcefield = "gaff-2.2.20"
>>> forcefield_kwargs = {
...     "constraints": app.HBonds,
...     "rigidWater": True,
...     "removeCMMotion": False,
...     "hydrogenMass": 4 * unit.amu,
... }
>>> system_generator = SystemGenerator(
...     forcefields=amber_forcefields,
...     small_molecule_forcefield=small_molecule_forcefield,
...     forcefield_kwargs=forcefield_kwargs,
... )

If the cache argument is specified, parameterized molecules are cached in the corresponding file.

>>> cache = 'db.json'
>>> system_generator = SystemGenerator(forcefields=amber_forcefields, small_molecule_forcefield='gaff-2.2.20', forcefield_kwargs=forcefield_kwargs, cache=cache)

To use a barostat, you need to define a barostat whose parameters will be copied into each system (with a different random number seed):

>>> import openmm
>>> from openmm import unit
>>> pressure = 1.0 * unit.atmospheres
>>> temperature = 298.0 * unit.kelvin
>>> frequency = 25 # steps
>>> system_generator.barostat = openmm.MonteCarloBarostat(pressure, temperature, frequency)

Now, you can create an OpenMM System object from an OpenMM Topology object and a list of OpenFF Molecule objects

>>> from openff.toolkit import Molecule, Topology
>>> molecules = [Molecule.from_smiles(smiles) for smiles in ["CCO", "c1ccccc1"]]
>>> openmm_topology = Topology.from_molecules(molecules).to_openmm()
>>> system = system_generator.create_system(openmm_topology, molecules=molecules)

Parameters for multiple force fields can be held in the same cache file.

To use the Open Force Field ‘openff-1.0.0’ (“Parsley”) force field instead, simply change the small_molecule_forcefield parameter to one of the supported GAFFTemplateGenerator.INSTALLED_FORCEFIELDS:

>>> small_molecule_forcefield = 'openff-1.0.0'
>>> system_generator = SystemGenerator(forcefields=amber_forcefields, small_molecule_forcefield=small_molecule_forcefield, forcefield_kwargs=forcefield_kwargs)

For debugging convenience, you can also turn _off_ specific interactions during system creation, such as particle charges:

>>> system_generator.particle_charges = False # will cause particle charges to be set to zero
>>> system_generator.exception_charges = False # will zero out all 1-4 charge interactions
>>> system_generator.particle_epsilons = False # will zero out Lennard-Jones particle-particle interactions
>>> system_generator.particle_exceptions = False # will zero out all 1-4 Lennard-Jones interactions
>>> system_generator.torsions = False # will zero out all torsion terms

Methods

`__init__`([forcefields, ...])	Initializes a SystemGenerator.
`add_molecules`(molecules)	Add molecules to registered template generator
`create_system`(topology[, molecules])	Create a system from the specified topology.

Attributes

SMALL_MOLECULE_FORCEFIELDS

add_molecules(molecules)[source]#

Add molecules to registered template generator

Parameters:: molecules (openff.toolkit.topology.Molecule or list, 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.

create_system(topology, molecules=None)[source]#

Create a system from the specified topology.

Parameters:

topology (openmm.app.Topology object) – The topology describing the system to be created
molecules (openff.toolkit.topology.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.

Returns:

system – A system object generated from the topology

Return type:

openmm.System