From ba45a360dc537ba31ae26030398459d6e10bbb8d Mon Sep 17 00:00:00 2001 From: Evan Pretti Date: Wed, 1 Apr 2026 10:20:32 -0700 Subject: [PATCH] Update README and SystemGenerator docstring --- README.md | 12 ++- .../generators/system_generators.py | 75 +++++-------------- 2 files changed, 25 insertions(+), 62 deletions(-) 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.