Clean up documentation and deploy automatically by epretti · Pull Request #453 · openmm/openmmforcefields

epretti · 2026-09-04T18:55:00Z

Sets up GitHub Actions to automatically build and deploy the Sphinx documentation to GitHub Pages. This is mostly modeled after the way OpenMM-ML and MLIPOps do their documentation. It also moves a lot of material from the README that should have been in a user guide into an actual user guide.

I don't think this can easily be tested on this repository before we actually merge it to trigger the action. However, I've been testing it on my fork so the output can be previewed at https://epretti.github.io/openmmforcefields.

A gh-pages branch will also need to be set up so the action has somewhere to push to.

for more information, see https://pre-commit.ci

codecov-commenter · 2026-09-04T19:39:31Z

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.48%. Comparing base (fb86b91) to head (873b4d4).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #453   +/-   ##
=======================================
  Coverage   84.48%   84.48%           
=======================================
  Files           5        5           
  Lines         799      799           
=======================================
  Hits          675      675           
  Misses        124      124

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

epretti · 2026-09-14T15:45:55Z

@peastman does this look OK to you? I'd like to get this deployed at some point so I can finish up the tutorial for using OpenMMForceFields I had started working on and include links to the documentation in it.

peastman · 2026-09-14T16:30:05Z

+
+Once installed, the AMBER force fields will be registered in the `amber/` relative path searched by [`openmm.app.ForceField`](http://docs.openmm.org/latest/api-python/generated/openmm.app.forcefield.ForceField.html#openmm.app.forcefield.ForceField).
+
+For example, to specify the newer recommended [`ff14SB`](https://pubs.acs.org/doi/abs/10.1021/acs.jctc.5b00255) 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:


You probably want to update this to ff19SB.

peastman · 2026-09-14T16:31:57Z

+## 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.
+If you're not familiar with this approach to applying parameters to biomolecular systems, please see the [OpenMM User Guide](http://docs.openmm.org/latest/userguide/application.html#force-fields).


This link needs to be updated.

peastman · 2026-09-14T16:32:59Z

+
+## Using AMBER GAFF 1.x and 2.x for small molecules
+
+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 [GAFF](http://ambermd.org/antechamber/gaff.html) versions 1 or 2.


The template generator link needs to be updated.

peastman · 2026-09-14T16:38:33Z

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


I'm not sure what this means. Is it saying that the user specified partial charges will be ignored if it's ever seen that molecule before? That sounds like a bug if it's true.

I think this is the way that it works on account of the molecule caching. Normally one wouldn't add a molecule more than once so I don't think this would be a common issue, but I will verify if this is the actual current behavior and we can decide if it should be changed.

peastman · 2026-09-14T16:43:06Z

+
+## 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.


Another wrong link to the documentation.

peastman · 2026-09-14T16:47:19Z

+
+## Using espaloma to generate 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 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.


peastman · 2026-09-14T16:48:52Z

+
+### 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.2.20 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`](https://open-forcefield-toolkit.readthedocs.io/en/latest/api/generated/openff.toolkit.topology.Topology.html#openff.toolkit.topology.Topology) object:


Here's another place where it's referring to ff14SB as "new".

epretti · 2026-09-14T20:56:24Z

Thanks for finding these. I should have taken a closer look at the content I migrated from the README; it seems to have accumulated some other issues. I've updated and cleaned up some links and text in a few places.

I've also changed the examples showing the use of the template generators to use ff19SB + TIP3P-FB from the main OpenMM distribution. I added a note at the top of the Amber/CHARMM FF section that some standard FFs are bundled with OpenMM, but OpenMMForceFields provides a larger selection; previously I think it sounded too much like one had to install OpenMMForceFields to use those force fields, and users discovering force fields distributed with both packages might have been confused. Hopefully that makes sense. If you have suggestions to make it clearer, please let me know.

peastman

A couple of minor fixes. Otherwise looks good.

peastman · 2026-09-15T00:36:26Z

+Various water models and associated parameters for ions are also included.  For instance, to load the ff14SB force field for proteins, and the TIP3P water model with the [Joung and Cheatham recommended salt models](https://doi.org/10.1021/jp8001614) (`parm/frcmod.ionsjc_tip3p`) and recommended multivalent ion parameters (`parm/frcmod.ions234lm_126_tip3p`):
+```python
+forcefield = ForceField(
+    "amber/protein.ff14SB.xml",


This should be ff19SB.

peastman · 2026-09-15T02:21:03Z

 ```

-To use the [OpenFF's Sage `openff-2.2.1`](https://github.com/openforcefield/openff-forcefields) or a newer version, an update of the [Open Force Field ("Parsley") small molecule force field](https://openforcefield.org/news/introducing-openforcefield-1.0/) instead of GAFF 2.2.20, we would have instead specified `small_molecule_forcefield='openff-2.2.1'`.
+To use, for example, [OpenFF's Sage `openff-2.3.0`](https://github.com/openforcefield/openff-forcefields) instead of GAFF 2.2.20, we would have instead specified `small_molecule_forcefield='openff-2.2.1'`.


Should be small_molecule_forcefield='openff-2.3.0'

epretti and others added 5 commits September 4, 2026 09:47

Test building and deploying docs

2ee7d6b

Debugging

7b34fc4

Updates to documentation building and reorganization

2a4a373

Update action versions

6b151ea

[pre-commit.ci] auto fixes from pre-commit.com hooks

5bd3af6

for more information, see https://pre-commit.ci

peastman reviewed Sep 14, 2026

View reviewed changes

epretti added 2 commits September 14, 2026 13:54

Update user guide links and text

6700a81

Merge branch 'docs' of github.com:epretti/openmmforcefields into docs

873b4d4

peastman reviewed Sep 15, 2026

View reviewed changes


		Once installed, the AMBER force fields will be registered in the `amber/` relative path searched by [`openmm.app.ForceField`](http://docs.openmm.org/latest/api-python/generated/openmm.app.forcefield.ForceField.html#openmm.app.forcefield.ForceField).

		For example, to specify the newer recommended [`ff14SB`](https://pubs.acs.org/doi/abs/10.1021/acs.jctc.5b00255) 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:


		## Using AMBER GAFF 1.x and 2.x for small molecules

		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 [GAFF](http://ambermd.org/antechamber/gaff.html) versions 1 or 2.


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


		## Using espaloma to generate 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 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.


		### 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.2.20 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`](https://open-forcefield-toolkit.readthedocs.io/en/latest/api/generated/openff.toolkit.topology.Topology.html#openff.toolkit.topology.Topology) object:

Uh oh!

Conversation

epretti commented Sep 4, 2026

Uh oh!

codecov-commenter commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

epretti commented Sep 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

epretti commented Sep 14, 2026

Uh oh!

peastman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov-commenter commented Sep 4, 2026 •

edited

Loading