openmmforcefields/README.md

AMBER and CHARMM force fields for OpenMM

Support for small molecule parameterization and additional AMBER and CHARMM force fields for OpenMM.

Supported force fields

AMBER: All major AMBER force fields distributed with AmberTools 18.0, as well as the GAFF small molecule force fields through 1.81 and 2.11

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

Open Force Field Initiative force fields: All distributed Open Force Field Initiative force fields, including the smirnoff99Frosst series and openforcefield-1.0.0 ("Parsley"). Newer parameter sets can be obtained by simply updating the openforcefields package with

conda update openforcefield

Using the force fields

Installation

The openmm-forcefields 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 -c omnia openmm-forcefields

Using the AMBER and CHARMM biopolymer force fields

Using the AMBER force fields

Once installed, the AMBER force fields will be registered in the amber/ relative path searched by simtk.openmm.app.ForceField. For example, to specify the 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.xml')

Using the CHARMM force fields

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')

Using AMBER GAFF 1/2 for small molecules

The openmm-forcefields 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 openforcefield 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 openforcefield 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 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 openforcefield.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 openforcefield Molecule object from various file formats as well---see the API docs for more details.

The openforcefield toolkit charging method Molecule.compute_partial_charges_am1bcc is used to assign partial charges. The canonical AM1-BCC charging method is used to assign ELF10 charges if the OpenEye Toolkit is available. If not, antechamber -c bcc from the [AmberTools]](http://ambermd.org/AmberTools.php) distribution (which uses the sqm semiempirical quantum chemical package) is used to assign AM1-BCC charges.

Note: The molecule you specify 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.

GAFFTemplateGenerator also supports the ability to specify a JSON cache file, allowing parameters for small molecules to be computed only once and then cached thereafter.

Examples using GAFFTemplateGenerator to generate small molecule GAFF parameters

Create a template generator for GAFF for a single molecule (benzene, created from SMILES) and register it with ForceField:

from openforcefield.topology import Molecule
molecule = Molecule.from_smiles('c1ccccc1')
from openmoltools.forcefield_generators import GAFFTemplateGenerator
gaff = GAFFTemplateGenerator(molecules=molecule, gaff_version='1.81')
from simtk.openmm.app import ForceField
forcefield = ForceField(gaff.gaff_xml_filename, 'amber14-all.xml', 'tip3p.xml')
forcefield.registerTemplateGenerator(gaff)

Create a template generator for GAFF2 for multiple molecules read from a file:

molecules = Molecule.from_file('molecules.sdf')
gaff = OEGAFFTemplateGenerator(molecules=molecules, gaff_version='2.11')

You can also add molecules later on after the generator has been registered:

gaff.add_molecules(molecule)
gaff.add_molecules([molecule1, molecule2])

To check which GAFF versions are supported, check the SUPPORTED_GAFF_VERSIONS attribute:

>>> print(GAFFTemplateGenerator.SUPPORTED_GAFF_VERSIONS)
['1.4', '1.8', '1.81', '2.1', '2.11']

You can optionally create or use a tiny database cache of pre-parameterized molecules:

gaff = GAFFTemplateGenerator(cache='gaff-molecules.json', gaff_version='1.80')

Newly parameterized molecules will be written to the cache, saving time next time!

Automating force field management with SystemGenerators

The openmm-forcefields package provides several openmmforcefields.generators.SystemGenerator subclasses that handle management of common force fields transparently for you.

Examples using GAFFSystemGenerator to automate the use of AMBER force fields with GAFF 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:

# Initialize a SystemGenerator
from openmmforcefields.generators import GAFFSystemGenerator
system_generator = GAFFSystemGenerator(forcefields=['amber/ff14SB.xml', 'amber/tip3p.xml'], gaff_version='2.11', cache='gaff-2.11.json')
# Create an OpenMM System from an Open Force Field toolkit Topology object
system = system_generator.create_system(topology)

Parameterized molecules are cached in gaff-2.11.json.

Examples using SMIRNOFFSystemGenerator to automate the use of AMBER force fields with SMIRNOFF for small molecule parameterization

Here's an example that uses the Open Force Field openforcefield-1.0.0 ("Parsley") force field 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:

# Initialize a SystemGenerator
from openmmforcefields.generators import GAFFSystemGenerator
system_generator = GAFFSystemGenerator(forcefields=['amber/ff14SB.xml', 'amber/tip3p.xml'], smirnoff='openforcefield-1.0.0', cache='openforcefield.json')
# Create an OpenMM System from an Open Force Field toolkit Topology object
system = system_generator.create_system(topology)

Parameterized molecules are cached in openforcefield.json.

Frequently Asked Questions (FAQ)

Q: What is the minimum version of OpenMM required to use this package?

A: You need at least OpenMM 7.4.1 to use the openmm-forcefields 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.

Converting AMBER and CHARMM force fields to OpenMM ffxml files

See the corresponding directories for information on how to use the provided conversion tools:

• amber/ - AMBER force fields and conversion tools
• charmm/ - CHARMM force fields and conversion tools

Changelog

0.6.0 Force fields for OpenMM 7.4.1 and GAFF support

This release contains updated CHARMM and AMBER force fields for use with OpenMM 7.4.1.

• Amber force fields were updated to the versions distributed with AmberTools 18.0.
• Support for GAFF via antechamber and the openforcefield toolkit.

0.5.0 Force fields for OpenMM 7.3.1

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)

0.4.0 Force fields for OpenMM 7.3.0

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.

0.3.0 Force fields for OpenMM 7.2.0 rc2

This release contains the force fields distributed with OpenMM 7.2.0 rc2

0.2.0 Forcefields for OpenMM 7.2.0 rc1

This release contains the force fields distributed with OpenMM 7.2.0 rc1

0.1.0 Conda-installable AMBER force fields

This prerelease allows installation of AmberTools 16 via conda.