This repository provides support for AMBER, CHARMM, OpenFF, and Espaloma force fields and small molecule parameterization with GAFF, Espaloma, and Open Force Field Toolkit for OpenMM.
AMBER: All major AMBER force fields distributed with AmberTools 20.15 from conda-forge (except ff19SB---see FAQ below), as well as all released GAFF small molecule force fields through 1.81 (GAFF 1.x) and 2.11 (GAFF 2.x).
CHARMM: Non-polarizable protein, nucleic acid, and pre-parameterized small molecule force fields available in in the July 2020 CHARMM36 force field release from the Mackerell website. Note that this conversion has not yet been fully validated.
Open Force Field Initiative force fields: All distributed Open Force Field Initiative force fields, including the openff-1.x.y ("Parsley") and smirnoff99Frosst series of force fields available through the openff-forcefields package. This is now supported in OpenMM 7.5.0 and later.
Espaloma: Currently espaloma-0.3.2 is supported. See our first espaloma paper and our second paper which focuses on protein-ligand systems and beyond.
The openmmforcefields package provides additional AMBER and CHARMM biopolymer force fields, small molecule support through GAFF and the Open Force Field toolkit, and force field conversion tools.
The easiest way to install this package and its requisite dependencies is via conda:
conda install --yes -c conda-forge openmmforcefieldsIf you optionally have the OpenEye Toolkits installed, openmmforcefields will use these to accelerate small molecule parameterization.
Free academic licenses are available for bona fide academic research, while licenses for IP generation are available for a fee.
Support for the SMIRNOFF residue template or system generators requires OpenMM 7.4.2 or later.
This repository contains force fields for use with the OpenMM ForceField class for parameterizing biomolecular systems.
If you're not familiar with this approach to applying parameters to biomolecular systems, please see the OpenMM User Guide.
Once installed, the AMBER force fields will be registered in the amber/ relative path searched by openmm.app.ForceField.
For example, to specify the newer recommended ff14SB force field and accompanying recommended ions and solvent models (corresponding to force fields loaded in LEaP with leaprc.protein.ff14SB), prepend the amber prefix and the .xml suffix:
forcefield = ForceField("amber/protein.ff14SB.xml")To access just the ff14SB force field converted from oldff/leaprc.ff14SB:
forcefield = ForceField("amber/ff14SB.xml")or to specifically access the older (now outdated) ff99SBildn force field converted from oldff/leaprc.ff14SB:
forcefield = ForceField("amber/ff99SBildn.xml")The TIP3P conversion also includes the Joung and Cheatham recommended salt models (parm/frcmod.ionsjc_tip3p) and recommended divalent counterion parameters (parm/frcmod.ions234lm_126_tip3p):
forcefield = ForceField(
"amber/protein.ff14SB.xml",
"amber/tip3p_standard.xml",
"amber/tip3p_HFE_multivalent.xml",
)Similarly, the CHARMM force fields will be registered in the charmm/ relative path.
For example, model system small molecule templates corresponding to amino acids can be accessed with:
forcefield = ForceField("charmm/toppar_all36_prot_model.xml")The openmmforcefields package includes a residue template generator for the OpenMM ForceField class that automatically generates OpenMM residue templates for small molecules lacking parameters using GAFF versions 1 or 2.
The openff-toolkit is used to provide an interface with cheminformatics toolkits to interact with antechamber from the AmberTools package to generate parameters for small molecules.
By default, the openff-toolkit will make use of the free and open source RDKit cheminformatics toolkit that is installed automatically, but will optionally use the OpenEye toolkit if it is installed and licensed.
The OpenEye toolkit is available for free for academics for non-IP-generating academic research.
Generation of OpenMM-compatible parameters for small molecules encountered in an OpenMM Topology is handled through openmmforcefields.generators.GAFFTemplateGenerator.
Because the OpenMM Topology object used by the OpenMM ForceField class does not know the precise chemical identity of molecules represented in the topology---which contain only elements and bonds between them, without stereochemical or bond order information---it is necessary to instruct GAFFTemplateGenerator which small molecules it will encounter in processing the Topology object ahead of time; it then matches these by element and bond pattern.
To do this, it is necessary to specify one or more openff.toolkit.topology.Molecule objects which can easily be created from many different representations of small molecules, including SMILES strings and common molecule storage formats.
There are many ways to create an OpenFF Molecule object from various file formats as well---see the API docs for more details.
If the provided molecule(s) contain nonzero (user-specified) partial charges (stored in the Molecule.partial_charges attribute), those partial charges will be used.
If they do not contain partial charges, the OpenFF Toolkit is used to generate them.
- In
GAFFTemplateGenerator, Antechamber from the AmberTools distribution (which uses thesqmsemiempirical 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.- If OpenEye Toolkits are installed and licensed, OpenEye's Quacpac Toolkit is used to generate AM1-BCC-ELF10 charges. 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/
sqmis used to generate AM1-BCC charges in the same way that it is used inGAFFTemplateGenerator. In this case, the conformers used to generate charges are generated by RDKit.
Note: The Molecule object must have the all protons and stereochemistry explicitly specified, and must match the exact protonation and tautomeric state of the molecule that will be found in your OpenMM Topology object.
The atom ordering need not be the same.
Note: The first time a Molecule is specified, added, or cached, if it lacks partial charges, the automatically generated charges will be cached and reused; if it contains user-specified partial charges, those charges will be used and cached. Adding the molecule again with a different set of charges will have no effect on changing which charges are assigned.
GAFFTemplateGenerator also supports the ability to specify a cache filename, allowing parameters for small molecules to be computed only once and then cached in the specified cache file thereafter.
Create a GAFF template generator for a single molecule (benzene, created from SMILES) and register it with ForceField:
# Create an OpenFF Molecule object for benzene from SMILES
from openff.toolkit import Molecule
molecule = Molecule.from_smiles("c1ccccc1")
# Create the GAFF template generator
from openmmforcefields.generators import (
GAFFTemplateGenerator,
)
gaff = GAFFTemplateGenerator(molecules=molecule)
# Create an OpenMM ForceField object with AMBER ff14SB and TIP3P with compatible ions
from openmm.app import ForceField
forcefield = ForceField(
"amber/protein.ff14SB.xml",
"amber/tip3p_standard.xml",
"amber/tip3p_HFE_multivalent.xml",
)
# Register the GAFF template generator
forcefield.registerTemplateGenerator(gaff.generator)
# You can now parameterize an OpenMM Topology object that contains the specified molecule.
# forcefield will load the appropriate GAFF parameters when needed, and antechamber
# will be used to generate small molecule parameters on the fly.
from openmm.app import PDBFile
pdbfile = PDBFile("t4-lysozyme-L99A-with-benzene.pdb")
system = forcefield.createSystem(pdbfile.topology)The latest available GAFF version is used if none is specified. You can check which GAFF version is in use with
>>> gaff.gaff_version
'2.11'Create a template generator for a specific GAFF version for multiple molecules read from an SDF file:
molecules = Molecule.from_file("molecules.sdf")
gaff = GAFFTemplateGenerator(molecules=molecules, forcefield="gaff-2.11")You can also add molecules to the generator later, even after the generator has been registered:
gaff.add_molecules(molecule)
gaff.add_molecules([molecule1, molecule2])To check which GAFF versions are supported, examine the INSTALLED_FORCEFIELDS attribute:
>>> print(GAFFTemplateGenerator.INSTALLED_FORCEFIELDS)
['gaff-1.4', 'gaff-1.8', 'gaff-1.81', 'gaff-2.1', 'gaff-2.11']You can optionally specify a file that contains a cache of pre-parameterized molecules:
generator = GAFFTemplateGenerator(cache="gaff-molecules.json", forcefield="gaff-1.8")Newly parameterized molecules will be written to the cache, saving time next time these molecules are encountered.
The openmmforcefields package includes a residue template generator for the OpenMM ForceField class that automatically generates OpenMM residue templates for small molecules lacking parameters using the Open Force Field Initiative SMIRNOFFsmall molecule force fields.
This includes the openff-1.x.y ("Parsley") and openff-2.x.y ("Sage") small molecule force field lines, including the most recent force field in each lines.
The SMIRNOFFTemplateGenerator residue template generator operates in a manner very similar to GAFFTemplateGenerator, so we only highlight its differences here.
Create a SMIRNOFF template generator for a single molecule (benzene, created from SMILES) and register it with ForceField:
# Create an OpenFF Molecule object for benzene from SMILES
from openff.toolkit import Molecule
molecule = Molecule.from_smiles("c1ccccc1")
# Create the SMIRNOFF template generator with the default installed force field (openff-2.1.0)
from openmmforcefields.generators import (
SMIRNOFFTemplateGenerator,
)
smirnoff = SMIRNOFFTemplateGenerator(molecules=molecule)
# Create an OpenMM ForceField object with AMBER ff14SB and TIP3P with compatible ions
from openmm.app import ForceField
forcefield = ForceField(
"amber/protein.ff14SB.xml",
"amber/tip3p_standard.xml",
"amber/tip3p_HFE_multivalent.xml",
)
# Register the SMIRNOFF template generator
forcefield.registerTemplateGenerator(smirnoff.generator)
# create a System with the non-bonded settings of mainline OpenFF force fields
# (9 Angstrom cut-off, switching distance applied at 8 Angstrom)
system = forcefield.createSystem(
topology=molecule.to_topology().to_openmm(),
nonbondedCutoff=0.9 * openmm.unit.nanometer,
switchDistance=0.8 * openmm.unit.nanometer,
)The latest official Open Force Field Initiative release (openff-1.2.0 of the "Parsley" small molecule force field) is used if none is specified.
You can check which SMIRNOFF force field is in use with
>>> smirnoff.smirnoff_filename
'/Users/mattthompson/mambaforge/envs/openmmforcefields/lib/python3.11/site-packages/openforcefields/offxml/openff-2.1.0.offxml'Create a template generator for a specific SMIRNOFF force field for multiple molecules read from an SDF file:
molecules = Molecule.from_file("molecules.sdf")
# Create a SMIRNOFF residue template generator from the official openff-1.0.0 release,
# which is installed automatically
smirnoff = SMIRNOFFTemplateGenerator(molecules=molecules, forcefield="openff-1.2.0")
# Create a SMIRNOFF residue template generator from the official smirnoff99Frosst-1.1.0 release,
# which is installed automatically
smirnoff = SMIRNOFFTemplateGenerator(molecules=molecules, forcefield="smirnoff99Frosst-1.2.0")
# Use a local .offxml file instead
smirnoff = SMIRNOFFTemplateGenerator(molecules=molecules, forcefield="local-file.offxml")You can also add molecules to the generator later, even after the generator has been registered:
smirnoff.add_molecules(molecule)
smirnoff.add_molecules([molecule1, molecule2])To check which SMIRNOFF force fields are automatically installed, examine the INSTALLED_FORCEFIELDS attribute:
>>> print(SMIRNOFFTemplateGenerator.INSTALLED_FORCEFIELDS)
['smirnoff99Frosst-1.0.2', 'smirnoff99Frosst-1.0.0', 'smirnoff99Frosst-1.1.0', 'smirnoff99Frosst-1.0.4', 'smirnoff99Frosst-1.0.8', 'smirnoff99Frosst-1.0.6', 'smirnoff99Frosst-1.0.3', 'smirnoff99Frosst-1.0.1', 'smirnoff99Frosst-1.0.5', 'smirnoff99Frosst-1.0.9', 'smirnoff99Frosst-1.0.7', 'ff14sb_off_impropers_0.0.2', 'ff14sb_off_impropers_0.0.1', 'ff14sb_off_impropers_0.0.3', 'tip3p_fb-1.1.0', 'tip3p_fb-1.0.0', 'openff-1.0.1', 'openff-1.1.1', 'openff-1.0.0-RC1', 'opc3', 'opc3-1.0.0', 'openff-2.1.0-rc.1', 'openff-1.2.0', 'openff-1.3.0', 'tip3p-1.0.0', 'opc-1.0.2', 'openff-2.0.0-rc.2', 'opc-1.0.0', 'openff-2.1.0', 'openff-2.0.0', 'tip4p_fb-1.0.1', 'tip3p', 'opc3-1.0.1', 'opc', 'tip3p_fb-1.1.1', 'openff-1.1.0', 'openff-1.0.0', 'openff-1.0.0-RC2', 'tip3p-1.0.1', 'openff-1.3.1', 'openff-1.2.1', 'openff-1.3.1-alpha.1', 'tip4p_fb', 'tip3p_fb', 'tip4p_fb-1.0.0', 'openff-2.0.0-rc.1', 'opc-1.0.1']You can optionally specify a file that contains a cache of pre-parameterized molecules:
smirnoff = SMIRNOFFTemplateGenerator(
cache="smirnoff-molecules.json",
forcefield="openff-1.2.0",
)Newly parameterized molecules will be written to the cache, saving time next time these molecules are encountered.
The openmmforcefields package includes a residue template generator for the OpenMM ForceField class that can automatically generate OpenMM residue templates for small molecules lacking parameters using espaloma via one of its released force fields, provided espaloma and its dependencies are installed.
espaloma uses a graph convolutional model to generate both valence parameters and fast partial charges.
The EspalomaTemplateGenerator residue template generator operates in a manner very similar to GAFFTemplateGenerator, so we only highlight its differences here.
This feature is currently experimental and its API is subject to change.
Create an espaloma template generator for a single molecule (benzene, created from SMILES) and register it with ForceField:
# Create an OpenFF Molecule object for benzene from SMILES
from openff.toolkit import Molecule
molecule = Molecule.from_smiles("c1ccccc1")
# Create the SMIRNOFF template generator with the released espaloma-0.3.2 force field
from openmmforcefields.generators import (
EspalomaTemplateGenerator,
)
espaloma = EspalomaTemplateGenerator(molecules=molecule, forcefield="espaloma-0.3.2")
# Create an OpenMM ForceField object with AMBER ff14SB and TIP3P with compatible ions
from openmm.app import ForceField
forcefield = ForceField(
"amber/protein.ff14SB.xml",
"amber/tip3p_standard.xml",
"amber/tip3p_HFE_multivalent.xml",
)
# Register the SMIRNOFF template generator
forcefield.registerTemplateGenerator(espaloma.generator)Create a template generator for a specific espaloma force field for multiple molecules read from an SDF file:
molecules = Molecule.from_file("molecules.sdf")
# Create an espaloma residue template generator from the espaloma-0.3.2 release,
# retrieving it automatically from GitHub release artifacts
espaloma = EspalomaTemplateGenerator(molecules=molecules, forcefield="espaloma-0.3.2")
# Create an espaloma residue template generator from an espaloma model retrieved from a URL
espaloma = EspalomaTemplateGenerator(
molecules=molecules,
forcefield="https://github.com/choderalab/espaloma/releases/download/0.3.2/espaloma-0.3.2.pt",
)
# Create an espaloma residue template generator from an espaloma model stored in a local file
espaloma = EspalomaTemplateGenerator(
molecules=molecules,
forcefield="/path/to/espaloma-0.3.2.pt",
)You can also add molecules to the generator later, even after the generator has been registered:
smirnoff.add_molecules(molecule)
smirnoff.add_molecules([molecule1, molecule2])You can optionally specify a file that contains a cache of pre-parameterized molecules:
espaloma = EspalomaTemplateGenerator(
cache="espaloma-molecules.json",
forcefield="espaloma-0.3.2",
)Newly parameterized molecules will be written to the cache, saving time next time these molecules are encountered.
The openmmforcefields package provides the openmmforcefields.generators.SystemGenerator class that handles management of common force fields transparently for you.
Using SystemGenerator to automate the use of AMBER force fields with GAFF, OpenFF, or espaloma for small molecule parameterization
Here's an example that uses GAFF 2.11 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
forcefield_kwargs = {
"constraints": app.HBonds,
"rigidWater": True,
"removeCMMotion": False,
"hydrogenMass": 4 * unit.amu,
}
# Initialize a SystemGenerator using GAFF
from openmmforcefields.generators import SystemGenerator
system_generator = SystemGenerator(
forcefields=[
"amber/ff14SB.xml",
"amber/tip3p_standard.xml",
],
small_molecule_forcefield="gaff-2.11",
forcefield_kwargs=forcefield_kwargs,
cache="db.json",
)
# Create an OpenMM System from an OpenMM Topology object
system = system_generator.create_system(openmm_topology)
# Alternatively, create an OpenMM System from an OpenMM Topology object and a list of OpenFF Molecule objects
molecules = Molecule.from_file("molecules.sdf", file_format="sdf")
system = system_generator.create_system(openmm_topology, molecules=molecules)Parameterized molecules are cached in db.json.
Parameters for multiple force fields can be held in the same cache file.
By default, SystemGenerator will use PME for periodic systems and NoCutoff for non-periodic systems.
You can modify this behavior with the optional periodic_forcefield_kwargs and nonperiodic_forcefield_kwargs arguments, which are used to update forcefield_kwargs depending on whether the system is periodic or non-periodic:
from openmm import app
system_generator = SystemGenerator(
forcefields=[
"amber/ff14SB.xml",
"amber/tip3p_standard.xml",
],
periodic_forcefield_kwargs={"nonbondedMethod": app.LJPME},
nonperiodic_forcefield_kwargs={"nonbondedMethod": app.CutoffNonPeriodic},
)To use the Open Force Field openff-1.2.0, an update of the Open Force Field ("Parsley") small molecule force field instead of GAFF 2.11, we would have instead specified small_molecule_forcefield='openff-1.2.0'.
To use espaloma for assigning small molecule parameters, for example with the espaloma-0.3.2 model released with the espaloma preprint, you can specify small_molecule_forcefield='espaloma-0.3.2'.
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.
Q: Do you support the new Amber ff19SB protein force field?
A: ParmEd, which is used to convert these force fields to OpenMM format, does not currently support the conversion of AMBER CMAP forces to OpenMM, so we do not yet support this force field, but hope to add support soon.
Q: Do you plan to support other small molecule force fields?
A: If there are other free and open source conda-installable tools for generating parameters for other AMBER- or CHARMM-compatible force fields, we are happy to add support for them!
See the corresponding directories for information on how to use the provided conversion tools:
amber/- AMBER force fields and conversion toolscharmm/- CHARMM force fields and conversion tools
This release brings back GAFF force feild support for all versions of OpenMM previously supported.
Additionally, we now use the output of parmchk2 for all GAFF parameters.
Previously we used gaff.dat + parmchk2 output to generate forcefield parameters.
Functionally this doesn't change the end user experience but means we do not need to create new forcefield XML files for newer GAFF versions and now support whatever GAFF versions that parmchk2 supports for the installed AmberTools version.
The XML files in openmmforcefields/ffxml/amber/gaff/ffxml may be removed in a future release.
This release effectively reverts the changes in 0.13.0. This release is only compatible with OpenMM 8.1.2. No other changes were made.
This release temporarily removes GAFFTemplateGenerator because of packaging incompatibilities with AmberTools 23. This functionality is planned to be re-introduced in 0.14.0.
This release is expected to work with Python 3.10-3.12.
Other changes include
- The default force field of
SystemGeneratorwas updated fromopenff-1.0.0(code name Parsley) toopenff-2.0.0(code name Sage).
See our 0.12.0 release page for more details.
This release adds support for using espaloma to apply small molecule parameters.
- (PR #182) Add support for espaloma small molecule parameters
This release adds support for the AMBER GLYCAM force field supporting glycans and updates imports for OpenMM 7.6.
This release utilizes the new openforcefield 0.9.0 toolkit now distributed through conda-forge.
This release contains updated CHARMM and AMBER force fields for use with OpenMM 7.5.0 and the new openforcefield 0.9.0 toolkit, both now distributed through conda-forge.
- Amber force fields were updated to versions distributed with AmberTools 20.15
- Added AMBER
phosaa14SBparameters for phosphorylated amino acids - CHARMM force fields were updated to July 2020 CHARMM additive force field release
- (PR #128) Update README for openff-1.2.0 and use openforcefield 0.7.1 toolkit API for identifying installed force fields
- (PR #127) Fixes a bug where the wrong path was imported for logging; improves docstrings.
- (PR #121) Add compatibility with
openforcefield 0.7.0
0.7.3 Bugfix release: Compatibility with openforcefield toolkit 0.7.0 and auto-detection of installed openforcefield force fields
- (PR #119) Handle
Nonepartial charges in openforcefieldMoleculeobjects (needed inopenforcefieldtoolkit 0.7.0) - (PR #120) Auto-detect installed SMIRNOFF force fields
- Raise a
ValueErrorifSystemGeneratorreceives anonbondedMethodkey inforcefield_kwargs; these should go intoperiodic_forcefield_kwargsornonperiodic_forcefield_kwargs.
- When using the OpenEye toolkit, some molecules failed to charge with GAFF. See openforcefield/openff-toolkit#492
- Removed most
perses_jacs_systems, updating the remaining ones with inputs used in AMBER-TI publication, https://pubs.acs.org/doi/10.1021/acs.jcim.9b00105 - Fix a bug where some molecules with pyramidal atoms would cause exceptions when read from cache
0.7.0 User-specified partial charges, SystemGenerator support for periodic and non-periodic topologies, and minor bugfixes
- If
Moleculeobjects contain nonzero partial charges, these are used instead of generating new partial charges - Fix bug in default
periodic_forcefield_kwargsandnonperiodic_forcefield_kwargs
- Fix examples in the
README.md - Fix
GAFFTemplateGenerator.gaff_major_version - Fix incorrect default SMIRNOFF force field, which is now
openff-1.0.0(was previouslysmirnoff99Frosst-1.1.0) - Add
SystemGenerator.SMALL_MOLECULE_FORCEFIELDSconvenience property to list available small molecule force fields SystemGeneratorAPI changed to support both periodic and non-periodicTopologyobjects for the same generator
This release provides updated support for AMBER biopolymer force fields (from AmberTools 19.9) and small molecule support with GAFF 1.x and 2.x, along with experimental support for the new Open Force Field Initiative SMIRNOFF force fields.
AMBER: All major AMBER force fields distributed with AmberTools 19.9 (except ff19SB---see FAQ below), as well as all released GAFF small molecule force fields through 1.81 (GAFF 1.x) and 2.11 (GAFF 2.x).
CHARMM: Non-polarizable protein, nucleic acid, and pre-parameterized small molecule force fields available in in the Aug 2015 CHARMM36 force field release from the Mackerell website. Note that this conversion has not yet been fully validated.
Open Force Field Initiative force fields: All distributed Open Force Field Initiative force fields, including the smirnoff99Frosst series and openff-1.0.0 ("Parsley"). This support is experimental since it requires a development version of OpenMM 7.5.0.
Residue template generators are provided for both GAFF (GAFFTemplateGenerator) and SMIRNOFF (SMIRNOFFTemplateGenerator).
This release also contains an experimental new SystemGenerator for managing biopolymer and small molecule force field System creation via a unified API.
This release contains updated CHARMM and AMBER force fields for use with OpenMM 7.3.1.
- Amber force fields were updated to versions distributed with AmberTools 18.0
- Release version metadata in Amber force fields was corrected
- CHARMM force fields were updated to July 2018 CHARMM additive force field release
- Experimental Amber GAFF residue template generator released (requires OpenEye Toolkit)
This release contains updated CHARMM and AMBER force fields distributed with OpenMM 7.3.0.
Amber force fields were converted from the AmberTools 18 package, while CHARMM force fields were converted from the July 2016 update.
This release contains the force fields distributed with OpenMM 7.2.0 rc2
This release contains the force fields distributed with OpenMM 7.2.0 rc1
This prerelease allows installation of AmberTools 16 via conda.