openmm/openmmforcefields openmm/openmmforcefields

  • Stars
    star
    252
  • Rank 161,312 (Top 4 %)
  • Language
    Python
  • License
    Other
  • Created about 8 years ago
  • Updated about 2 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
openmm/openmmforcefields
github

openmm

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

CHARMM and AMBER forcefields for OpenMM (with small molecule support)

CI conda-forge badge conda-forge downloads DOI

AMBER and CHARMM force fields for OpenMM

This repository provides support for AMBER and CHARMM force fields and small molecule parameterization with GAFF and the Open Force Field Toolkit for OpenMM.

Supported force fields

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.

Using the force fields

Installation

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 openmmforcefields

If 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.

Using the AMBER and CHARMM biopolymer force fields

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.

Using the AMBER force fields

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

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.x and 2.x for small molecules

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.

Cheminformatics toolkits

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.

On-the-fly template generation for small molecules

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.

Specifying molecules

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.

Partial charges for small molecules

If the provided molecule(s) contain nonzero (user-specified) partial charges, they will be used. If they do not contain partial charges, the openff-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 from the AmberTools distribution (which uses the sqm semiempirical quantum chemical package) is used to assign AM1-BCC charges (antechamber -c bcc).

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.

Caching

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.

Examples using GAFFTemplateGenerator to generate small molecule GAFF parameters

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.topology 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

>>> generator.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.80')

Newly parameterized molecules will be written to the cache, saving time next time these molecules are encountered.

Using the Open Force Field Initiative SMIRNOFF small molecule force fields

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 SMIRNOFF small molecule force fields. This includes the openff-1.0.0 ("Parsley") small molecule force field, as well as newer versions of this force field.

The SMIRNOFFTemplateGenerator residue template generator operates in a manner very similar to GAFFTemplateGenerator, so we only highlight its differences here.

Examples using SMIRNOFFTemplateGenerator to generate small molecule SMIRNOFF parameters

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.topology import Molecule
molecule = Molecule.from_smiles('c1ccccc1')
# Create the SMIRNOFF template generator with the default installed force field (openff-1.0.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)

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/choderaj/Library/Caches/Python-Eggs/openforcefields-1.0.0-py3.7.egg-tmp/openforcefields/offxml/openff-1.0.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)
['openff-1.0.1', 'openff-1.1.1', 'openff-1.0.0-RC1', 'openff-1.2.0', 'openff-1.1.0', 'openff-1.0.0', 'openff-1.0.0-RC2', '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']

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.

Using espaloma to generate small molecule force fields

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.

Examples using EspalomaTemplateGenerator to generate small molecule parameters with espaloma

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.topology import Molecule
molecule = Molecule.from_smiles('c1ccccc1')
# Create the SMIRNOFF template generator with the released espaloma-0.2.0 force field
from openmmforcefields.generators import EspalomaTemplateGenerator
espaloma = EspalomaTemplateGenerator(molecules=molecule, forcefield='espaloma-0.2.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.2.0 release,
# retrieving it automatically from GitHub release artifacts
espaloma = EspalomaTemplateGenerator(molecules=molecules, forcefield='espaloma-0.2.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.2.2/espaloma_0.2.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.2.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.2.2')

Newly parameterized molecules will be written to the cache, saving time next time these molecules are encountered.

Automating force field management with SystemGenerator

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.2.0 model released with the espaloma preprint, you can specify small_molecule_forcefield='espaloma-0.2.0'.

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.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!

Converting AMBER and CHARMM 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.11.0 Support for espaloma small molecule parameters

This release adds support for using espaloma to apply small molecule parameters.

  • (PR #182) Add support for espaloma small molecule parameters

0.10.0 Updates for OpenMM 7.6 and AMBER GLYCAM addition

This release adds support for the AMBER GLYCAM force field supporting glycans and updates imports for OpenMM 7.6.

0.9.0 Updates for openforcefield 0.9.0 toolkit

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.

0.8.0 Updates for openforcefield 0.7.1 toolkit

  • (PR #128) Update README for openff-1.2.0 and use openforcefield 0.7.1 toolkit API for identifying installed force fields

0.7.5 Bugfix release

  • (PR #127) Fixes a bug where the wrong path was imported for logging; improves docstrings.

0.7.4 Bugfix release to ensure compatibility with openforcefield toolkit 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 None partial charges in openforcefield Molecule objects (needed in openforcefield toolkit 0.7.0)
  • (PR #120) Auto-detect installed SMIRNOFF force fields

0.7.2 Bugfix release: More error checking; OpenMM 7.4.2 minimum version requirement

  • Raise a ValueError if SystemGenerator receives a nonbondedMethod key in forcefield_kwargs; these should go into periodic_forcefield_kwargs or nonperiodic_forcefield_kwargs.

0.7.1 Bugfix release: Fix GAFF AM1-BCC charging bug for some molecules

0.7.0 User-specified partial charges, SystemGenerator support for periodic and non-periodic topologies, and minor bugfixes

  • If Molecule objects contain nonzero partial charges, these are used instead of generating new partial charges
  • Fix bug in default periodic_forcefield_kwargs and nonperiodic_forcefield_kwargs

0.6.1 Updated README and minor bugfixes

  • 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 previously smirnoff99Frosst-1.1.0)
  • Add SystemGenerator.SMALL_MOLECULE_FORCEFIELDS convenience property to list available small molecule force fields
  • SystemGenerator API changed to support both periodic and non-periodic Topology objects for the same generator

0.6.0 Updated AMBER force fields (AmberTools 19.9) and small molecule support via GAFF

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.

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.

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.

More Repositories

1

openmm

OpenMM is a toolkit for molecular simulation using high performance GPU code.
C++
1,484
star
2

pdbfixer

PDBFixer fixes problems in PDB files
Python
465
star
3

openmm-torch

OpenMM plugin to define forces with neural networks
C++
180
star
4

spice-dataset

A collection of QM data for training potential functions
Python
150
star
5

NNPOps

High-performance operations for neural network potentials
C++
81
star
6

openmm-ml

High level API for using machine learning models in OpenMM simulations
Python
80
star
7

openmm-plumed

OpenMM plugin to interface with PLUMED
C++
59
star
8

openmm-setup

An application for configuring and running simulations with OpenMM
HTML
53
star
9

openmm-cookbook

The OpenMM Cookbook and Tutorials
Jupyter Notebook
38
star
10

openmm-tensorflow

OpenMM plugin to define forces with neural networks
C++
31
star
11

openmm_workshops

Jupyter Notebook
31
star
12

openmmexampleplugin

An example of how to write a plugin for OpenMM
C++
29
star
13

spice-models

Models trained on the SPICE dataset
Python
10
star
14

openmm-xtb

OpenMM plugin to interface with XTB
C++
10
star
15

openmm-tensorrt

OpenMM plugin to define forces with a TensorRT graph
C++
6
star
16

nutmeg

The Nutmeg machine learning models
Python
5
star
17

openmm-org

Content of https://openmm.org
Vue
4
star
18

openmm-wheels

Shell
3
star
19

openmm-feedstock

Smithy feedstock to run packaging experiments with conda & openmm. For released builds, check the feedstock on Conda Forge: https://github.com/conda-forge/openmm-feedstock
Shell
1
star