Skip to content

Clean up README and docstrings #435

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
epretti merged 1 commit into from
Apr 24, 2026
+25 −62
Merged

Clean up README and docstrings #435

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 5 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand All @@ -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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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?
<br>
**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)?
<br>
Expand Down
75 changes: 20 additions & 55 deletions openmmforcefields/generators/system_generators.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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__(
Expand All @@ -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.
Expand All @@ -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.

Expand Down Expand Up @@ -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,
Expand All @@ -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.
"""
Expand Down Expand Up @@ -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.

Expand Down
Loading