diff --git a/README.md b/README.md
index 75142736..b734646a 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ This repository provides support for AMBER, CHARMM, OpenFF, and Espaloma force f
**CHARMM:** Non-polarizable protein, nucleic acid, and pre-parameterized small molecule force fields available in in the [July 2024 CHARMM36 force field release from the Mackerell website](http://mackerell.umaryland.edu/charmm_ff.shtml). *Note that this conversion has not yet been fully validated.*
-**Open Force Field Initiative force fields:** All distributed [Open Force Field Initiative](http://openforcefield.org) [force fields](https://openforcefield.org/force-fields/force-fields/), including the [`openff-2.x.y` ("Sage")](https://openforcefield.org/force-fields/force-fields/) and [`smirnoff99Frosst`](https://github.com/openforcefield/smirnoff99Frosst/) series of force fields available through the [`openff-forcefields`](http://github.com/openforcefield/openff-forcefields) package. This is now supported in OpenMM 7.5.0 and later.
+**Open Force Field Initiative force fields:** All distributed [Open Force Field Initiative](http://openforcefield.org) [force fields](https://openforcefield.org/force-fields/force-fields/), including the [`openff-2.x.y` ("Sage")](https://openforcefield.org/force-fields/force-fields/) and [`smirnoff99Frosst`](https://github.com/openforcefield/smirnoff99Frosst/) series of force fields available through the [`openff-forcefields`](http://github.com/openforcefield/openff-forcefields) package.
**Espaloma:** Currently [`espaloma-0.3.2`](https://github.com/choderalab/espaloma/releases/tag/0.3.2) is supported. See our [first espaloma paper](https://arxiv.org/abs/2010.01196) and our second paper which focuses on [protein-ligand systems and beyond](https://arxiv.org/abs/2307.07085).
@@ -31,8 +31,6 @@ conda install --yes -c conda-forge openmmforcefields
If you optionally have the [OpenEye Toolkits](https://www.eyesopen.com/toolkit-development) installed, `openmmforcefields` will use these to accelerate small molecule parameterization.
Free academic licenses are available for [bona fide academic research](https://www.eyesopen.com/academic-licensing), while licenses for IP generation are available [for a fee](https://www.eyesopen.com/pricing).
-Support for the SMIRNOFF residue template or system generators requires OpenMM 7.4.2 or later.
-
## Using the AMBER and CHARMM biopolymer force fields
This repository contains force fields for use with the [OpenMM `ForceField` class](http://docs.openmm.org/latest/userguide/application.html#force-fields) for parameterizing biomolecular systems.
@@ -96,7 +94,7 @@ If the provided molecule(s) contain nonzero (user-specified) partial charges (st
If they do _not_ contain partial charges, the OpenFF Toolkit is used to generate them.
* In `GAFFTemplateGenerator`, [Antechamber](http://ambermd.org/antechamber/) from the [AmberTools](http://ambermd.org/AmberTools.php) distribution (which uses the `sqm` semiempirical quantum chemical package) is used to assign AM1-BCC charges (`antechamber -c bcc`). The conformers used in charge assignment are generated by RDKit.
-* In `SMIRNOFFTemplateGenerator`, the charges are assigned by the OpenFF software according to the [AM1-BCC settings of the SMIRNOFF specification](https://openforcefield.github.io/standards/standards/smirnoff/#toolkitam1bcc-temporary-support-for-toolkit-based-am1-bcc-partial-charges).
+* In `SMIRNOFFTemplateGenerator`, the charges are assigned by the OpenFF software using [OpenFF NAGL](https://github.com/openforcefield/openff-nagl) or according to the [AM1-BCC settings of the SMIRNOFF specification](https://openforcefield.github.io/standards/standards/smirnoff/#toolkitam1bcc-temporary-support-for-toolkit-based-am1-bcc-partial-charges) (depending on the force field in use).
* If OpenEye Toolkits are installed and licensed, OpenEye's Quacpac Toolkit is used to generate [AM1-BCC-ELF10 charges](https://docs.eyesopen.com/toolkits/python/quacpactk/OEProtonClasses/OEAM1BCCELF10Charges.html). In this case, the conformers used to generate charges are generated by OpenEye's Omega Toolkit.
* If OpenEye Toolkits are not installed or not licensed, AmberTools's Antechamber/`sqm` is used to generate AM1-BCC charges in the same way that it is used in `GAFFTemplateGenerator`. In this case, the conformers used to generate charges are generated by RDKit.
@@ -175,7 +173,7 @@ Newly parameterized molecules will be written to the cache, saving time next tim
## Using the Open Force Field Initiative SMIRNOFF small molecule force fields
-The `openmmforcefields` package includes a [residue template generator](http://docs.openmm.org/latest/userguide/application.html#adding-residue-template-generators) for [the OpenMM `ForceField` class](http://docs.openmm.org/latest/api-python/generated/openmm.app.forcefield.ForceField.html#openmm.app.forcefield.ForceField) that automatically generates OpenMM residue templates for small molecules lacking parameters using the [Open Force Field Initiative](http://openforcefield.org) [SMIRNOFF](https://openforcefield.github.io/standards/standards/smirnoff/)small molecule force fields.
+The `openmmforcefields` package includes a [residue template generator](http://docs.openmm.org/latest/userguide/application.html#adding-residue-template-generators) for [the OpenMM `ForceField` class](http://docs.openmm.org/latest/api-python/generated/openmm.app.forcefield.ForceField.html#openmm.app.forcefield.ForceField) that automatically generates OpenMM residue templates for small molecules lacking parameters using the [Open Force Field Initiative](http://openforcefield.org) [SMIRNOFF](https://openforcefield.github.io/standards/standards/smirnoff/) small molecule force fields.
This includes the [`openff-1.x.y` ("Parsley")](https://openforcefield.org/news/introducing-openforcefield-1.0/) and [`openff-2.x.y` ("Sage")](https://pubs.acs.org/doi/10.1021/acs.jctc.3c00039) small molecule force field lines, including the [most recent force field in each lines](https://github.com/openforcefield/openff-forcefields).
The `SMIRNOFFTemplateGenerator` residue template generator operates in a manner very similar to `GAFFTemplateGenerator`, so we only highlight its differences here.
@@ -235,7 +233,7 @@ force field name, path to an OFFXML force field file, file object, or XML in a
string. An iterable can be provided to the `forcefield` argument to load from
multiple sources if desired. For exapmle:
-```
+```python
# Create a SMIRNOFF residue template generator from an older Sage or Parsley version
smirnoff = SMIRNOFFTemplateGenerator(molecules=molecules, forcefield="openff-1.3.0")
# Request a specific SMIRNOFF force field installed with OpenFF by its full name
@@ -414,7 +412,7 @@ To use [espaloma](https://github.com/choderalab/espaloma) for assigning small mo
**Q:** What is the minimum version of OpenMM required to use this package?
-**A:** You need at least OpenMM 7.4.2 to use the `openmmforcefields` package.
+**A:** You need at least OpenMM 8.5.1 to use the `openmmforcefields` package.
**Q:** Do you support the new [Amber ff19SB protein force field](https://doi.org/10.1021/acs.jctc.9b00591)?
diff --git a/openmmforcefields/generators/system_generators.py b/openmmforcefields/generators/system_generators.py
index b6fd2cf3..c1c6dd58 100644
--- a/openmmforcefields/generators/system_generators.py
+++ b/openmmforcefields/generators/system_generators.py
@@ -20,48 +20,21 @@
class SystemGenerator:
"""
Common interface for generating OpenMM Systems from OpenMM Topology objects
- that may contain both biopolymers (with parameters provided by OpenMM) and small molecules
- (with parameters provided by residue template generators).
+ 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``
.. todo ::
Once Open Force Field Topology objects support residue definitions, we will also be able
to support Open Force Field Topology objects (which carry their own Molecule definitions).
- Parameters
- ----------
- forcefield : openmm.app.ForceField
- The ForceField object used to create new System objects.
- New ffxml files can be read in at any time.
- forcefield_kwargs : dict
- Keyword arguments fed to ``openmm.app.ForceField.createSystem()`` during System generation.
- These keyword arguments can be modified at any time.
- periodic_forcefield_kwargs : dict
- Keyword arguments fed to ``openmm.app.ForceField.createSystem()`` during System generation for
- periodic systems.
- These keyword arguments can be modified at any time.
- nonperiodic_forcefield_kwargs : dict
- Keyword arguments fed to ``openmm.app.ForceField.createSystem()`` during System generation for non-periodic
- systems.
- These keyword arguments can be modified at any time.
- barostat : openmm.MonteCarloBarostat
- If not None, this container holds the barostat parameters to use for newly created System objects.
- molecules : openff.toolkit.topology.Molecule or list, optional, default=None
- Can alternatively be an object (such as an OpenEye OEMol or RDKit Mol or SMILES string) that can be used to
- construct a Molecule.
- Can also be a list of Molecule objects or objects that can be used to construct a Molecule.
- 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
- 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.
+ .. warning :: This API is experimental and subject to change.
"""
def __init__(
@@ -78,23 +51,21 @@ def __init__(
postprocess_system=None,
):
"""
- This is a utility class to generate OpenMM Systems from Open Force Field Topology objects using AMBER
- protein force fields and GAFF small molecule force fields.
-
- .. warning :: This API is experimental and subject to change.
+ Initializes a `SystemGenerator`.
Parameters
----------
forcefields : list of str, optional, default=None
- List of the names of ffxml files that will be used in System creation for the biopolymer.
- small_molecule_forcefield : str, optional, default='openff-2.2.0'
- Small molecule force field to use.
- Must be supported by one of the registered template generators:
- [GAFFTemplateGenerator, SMIRNOFFTemplateGenerator]
- Supported GAFF force fields include 'gaff-2.2.20', 'gaff-2.11', and others.
- (See ``GAFFTemplateGenerator.INSTALLED_FORCEFIELDS`` for a complete list.)
- Supported SMIRNOFF force fields include all installed force fields from Parsley and Sage lines, such as 'openff-1.0.0' and 'openff-2.2.1'.
- (See ``SMIRNOFFTemplateGenerator.INSTALLED_FORCEFIELDS`` for a complete list.)
+ 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, default='openff-2.2.0'
+ 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.
@@ -111,14 +82,12 @@ def __init__(
will be created and
added to each newly created ``System``.
molecules : openff.toolkit.topology.Molecule or list, optional, default=None
- Can alternatively be an object (such as an OpenEye OEMol or RDKit Mol or SMILES string) that can be used
- to construct a Molecule.
- Can also be a list of Molecule objects or objects that can be used to construct a Molecule.
+ 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, optiona, default=None
+ 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.
@@ -268,7 +237,7 @@ def __init__(
@classproperty
def SMALL_MOLECULE_FORCEFIELDS(cls):
- """Return a listof available small molecule force fields"""
+ """Return a list of available small molecule force fields"""
forcefields = list()
from openmmforcefields.generators.template_generators import (
SmallMoleculeTemplateGenerator,
@@ -285,9 +254,7 @@ def add_molecules(self, molecules):
Parameters
----------
molecules : openff.toolkit.topology.Molecule or list, optional, default=None
- Can alternatively be an object (such as an OpenEye OEMol or RDKit Mol or SMILES string) that can
- be used to construct a Molecule.
- Can also be a list of Molecule objects or objects that can be used to construct a Molecule.
+ 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.
"""
@@ -351,9 +318,7 @@ def create_system(self, topology, molecules=None):
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 alternatively be an object (such as an OpenEye OEMol or RDKit Mol or SMILES string) that can be used
- to construct a Molecule.
- Can also be a list of Molecule objects or objects that can be used to construct a Molecule.
+ 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.