forcefill

Turn ligands into a ready-to-use OpenMM force-field XML — either the non-standard residues (ligands, cofactors, hetero molecules) found in a PDB, or ligand files on their own. Parameters come from AmberTools (antechamber + parmchk2) via ParmEd, from OpenFF Sage or Espaloma via openmmforcefields, or — for CHARMM — by converting the CGenFF stream file ParamChem gave you.

The output is a plain ffxml file you load alongside the standard force fields:

ff = ForceField("amber14-all.xml", "amber14/tip3p.xml", "extras.xml")
system = ff.createSystem(pdb.topology)

Two ways in, depending on whether you have a structure:

from forcefill import build_forcefield_xml, build_ligand_xml

# A complex: find what amber14 cannot match and parameterize it
build_forcefield_xml("complex.pdb", "extras.xml")

# Just the ligand, no structure anywhere
build_ligand_xml("benzamidinium.sdf", "ben.xml")

What it does

1. Identify — ForceField.getUnmatchedResidues finds every residue the base force field (default: amber14-all.xml + amber14/tip3p.xml) has no template for.
2. Classify — only chemistry a stand-alone GAFF treatment is actually valid for gets parameterized; see What gets skipped, and why.
3. Check — before anything expensive: the net charge is read from the ligand file, a supplied file is confirmed to be the same molecule as the residue, and the geometry is checked for the faults that produce NaN energies.
4. Parameterize — each unique residue through antechamber (GAFF2 atom types, AM1-BCC charges → .mol2) and parmchk2 (missing parameters → .frcmod), through OpenFF with backend="smirnoff", through the Espaloma graph network with backend="espaloma", or from a CGenFF stream file with backend="charmm".
5. Assemble — one XML per residue, plus one combined XML.
6. Validate — an openmm.System is built from base force field + new XML for every parameterized residue on its own (and for the whole input when nothing was skipped), so a template that does not match its residue fails loudly here instead of at simulation time. minimize=True additionally catches parameters that are unphysical rather than merely absent (see Checks).

Documentation

Full documentation is at forcefill.readthedocs.io:

Installation

AmberTools is conda-only, so conda-forge is the recommended route:

conda env create -f environment.yml
conda activate forcefill
pip install -e . --no-deps

Or into an existing environment:

conda install -c conda-forge openmm parmed ambertools
pip install forcefill

Requires Python ≥ 3.10. Two things are not ordinary dependencies: AmberTools is not a Python package (the antechamber and parmchk2 executables must be on PATH for the gaff backend), and espaloma is optional because it pulls in PyTorch. The full list, and the reason the openmmforcefields floor is 0.16, is in the installation guide.

Quickstart

from forcefill import build_forcefield_xml

result = build_forcefield_xml(
    "complex.pdb",
    "extras.xml",
    net_charges={"LIG": -1},  # essential for sensible AM1-BCC charges
    clean_structure=True,  # drop water, buffer ions and crystallization additives
)
print(result.parameterized)  # ['LIG']
print(result.skipped)  # {'ZN': 'monatomic species - ...'}

then simulate with:

from openmm import app

pdb = app.PDBFile("complex.pdb")
ff = app.ForceField("amber14-all.xml", "amber14/tip3p.xml", "extras.xml")
system = ff.createSystem(pdb.topology)

result also reports the per-residue XML files (result.residue_xmls), the skip reasons (result.skipped), and the directory holding every intermediate file (result.workdir) for inspection — pass cleanup=True to remove it on success.

More, including per-ligand settings and the other three backends, in the guide.

Development

conda env create -f environment.yml && conda activate forcefill
pip install -e . --no-deps
pytest -m "not integration and not smirnoff"   # fast hermetic tests only
pytest                                         # everything, including real antechamber and OpenFF

Style is enforced by ruff (pip install -e '.[dev]' && pre-commit install).

The docs build is pip-only and separate from the conda environment — see Contributing, which also has the release process.

Changelog

Every release is described in CHANGELOG.md. The public API is everything exported from forcefill/__init__.py, and it follows semantic versioning from 1.0.0 on.

Roadmap

• A forcefill command-line interface — build_ligand_xml is the shape one wants.
• Caching, so re-runs into the same workdir skip finished antechamber jobs — and finished SMIRNOFF/Espaloma templates, which openmmforcefields' own cache= cannot help with on the code path forcefill uses.
• Covalently bound ligands. Still skipped, and deliberately: a stand-alone treatment of a polymer-linked residue is wrong whichever backend produces it.

License

MIT — see LICENSE.