Skip to content

Commit

Permalink
fix badges + readme updates (#309)
Browse files Browse the repository at this point in the history 
* fix badges

* updated espaloma references to 0.3.2

* added link to release notes to README

* Update README.md

Co-authored-by: Matt Thompson <[email protected]>

* added link to releases page on github

* update espaloma citations

---------

Co-authored-by: Matt Thompson <[email protected]>
  • Loading branch information
@mikemhenry @mattwthompson
mikemhenry and mattwthompson authored Nov 1, 2023
1 parent 9eb2e49 commit 637d551
Showing 1 changed file with 20 additions and 14 deletions.
34 changes: 20 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
[![CI](https://github.com/openmm/openmmforcefields/workflows/CI/badge.svg?branch=master)](https://github.com/openmm/openmmforcefields/actions?query=workflow%3ACI)
[![conda-forge badge](https://anaconda.org/conda-forge/openmmforcefields/badges/installer/conda.svg)](https://anaconda.org/conda-forge/openmmforcefields)
[![conda-forge downloads](https://anaconda.org/conda-forge/openmmforcefields/badges/downloads.svg)](https://anaconda.org/conda-forge/openmmforcefields)
[![CI](https://github.com/openmm/openmmforcefields/actions/workflows/ci.yaml/badge.svg)](https://github.com/openmm/openmmforcefields/actions/workflows/ci.yaml)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/openmmforcefields.svg)](https://anaconda.org/conda-forge/openmmforcefields)
[![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/openmmforcefields.svg)](https://anaconda.org/conda-forge/openmmforcefields)
[![DOI](https://zenodo.org/badge/70107487.svg)](https://zenodo.org/badge/latestdoi/70107487)

# AMBER and CHARMM force fields for OpenMM
# AMBER, CHARMM, OpenFF, and Espaloma 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.
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.

## Supported force fields

Expand All @@ -15,6 +15,8 @@ This repository provides support for AMBER and CHARMM force fields and small mol

**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-1.x.y` ("Parsley")](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.

**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).

# Using the force fields

## Installation
Expand Down Expand Up @@ -229,6 +231,7 @@ Newly parameterized molecules will be written to the cache, saving time next tim
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 can automatically generate OpenMM residue templates for small molecules lacking parameters using [espaloma](https://github.com/choderalab/espaloma) via one of its released force fields, provided `espaloma` and its dependencies are installed.
`espaloma` uses a [graph convolutional model](https://arxiv.org/abs/2010.01196) 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.**
Expand All @@ -240,9 +243,9 @@ Create an espaloma template generator for a single molecule (benzene, created fr
# 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.2.0 force field
# 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.2.2')
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')
Expand All @@ -252,13 +255,13 @@ forcefield.registerTemplateGenerator(espaloma.generator)
Create a template generator for a specific espaloma force field for multiple molecules read from an SDF file:
```python
molecules = Molecule.from_file('molecules.sdf')
# Create an espaloma residue template generator from the espaloma-0.2.0 release,
# 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.2.2')
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.2.2/espaloma_0.2.2.pt')
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.2.2.pt')
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:
```python
Expand All @@ -267,7 +270,7 @@ smirnoff.add_molecules([molecule1, molecule2])
```
You can optionally specify a file that contains a cache of pre-parameterized molecules:
```python
espaloma = EspalomaTemplateGenerator(cache='espaloma-molecules.json', forcefield='espaloma-0.2.2')
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.

Expand Down Expand Up @@ -306,7 +309,7 @@ system_generator = SystemGenerator(forcefields=['amber/ff14SB.xml', 'amber/tip3p

To use the [Open Force Field `openff-1.2.0`](https://github.com/openforcefield/openff-forcefields), an update of the [Open Force Field ("Parsley") small molecule force field](https://openforcefield.org/news/introducing-openforcefield-1.0/) instead of GAFF 2.11, we would have instead specified `small_molecule_forcefield='openff-1.2.0'`.

To use [espaloma](https://github.com/choderalab/espaloma) for assigning small molecule parameters, for example with the [`espaloma-0.2.0` model](https://github.com/choderalab/espaloma/releases/tag/0.2.0) released with the [espaloma preprint](https://arxiv.org/abs/2010.01196), you can specify `small_molecule_forcefield='espaloma-0.2.0'`.
To use [espaloma](https://github.com/choderalab/espaloma) for assigning small molecule parameters, for example with the [`espaloma-0.3.2` model](https://github.com/choderalab/espaloma/releases/tag/0.3.2) released with the [espaloma preprint](https://arxiv.org/abs/2307.07085), you can specify `small_molecule_forcefield='espaloma-0.3.2'`.

# Frequently Asked Questions (FAQ)

Expand All @@ -329,7 +332,10 @@ See the corresponding directories for information on how to use the provided con
* `amber/` - AMBER force fields and conversion tools
* `charmm/` - CHARMM force fields and conversion tools

# Changelog
# [Changelog](https://github.com/openmm/openmmforcefields/releases)

## 0.12.0 Updates for espaloma and support a offxml string in SystemGenerator
See our [0.12.0 release page](https://github.com/openmm/openmmforcefields/releases/tag/0.12.0) for more details.

## 0.11.0 Support for espaloma small molecule parameters
This release adds support for using [espaloma](https://github.com/choderalab/espaloma) to apply small molecule parameters.
Expand Down

0 comments on commit 637d551

Please sign in to comment.