forcefill 1.0.0__tar.gz

forcefill-1.0.0/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to forcefill are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the version numbers
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html): the public API
+is everything exported from `forcefill/__init__.py`, so a breaking change to any
+of it requires a major bump.
+
+## [Unreleased]
+
+## [1.0.0] - 2026-09-18
+
+First release. The API below is now covered by the compatibility promise above.
+
+### Added
+
+- **`build_forcefield_xml(pdb_file, output_xml, ...)`** — takes a PDB, finds
+  every residue the base force field has no template for
+  (`ForceField.getUnmatchedResidues`), parameterizes the ones a stand-alone
+  small-molecule treatment is valid for, and writes one OpenMM ffxml you load
+  alongside the standard force fields. Returns a `ParameterizationResult`
+  carrying the per-residue XMLs, the skipped residues with their reasons, and
+  the working directory.
+- **`build_ligand_xml(ligands, output_xml, ...)`** — the same pipeline for
+  ligands with no structure at all, from SDF, MOL2, SMILES or a `LigandSpec`,
+  singly or as a batch.
+- **Four backends**, selected with `backend=` globally or per ligand:
+  - `"gaff"` (default) — `antechamber` GAFF2 atom types with AM1-BCC charges,
+    plus `parmchk2` for the missing parameters.
+  - `"smirnoff"` — OpenFF, default `openff-2.2.1`, through
+    `openmmforcefields`. Accepts a released force field by name, a local
+    OFFXML, or a layered list of both.
+  - `"espaloma"` — the Espaloma graph network, default `espaloma-0.3.2`.
+    Optional dependency; it pulls in PyTorch.
+  - `"charmm"` — converts the CGenFF stream file ParamChem returns, against
+    `CHARMM_BASE_FORCEFIELD`. Handles the LJ conversion that ParmEd's own
+    CHARMM writer gets wrong.
+  Backends may be mixed across residues in one run; the resulting XMLs merge
+  into a single loadable file.
+- **`LigandSpec`** — per-ligand settings (input file or SMILES, net charge,
+  multiplicity, backend, force field, CHARMM files, atom type, charge method,
+  extra `antechamber` arguments), overriding the run-wide defaults.
+- **BespokeFit support** — a BespokeFit OFFXML is accepted wherever a SMIRNOFF
+  force field is, with checks that the fit actually belongs to the molecule it
+  is being applied to, so bought QC is not silently applied to the wrong ligand.
+- **Preflight checks**, 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 it stands in for, and the geometry is screened for the faults that
+  produce NaN energies.
+- **Post-parameterization validation** — 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 at build time instead of at simulation time.
+  `minimize=True` additionally catches parameters that are unphysical rather
+  than merely absent. `validate_forcefield_xml`, `minimize_with_forcefield_xml`
+  and `add_extra_particles` are public for use on their own.
+- **`clean_pdb` / `clean_topology`** — drop water, bulk buffer ions and
+  crystallization additives while keeping structural metals, either as a
+  pre-step (`clean_structure=True`) or on their own. The residue sets
+  (`WATER_RESIDUES`, `BULK_ION_RESIDUES`, `ADDITIVE_RESIDUES`,
+  `STRUCTURAL_METAL_RESIDUES`) are public and inspectable.
+- **Refusal with a reason** — chemistry a stand-alone treatment is not valid
+  for (covalently bound residues, monatomic species, polymer fragments) is
+  skipped and reported in `result.skipped`, rather than silently given wrong
+  parameters.
+- **Supporting public API** — `merge_ffxml`, `find_nonstandard_residues`,
+  `extract_residue_to_pdb`, `assemble_openmm_ffxml`, `run_antechamber`,
+  `run_parmchk2`, `locate_gaff_dat`, `residue_templates_with_virtual_sites`,
+  and the `DEFAULT_*` constants.
+- **Typing** — the package is fully annotated and ships a PEP 561 `py.typed`
+  marker, so annotations are visible to type checkers in consuming projects.
+- **Documentation** at [forcefill.readthedocs.io](https://forcefill.readthedocs.io),
+  covering installation, a quickstart, the four backends, CHARMM/CGenFF,
+  BespokeFit, cleaning, what gets skipped and why, and an API reference.
+
+### Known limitations
+
+- Covalently bound ligands are skipped deliberately: a stand-alone treatment of
+  a polymer-linked residue is wrong whichever backend produces it.
+- There is no command-line interface yet.
+- Re-running into an existing working directory repeats finished `antechamber`
+  jobs; nothing is cached between runs.
+
+[Unreleased]: https://github.com/LouieSlocombe/forcefill/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/LouieSlocombe/forcefill/releases/tag/v1.0.0

forcefill-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Louie Slocombe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forcefill-1.0.0/MANIFEST.in

@@ -0,0 +1,19 @@
+# What goes into the sdist beyond the package itself. The wheel is unaffected —
+# that is [tool.setuptools.package-data] in pyproject.toml.
+#
+# Without this file setuptools falls back to a distutils default that picks up
+# `tests/test_*.py` and nothing else, which ships a suite that cannot even be
+# collected: conftest.py, helpers.py, tests/data/ and the examples/data/ fixtures
+# two of the tests read are all missing. Ship it whole or not at all — and not at
+# all is right here, because the suite cannot run from an sdist install in any
+# case: it needs AmberTools, which is not a Python package, and
+# openmmforcefields >= 0.16, which does not exist on PyPI. Run it from a checkout
+# (see docs/contributing.md).
+prune tests
+
+include CHANGELOG.md
+
+# Never useful to a consumer.
+global-exclude *.py[cod]
+global-exclude .DS_Store
+prune **/__pycache__

forcefill-1.0.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: forcefill
+Version: 1.0.0
+Summary: Parameterize non-standard PDB residues (ligands, cofactors) into OpenMM force-field XML with AmberTools GAFF/AM1-BCC, OpenFF Sage or CHARMM CGenFF
+Author-email: Louie Slocombe <louies@hotmail.co.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/LouieSlocombe/forcefill
+Project-URL: Repository, https://github.com/LouieSlocombe/forcefill
+Project-URL: Documentation, https://forcefill.readthedocs.io
+Project-URL: Changelog, https://github.com/LouieSlocombe/forcefill/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/LouieSlocombe/forcefill/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openmm>=7.6
+Requires-Dist: parmed>=3.4
+Requires-Dist: rdkit
+Requires-Dist: openff-toolkit>=0.16
+Requires-Dist: openmmforcefields>=0.16
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff==0.16.2; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Dynamic: license-file
+
+# forcefill
+
+[![ci](https://github.com/LouieSlocombe/forcefill/actions/workflows/ci.yml/badge.svg)](https://github.com/LouieSlocombe/forcefill/actions/workflows/ci.yml)
+[![docs](https://readthedocs.org/projects/forcefill/badge/?version=latest)](https://forcefill.readthedocs.io/en/latest/)
+[![pypi](https://img.shields.io/pypi/v/forcefill.svg)](https://pypi.org/project/forcefill/)
+[![python](https://img.shields.io/pypi/pyversions/forcefill.svg)](https://pypi.org/project/forcefill/)
+
+Turn ligands into a ready-to-use [OpenMM](https://openmm.org) 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](https://github.com/ParmEd/ParmEd),
+from [OpenFF](https://openforcefield.org) Sage or
+[Espaloma](https://github.com/choderalab/espaloma) via
+[openmmforcefields](https://github.com/openmm/openmmforcefields), or — for
+CHARMM — by converting the CGenFF stream file
+[ParamChem](https://cgenff.paramchem.org) gave you.
+
+The output is a plain ffxml file you load alongside the standard force fields:
+
+```python
+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:
+
+```python
+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](https://forcefill.readthedocs.io/en/latest/guide/what-gets-parameterized.html).
+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](https://forcefill.readthedocs.io/en/latest/guide/checks.html)).
+
+## Documentation
+
+Full documentation is at **[forcefill.readthedocs.io](https://forcefill.readthedocs.io/en/latest/)**:
+
+| | |
+|---|---|
+| [Installation](https://forcefill.readthedocs.io/en/latest/installation.html) | conda-forge, and the two dependencies that are not ordinary ones |
+| [Quickstart](https://forcefill.readthedocs.io/en/latest/quickstart.html) | a complex in, an ffxml out, and simulating with it |
+| [What gets skipped, and why](https://forcefill.readthedocs.io/en/latest/guide/what-gets-parameterized.html) | the residues forcefill refuses, and what to do instead |
+| [Cleaning the structure](https://forcefill.readthedocs.io/en/latest/guide/cleaning.html) | water, buffer ions and crystallization additives — and the metals it keeps |
+| [Ligand input](https://forcefill.readthedocs.io/en/latest/guide/ligands.html) | SDF, MOL2 or SMILES; `LigandSpec`; ligands with no structure at all |
+| [Four backends](https://forcefill.readthedocs.io/en/latest/guide/backends.html) | GAFF, OpenFF Sage, Espaloma, CGenFF — and which mix |
+| [CHARMM and CGenFF](https://forcefill.readthedocs.io/en/latest/guide/charmm.html) | converting a ParamChem stream file, and the three ways doing it by hand goes wrong |
+| [Bespoke torsions](https://forcefill.readthedocs.io/en/latest/guide/bespokefit.html) | a BespokeFit OFFXML, and the checks that protect the QC you paid for |
+| [Checks](https://forcefill.readthedocs.io/en/latest/guide/checks.html) | what runs before the expensive step, and what runs after |
+| [Things to get right](https://forcefill.readthedocs.io/en/latest/guide/gotchas.html) | explicit hydrogens, net charge, virtual sites, the periodic box |
+| [Relation to `openmmforcefields`](https://forcefill.readthedocs.io/en/latest/guide/openmmforcefields.html) | which template generators forcefill uses, and why not `GAFFTemplateGenerator` |
+| [API reference](https://forcefill.readthedocs.io/en/latest/api/index.html) | every public function, class and constant |
+
+## Installation
+
+AmberTools is conda-only, so conda-forge is the recommended route:
+
+```bash
+conda env create -f environment.yml
+conda activate forcefill
+pip install -e . --no-deps
+```
+
+Or into an existing environment:
+
+```bash
+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](https://forcefill.readthedocs.io/en/latest/installation.html).
+
+## Quickstart
+
+```python
+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:
+
+```python
+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](https://forcefill.readthedocs.io/en/latest/guide/index.html).
+
+## Development
+
+```bash
+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](https://forcefill.readthedocs.io/en/latest/contributing.html),
+which also has the release process.
+
+## Changelog
+
+Every release is described in [CHANGELOG.md](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](LICENSE).

forcefill-1.0.0/README.md

@@ -0,0 +1,169 @@
+# forcefill
+
+[![ci](https://github.com/LouieSlocombe/forcefill/actions/workflows/ci.yml/badge.svg)](https://github.com/LouieSlocombe/forcefill/actions/workflows/ci.yml)
+[![docs](https://readthedocs.org/projects/forcefill/badge/?version=latest)](https://forcefill.readthedocs.io/en/latest/)
+[![pypi](https://img.shields.io/pypi/v/forcefill.svg)](https://pypi.org/project/forcefill/)
+[![python](https://img.shields.io/pypi/pyversions/forcefill.svg)](https://pypi.org/project/forcefill/)
+
+Turn ligands into a ready-to-use [OpenMM](https://openmm.org) 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](https://github.com/ParmEd/ParmEd),
+from [OpenFF](https://openforcefield.org) Sage or
+[Espaloma](https://github.com/choderalab/espaloma) via
+[openmmforcefields](https://github.com/openmm/openmmforcefields), or — for
+CHARMM — by converting the CGenFF stream file
+[ParamChem](https://cgenff.paramchem.org) gave you.
+
+The output is a plain ffxml file you load alongside the standard force fields:
+
+```python
+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:
+
+```python
+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](https://forcefill.readthedocs.io/en/latest/guide/what-gets-parameterized.html).
+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](https://forcefill.readthedocs.io/en/latest/guide/checks.html)).
+
+## Documentation
+
+Full documentation is at **[forcefill.readthedocs.io](https://forcefill.readthedocs.io/en/latest/)**:
+
+| | |
+|---|---|
+| [Installation](https://forcefill.readthedocs.io/en/latest/installation.html) | conda-forge, and the two dependencies that are not ordinary ones |
+| [Quickstart](https://forcefill.readthedocs.io/en/latest/quickstart.html) | a complex in, an ffxml out, and simulating with it |
+| [What gets skipped, and why](https://forcefill.readthedocs.io/en/latest/guide/what-gets-parameterized.html) | the residues forcefill refuses, and what to do instead |
+| [Cleaning the structure](https://forcefill.readthedocs.io/en/latest/guide/cleaning.html) | water, buffer ions and crystallization additives — and the metals it keeps |
+| [Ligand input](https://forcefill.readthedocs.io/en/latest/guide/ligands.html) | SDF, MOL2 or SMILES; `LigandSpec`; ligands with no structure at all |
+| [Four backends](https://forcefill.readthedocs.io/en/latest/guide/backends.html) | GAFF, OpenFF Sage, Espaloma, CGenFF — and which mix |
+| [CHARMM and CGenFF](https://forcefill.readthedocs.io/en/latest/guide/charmm.html) | converting a ParamChem stream file, and the three ways doing it by hand goes wrong |
+| [Bespoke torsions](https://forcefill.readthedocs.io/en/latest/guide/bespokefit.html) | a BespokeFit OFFXML, and the checks that protect the QC you paid for |
+| [Checks](https://forcefill.readthedocs.io/en/latest/guide/checks.html) | what runs before the expensive step, and what runs after |
+| [Things to get right](https://forcefill.readthedocs.io/en/latest/guide/gotchas.html) | explicit hydrogens, net charge, virtual sites, the periodic box |
+| [Relation to `openmmforcefields`](https://forcefill.readthedocs.io/en/latest/guide/openmmforcefields.html) | which template generators forcefill uses, and why not `GAFFTemplateGenerator` |
+| [API reference](https://forcefill.readthedocs.io/en/latest/api/index.html) | every public function, class and constant |
+
+## Installation
+
+AmberTools is conda-only, so conda-forge is the recommended route:
+
+```bash
+conda env create -f environment.yml
+conda activate forcefill
+pip install -e . --no-deps
+```
+
+Or into an existing environment:
+
+```bash
+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](https://forcefill.readthedocs.io/en/latest/installation.html).
+
+## Quickstart
+
+```python
+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:
+
+```python
+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](https://forcefill.readthedocs.io/en/latest/guide/index.html).
+
+## Development
+
+```bash
+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](https://forcefill.readthedocs.io/en/latest/contributing.html),
+which also has the release process.
+
+## Changelog
+
+Every release is described in [CHANGELOG.md](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](LICENSE).

forcefill-1.0.0/forcefill/__init__.py

@@ -0,0 +1,88 @@
+from importlib import metadata as _metadata
+
+from ._pipeline import ParameterizationResult
+from ._spec import (
+    BACKENDS,
+    CHARMM_BASE_FORCEFIELD,
+    DEFAULT_BASE_FORCEFIELD,
+    DEFAULT_ESPALOMA_FORCEFIELD,
+    DEFAULT_SMIRNOFF_FORCEFIELD,
+    LigandSpec,
+)
+from .amber import (
+    DEFAULT_AMBERTOOLS_TIMEOUT,
+    assemble_openmm_ffxml,
+    locate_gaff_dat,
+    run_antechamber,
+    run_parmchk2,
+)
+from .checks import (
+    DEFAULT_MINIMIZATION_PLATFORM,
+    DEFAULT_MINIMIZATION_TOLERANCE,
+    MinimizationResult,
+    add_extra_particles,
+    minimize_with_forcefield_xml,
+    residue_templates_with_virtual_sites,
+    validate_forcefield_xml,
+)
+from .clean_structure import (
+    ADDITIVE_RESIDUES,
+    BULK_ION_RESIDUES,
+    STRUCTURAL_METAL_RESIDUES,
+    WATER_RESIDUES,
+    CleaningResult,
+    clean_pdb,
+    clean_topology,
+)
+from .ligand import build_ligand_xml
+from .merge import merge_ffxml
+from .structure import build_forcefield_xml
+from .topology import extract_residue_to_pdb, find_nonstandard_residues
+
+# The version lives in pyproject.toml and reaches here through the installed
+# metadata; the fallback covers an uninstalled checkout.
+try:
+    __version__ = _metadata.version("forcefill")
+except _metadata.PackageNotFoundError:  # uninstalled checkout
+    __version__ = "0.0.0+unknown"
+
+# The reading and conversion helpers are not re-exported: they say where they
+# belong (`forcefill.ligand_files.inspect_ligand_file(...)`,
+# `forcefill.charmm.read_charmm_files(...)`), and the top level stays about the
+# pipeline.
+# `clean_structure` is also the name of a *module* here; it stays out of
+# __all__ because at the top level that name reads as build_forcefield_xml's
+# `clean_structure=` switch. Its public names are re-exported above.
+__all__ = [
+    "ADDITIVE_RESIDUES",
+    "BACKENDS",
+    "BULK_ION_RESIDUES",
+    "CHARMM_BASE_FORCEFIELD",
+    "DEFAULT_AMBERTOOLS_TIMEOUT",
+    "DEFAULT_BASE_FORCEFIELD",
+    "DEFAULT_ESPALOMA_FORCEFIELD",
+    "DEFAULT_MINIMIZATION_PLATFORM",
+    "DEFAULT_MINIMIZATION_TOLERANCE",
+    "DEFAULT_SMIRNOFF_FORCEFIELD",
+    "STRUCTURAL_METAL_RESIDUES",
+    "WATER_RESIDUES",
+    "CleaningResult",
+    "LigandSpec",
+    "MinimizationResult",
+    "ParameterizationResult",
+    "add_extra_particles",
+    "assemble_openmm_ffxml",
+    "build_forcefield_xml",
+    "build_ligand_xml",
+    "clean_pdb",
+    "clean_topology",
+    "extract_residue_to_pdb",
+    "find_nonstandard_residues",
+    "locate_gaff_dat",
+    "merge_ffxml",
+    "minimize_with_forcefield_xml",
+    "residue_templates_with_virtual_sites",
+    "run_antechamber",
+    "run_parmchk2",
+    "validate_forcefield_xml",
+]