unleap 0.1.0__tar.gz

unleap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zeke Piskulich
+
+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.

unleap-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md
+recursive-include tests *.py
+recursive-include docs *.rst *.py *.txt Makefile
+prune docs/_build

unleap-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: unleap
+Version: 0.1.0
+Summary: Recover a ligand's mol2, frcmod and OFF lib from a built Amber parm7/rst7 system
+Author-email: Zeke Piskulich <piskulichz@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/piskuliche/unleap
+Project-URL: Documentation, https://piskuliche.github.io/unleap/
+Project-URL: Issues, https://github.com/piskuliche/unleap/issues
+Keywords: amber,ambertools,tleap,gaff,force field,frcmod,ligand,molecular dynamics
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: parmed
+Requires-Dist: rdkit
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
+Dynamic: license-file
+
+# unleap
+
+[![tests](https://github.com/piskuliche/unleap/actions/workflows/tests.yml/badge.svg)](https://github.com/piskuliche/unleap/actions/workflows/tests.yml)
+[![docs](https://github.com/piskuliche/unleap/actions/workflows/docs.yml/badge.svg)](https://piskuliche.github.io/unleap/)
+[![PyPI](https://img.shields.io/pypi/v/unleap.svg)](https://pypi.org/project/unleap/)
+
+**Get a ligand's parameter files back out of a built Amber system.**
+
+tleap turns a ligand's `mol2` / `frcmod` / `lib` into a system (`parm7` + `rst7`); `unleap` goes
+the other way. It strips the ligand out of a complex or solvated system and regenerates its
+`frcmod` (a diff against GAFF/GAFF2, plus a self-contained copy), OFF `lib`, `mol2`, and an `sdf`
+for RDKit. It then rebuilds the ligand with tleap to prove the files reproduce the original
+parameters and energies.
+
+## Install
+
+unleap needs AmberTools (tleap, sander), which is not pip-installable. The simplest setup:
+
+```bash
+conda create -n unleap -c conda-forge ambertools rdkit
+conda activate unleap
+pip install unleap
+```
+
+## Use
+
+```bash
+unleap -p complex.parm7 -c complex.rst7 -o lig_out                      # ligand auto-detected
+unleap -p unisc.parm7 -c 0.00000000_ti.rst7 --resname L00 -o L00_out   # RBFE dual topology
+unleap -p complex.parm7 -c traj.nc --frame -1 -o lig_out               # from a trajectory
+```
+
+Hydrogen mass repartitioning is detected and undone. The output directory gets `LIG.frcmod`,
+`LIG.full.frcmod`, `LIG.lib`, `LIG.mol2`, `LIG.sdf`, a `tleap.in` that loads them, and a
+`report.txt` with the PASS/FAIL validation results.
+
+## Documentation
+
+**<https://piskuliche.github.io/unleap/>**: the user guide, developer guide and API reference.
+
+To build it locally: `pip install -e ".[docs]" && make -C docs html`.
+
+## Development
+
+```bash
+git clone https://github.com/piskuliche/unleap.git && cd unleap
+pip install -e ".[test,docs]"
+python -m pytest -q          # needs AmberTools on PATH; skipped otherwise
+```
+
+## License
+
+MIT

unleap-0.1.0/README.md

@@ -0,0 +1,53 @@
+# unleap
+
+[![tests](https://github.com/piskuliche/unleap/actions/workflows/tests.yml/badge.svg)](https://github.com/piskuliche/unleap/actions/workflows/tests.yml)
+[![docs](https://github.com/piskuliche/unleap/actions/workflows/docs.yml/badge.svg)](https://piskuliche.github.io/unleap/)
+[![PyPI](https://img.shields.io/pypi/v/unleap.svg)](https://pypi.org/project/unleap/)
+
+**Get a ligand's parameter files back out of a built Amber system.**
+
+tleap turns a ligand's `mol2` / `frcmod` / `lib` into a system (`parm7` + `rst7`); `unleap` goes
+the other way. It strips the ligand out of a complex or solvated system and regenerates its
+`frcmod` (a diff against GAFF/GAFF2, plus a self-contained copy), OFF `lib`, `mol2`, and an `sdf`
+for RDKit. It then rebuilds the ligand with tleap to prove the files reproduce the original
+parameters and energies.
+
+## Install
+
+unleap needs AmberTools (tleap, sander), which is not pip-installable. The simplest setup:
+
+```bash
+conda create -n unleap -c conda-forge ambertools rdkit
+conda activate unleap
+pip install unleap
+```
+
+## Use
+
+```bash
+unleap -p complex.parm7 -c complex.rst7 -o lig_out                      # ligand auto-detected
+unleap -p unisc.parm7 -c 0.00000000_ti.rst7 --resname L00 -o L00_out   # RBFE dual topology
+unleap -p complex.parm7 -c traj.nc --frame -1 -o lig_out               # from a trajectory
+```
+
+Hydrogen mass repartitioning is detected and undone. The output directory gets `LIG.frcmod`,
+`LIG.full.frcmod`, `LIG.lib`, `LIG.mol2`, `LIG.sdf`, a `tleap.in` that loads them, and a
+`report.txt` with the PASS/FAIL validation results.
+
+## Documentation
+
+**<https://piskuliche.github.io/unleap/>**: the user guide, developer guide and API reference.
+
+To build it locally: `pip install -e ".[docs]" && make -C docs html`.
+
+## Development
+
+```bash
+git clone https://github.com/piskuliche/unleap.git && cd unleap
+pip install -e ".[test,docs]"
+python -m pytest -q          # needs AmberTools on PATH; skipped otherwise
+```
+
+## License
+
+MIT

unleap-0.1.0/docs/Makefile

@@ -0,0 +1,13 @@
+# Minimal Sphinx makefile
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

unleap-0.1.0/docs/api.rst

@@ -0,0 +1,48 @@
+API reference
+=============
+
+.. automodule:: unleap
+   :members: UnleapError
+
+Command line
+------------
+
+.. automodule:: unleap.cli
+
+Selection
+---------
+
+.. automodule:: unleap.selection
+
+Extraction
+----------
+
+.. automodule:: unleap.extract
+
+frcmod
+------
+
+.. automodule:: unleap.frcmod
+
+.. autodata:: unleap.frcmod.LEAP_DEG_CORRECTION
+   :no-value:
+
+OFF library
+-----------
+
+.. automodule:: unleap.lib
+
+mol2 / SDF
+----------
+
+.. automodule:: unleap.mol2
+
+Validation
+----------
+
+.. automodule:: unleap.validate
+
+AmberTools helpers
+------------------
+
+.. automodule:: unleap.amber

unleap-0.1.0/docs/conf.py

@@ -0,0 +1,46 @@
+"""Sphinx configuration for unleap."""
+
+import importlib
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+project = "unleap"
+author = "Zeke Piskulich"
+copyright = "2026, Zeke Piskulich"
+
+from unleap import __version__ as release  # noqa: E402  (unleap/__init__.py has no heavy imports)
+
+version = release
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+]
+
+def _missing(module):
+    try:
+        importlib.import_module(module)
+        return False
+    except ImportError:
+        return True
+
+
+# Read the Docs (and any machine without AmberTools) has no ParmEd/RDKit; mock them for autodoc.
+autodoc_mock_imports = [m for m in ("parmed", "rdkit", "numpy", "scipy") if _missing(m)]
+autodoc_member_order = "bysource"
+autodoc_default_options = {"members": True, "undoc-members": False, "show-inheritance": True}
+napoleon_numpy_docstring = True
+napoleon_google_docstring = False
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+templates_path = []
+exclude_patterns = ["_build"]
+
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {"navigation_depth": 3, "collapse_navigation": False}
+html_title = f"unleap {release}"

unleap-0.1.0/docs/dev/amber_notes.rst

@@ -0,0 +1,85 @@
+Amber and ParmEd behaviors
+==========================
+
+Each of these was found on real data and has a regression test (see :doc:`testing`).
+Don't "simplify" these away.
+
+1. Structure slicing breaks AmberParm
+-------------------------------------
+
+``struct[mask]`` keeps the full LJ tables, so the saved parm7 is malformed::
+
+   FLAG LENNARD_JONES_ACOEF has 66 elements; expected 45
+
+``Structure.copy(AmberParm)`` drops ``parm_data`` entirely. Reload the file and call
+``AmberParm.strip()``, which rebuilds the tables (:func:`unleap.extract.strip`).
+
+2. ParmEd's frcmod writer loses precision
+-----------------------------------------
+
+``AmberParameterSet.write`` formats ``req``, ``theteq`` and masses with 3 decimals, but GAFF 2.2
+uses 4-decimal bond lengths (1.3986). It also re-sorts improper atoms alphabetically.
+:func:`unleap.frcmod.write` is our own writer in the same layout: 7 decimals for ``req``,
+6 for ``theteq``, and impropers kept in topology order.
+
+3. leap's DEGTORAD is 0.0174533
+-------------------------------
+
+``leap/src/leap/basics.h`` defines ``DEGTORAD 0.0174533``, not π/180. Every angle and phase tleap
+writes is inflated by about 4.3e-7 when read back exactly, so 113.02 becomes 113.0200487.
+Writing that back inflates it again. :func:`unleap.frcmod.full_params` divides by
+:data:`unleap.frcmod.LEAP_DEG_CORRECTION`, but only when the corrected values are "rounder"
+(``_leap_inflated``), so a topology written by another tool is not over-corrected.
+
+4. tleap may store an improper reversed
+---------------------------------------
+
+The prmtop atom order can be ``l-k-j-i``, which puts the central atom second. It is the same
+torsion angle, but "central = third atom" is then wrong. For one production ligand this turned the original
+``cc-ns-c -o`` into ``o -c -ns-cc``, which tleap then never matched.
+:func:`unleap.frcmod.improper_atoms` finds the central atom from bonding (bonded to the other
+three) and reorders. The validation keys use the same function.
+
+5. Wildcard and explicit impropers give different atom orders
+-------------------------------------------------------------
+
+If tleap matches ``X -X -c -o`` rather than an explicit ``cc-ns-c -o``, it stores the four atoms
+in a different order. The improper angle, and so the energy, changes slightly even though the
+parameters are identical. So the diff frcmod **always lists every improper explicitly**, as
+parmchk2 does. :func:`unleap.frcmod.lookup_improper` only feeds the base score.
+
+6. from_structure keys impropers under every permutation
+--------------------------------------------------------
+
+``AmberParameterSet.from_structure`` stores each improper under every outer-atom permutation.
+unleap dedupes on ``(central type, sorted outer types)``.
+
+7. tleap requires MASS and NONBON together
+------------------------------------------
+
+A frcmod with NONBON but no MASS fails::
+
+   Modified force field files must have both MASS and NONBOND entries or neither.
+
+The writer always emits both for every atom type in the set.
+
+8. Coordinate reading
+---------------------
+
+ParmEd's format sniffing rejects ASCII restarts whose natom line also holds a temperature
+(pmemd/REMD: ``52598  0.1400000E+05  0.2980000E+03``). :func:`unleap.extract.read_coordinates`
+uses ``Rst7.open`` directly. For NetCDF it uses ``NetCDFTraj`` (a ``frame`` dimension exists) or
+``NetCDFRestart``, and reads a single frame from ``_ncfile.variables``, so it never loads a 750 MB
+trajectory just to take one frame.
+
+9. The lib stores coordinates at about 1e-4 Å
+---------------------------------------------
+
+For stiff angles that alone moves the energy by about 1e-3 kcal/mol, so validation scores each
+rebuilt topology on the *original* coordinates. The atom order is identical.
+
+10. RDKit can't read GAFF-typed mol2
+------------------------------------
+
+RDKit's mol2 reader expects SYBYL types (``Element 'o' not found``). That's why the SDF is
+written too.

unleap-0.1.0/docs/dev/architecture.rst

@@ -0,0 +1,60 @@
+Architecture
+============
+
+Layout
+------
+
+.. code-block:: text
+
+   unleap/
+     __init__.py   version, UnleapError (user-facing failures -> exit code 2)
+     cli.py        argparse + orchestration; writes report.txt
+     amber.py      AMBERHOME helpers, base force-field presets, tleap / sander runners
+     selection.py  --mask / --resname / auto-detect (standard residue name sets)
+     extract.py    coordinate reading, ligand strip, sanity checks, PBC unwrap, HMR undo,
+                   atom-type consistency
+     frcmod.py     full parameter set, tleap-style base lookup, diff, base scoring, frcmod writer
+     lib.py        OFF library via ParmEd ResidueTemplate
+     mol2.py       Tripos mol2 + SDF writers, RDKit bond-order inference
+     validate.py   tleap rebuilds, term-by-term comparison, sander energy comparison
+   tests/
+     conftest.py   builds fixtures on the fly (RDKit -> antechamber -c gas -> parmchk2 -> tleap)
+     test_unleap.py
+   scripts/
+     vcm_sweep.py  real-data regression sweep over ABFE vcm_* jobs
+   docs/           this documentation (Sphinx, Read the Docs theme)
+
+Data flow
+---------
+
+:func:`unleap.cli.run` runs these steps in order:
+
+1. :func:`unleap.extract.load` loads the topology with ParmEd and reads coordinates with
+   :func:`~unleap.extract.read_coordinates` (see :doc:`amber_notes`, item 8).
+2. :func:`unleap.selection.ligand_mask`, then :func:`unleap.extract.strip`. This checks the
+   selection (exactly one whole residue, not covalent), warns about NBFIX/12-6-4/CMAP, then
+   **reloads** the topology and ``strip("!(mask)")``\ s it, then unwraps the ligand across PBC.
+3. :func:`unleap.frcmod.full_params` builds the parameter set with
+   ``AmberParameterSet.from_structure``, then applies the masses, improper dedupe and order,
+   and the leap angle correction.
+4. :func:`unleap.cli.pick_base` scores each preset (or uses ``--base``) and returns the
+   :class:`~unleap.amber.BaseFF` and its loaded ``.dat``.
+5. :func:`unleap.extract.undo_hmr` (needs the base for reference H masses), then
+   :func:`~unleap.extract.check_type_consistency`, then ``full_params`` again so the masses are final.
+6. :func:`unleap.frcmod.diff_params` compares each term with the base using tleap's lookup rules
+   (:doc:`diff_rules`).
+7. The frcmods, lib, mol2/sdf and ``tleap.in`` are written.
+8. :func:`unleap.validate.run` saves ``LIG.orig.parm7``, does the three tleap rebuilds, then runs
+   :func:`~unleap.validate.compare_terms` and :func:`~unleap.validate.compare_energies`.
+
+State between steps
+-------------------
+
+:class:`unleap.extract.Ligand` carries the state between steps. ``ligand.masses`` is the
+per-atom mass list to write. It differs from ``lig.atoms[i].mass`` only when HMR was undone.
+
+.. warning::
+
+   Never mutate parameter types attached to ``ligand.lig``. :func:`unleap.validate.save_stripped`
+   writes that structure as the reference everything is compared against. That's why
+   :func:`unleap.frcmod.full_params` replaces angle and dihedral types with corrected *copies*.

unleap-0.1.0/docs/dev/diff_rules.rst

@@ -0,0 +1,43 @@
+Diff frcmod matching rules
+==========================
+
+:func:`unleap.frcmod.compare_to_base` decides, term by term, whether the base force field already
+reproduces the ligand's parameter. It mirrors tleap's lookup order:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 14 40 46
+
+   * - Term
+     - Lookup
+     - Equal if
+   * - atom type
+     - by name
+     - mass, rmin and ε within ``_TOL`` (rel/abs 1e-5)
+   * - bond / angle
+     - explicit, either direction
+     - k and eq within ``_TOL``
+   * - dihedral
+     - explicit (either direction), then ``X-b-c-X``
+     - same term list after dropping zero-k terms: periodicity, phase (mod 360), k, SCEE, SCNB
+   * - improper
+     - central third; outer atoms permuted; 0, then 1, then 2 ``X`` wildcards
+     - k, periodicity, phase (no 1-4 scaling)
+
+A term that is missing from the base or differs is written explicitly. tleap gives explicit
+frcmod entries loaded after the base priority over the base, which reproduces the original
+build. Impropers are all written regardless (see :doc:`amber_notes`, item 5).
+
+Base scoring
+------------
+
+:func:`unleap.frcmod.score_base` is the fraction of the ligand's bonded terms plus LJ types that
+a base reproduces. Masses are ignored, because HMR may have altered them. ``--base auto`` takes
+the best preset from :func:`unleap.amber.preset_bases`.
+
+What the diff cannot express
+----------------------------
+
+A frcmod can add or override terms, but it cannot remove one. If the base would add a term the
+original build didn't have, validation reports ``extra in rebuild``. ``LIG.full.frcmod`` does not
+have this problem.

unleap-0.1.0/docs/dev/extending.rst

@@ -0,0 +1,35 @@
+Extending
+=========
+
+New base force fields
+---------------------
+
+Add them to ``_PRESETS`` in :mod:`unleap.amber`, as ``name -> (dat file, tleap preamble)``.
+:func:`~unleap.amber.preset_bases` lists only the presets whose ``.dat`` exists in ``AMBERHOME``,
+and ``--base auto`` scores them all.
+
+Multi-residue or covalent ligands
+---------------------------------
+
+This would need:
+
+* :func:`unleap.extract.strip` to accept several residues, and to stop rejecting bonds to
+  outside atoms.
+* :func:`unleap.lib.write` to emit connected units (head/tail atoms).
+* A policy for bonded terms that cross the cut.
+
+NBFIX
+-----
+
+ParmEd can write ``LJEDIT`` sections, but ``AmberParm`` doesn't populate ``atom_type.nbfix`` on
+load. You'd have to build the pairs from the A/B coefficient tables found in
+``extract._nonbonded_checks``.
+
+Conventions
+-----------
+
+* User-facing failures raise :class:`unleap.UnleapError`. The CLI turns them into exit code 2
+  with a one-line message.
+* Warnings that still allow output go in ``ligand.warnings`` and appear as ``WARNING:`` lines in
+  ``report.txt``.
+* Any fix for a real topology needs a regression test that reproduces it synthetically.

unleap-0.1.0/docs/dev/testing.rst

@@ -0,0 +1,68 @@
+Testing
+=======
+
+Unit and integration tests
+--------------------------
+
+.. code-block:: bash
+
+   python -m pytest -q          # ~5 s; skips everything if AmberTools isn't available
+
+The fixtures are built per session in pytest's tmp dir (``tests/conftest.py``): acetaminophen
+(GAFF2 and GAFF) and 4-chlorobenzoate next to an ff14SB peptide. Charges are antechamber
+``-c gas`` for speed.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 45 55
+
+   * - Area
+     - Tests
+   * - Round trip and diff ⊆ parmchk2
+     - ``test_gaff2_roundtrip``
+   * - Custom dihedral/LJ edits recovered exactly
+     - ``test_custom_parameters_are_recovered``
+   * - Auto-detect in a complex, charged-ligand bond orders
+     - ``test_complex_autodetect_and_bond_orders``, ``test_sdf_is_rdkit_readable``
+   * - HMR undo / ``--keep-masses`` refusal
+     - ``test_hmr_is_undone``, ``test_keep_masses_rejects_split_types``
+   * - Base auto-detect (gaff1)
+     - ``test_gaff1_base_autodetect``
+   * - NetCDF trajectory and REMD-style rst7 input
+     - ``test_netcdf_trajectory_and_remd_rst7``
+   * - Reversed improper order, leap angle correction
+     - ``test_reversed_improper_order``, ``test_leap_angle_correction_recovers_input``
+   * - Error paths
+     - ``test_ambiguous_autodetect``, ``test_multi_residue_mask_rejected``, ``test_nbfix_warns``
+   * - Validation is not vacuous
+     - ``test_validation_catches_missing_terms`` (drops the dihedrals from the diff and expects FAIL)
+
+When you fix a new real-world case, add a fixture that reproduces it. Items 3–5 in
+:doc:`amber_notes` were invisible on the synthetic systems until real RBFE/ABFE topologies
+exposed them.
+
+Real-data sweep
+---------------
+
+.. code-block:: bash
+
+   python scripts/vcm_sweep.py path/to/ABFE /tmp/vcm_sweep   # directory holding vcm_* jobs; ~10 min
+
+``scripts/vcm_sweep.py`` runs unleap over every
+``ABFE/vcm_*/results/.../t1_{complex,binder}_abfeproduction`` directory (its parm7 plus the λ=0
+production rst7). It then rebuilds each job's ``inputs/abfe/<L>/binder_<L>.*`` with tleap and
+compares that to the extracted ligand with :func:`~unleap.validate.compare_terms` and
+:func:`~unleap.validate.compare_energies`.
+
+That is the strongest end-to-end check available: it asks "is what we recovered what was put in?",
+not just "do our files reproduce the topology?". It writes one directory per job and leg, plus
+``summary.json``. It's worth re-running after any change to ``frcmod.py`` or ``validate.py``.
+
+Last result: 52/52 topologies pass, and 46/46 with inputs are identical to their inputs.
+
+Docs build
+----------
+
+.. code-block:: bash
+
+   make -C docs html SPHINXOPTS=-W     # warnings are errors

unleap-0.1.0/docs/index.rst

@@ -0,0 +1,46 @@
+unleap
+======
+
+**Get a ligand's parameter files back out of a built Amber system.**
+
+tleap takes a ligand's ``mol2`` / ``frcmod`` / ``lib`` and builds a system (``parm7`` + ``rst7``).
+``unleap`` goes the other way. Give it a complex or solvated system and it strips the ligand out,
+regenerates those files, and then proves they are right. It rebuilds the ligand with tleap and
+checks every parameter and a sander energy breakdown against the original topology.
+
+.. code-block:: bash
+
+   unleap -p complex.parm7 -c complex.rst7 -o lig_out
+
+Typical uses:
+
+* The original ligand inputs are gone, or you no longer trust they match what was simulated.
+* You want the exact parameters used in a production run (RBFE/ABFE/VCM job) to reuse elsewhere.
+* You want to check that a run's topology really used the ligand files you think it did.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User guide
+
+   user/installation
+   user/quickstart
+   user/options
+   user/outputs
+   user/validation
+   user/limitations
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Developer guide
+
+   dev/architecture
+   dev/amber_notes
+   dev/diff_rules
+   dev/testing
+   dev/extending
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
+   api

unleap-0.1.0/docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx>=7
+sphinx-rtd-theme>=2

unleap-0.1.0/docs/user/installation.rst

@@ -0,0 +1,41 @@
+Installation
+============
+
+Requirements
+------------
+
+* AmberTools: ``tleap`` and ``sander``, plus ``$AMBERHOME/dat/leap/parm/gaff*.dat``
+* Python 3.9+ with `ParmEd <https://parmed.github.io/ParmEd/>`_, `RDKit <https://www.rdkit.org/>`_,
+  NumPy and SciPy
+
+Install
+-------
+
+The easiest way to get everything is conda-forge, whose ``ambertools`` package includes ParmEd:
+
+.. code-block:: bash
+
+   conda create -n unleap -c conda-forge ambertools rdkit
+   conda activate unleap
+   pip install unleap
+
+If you already have an AmberTools install, source it (``source $AMBERHOME/amber.sh``) and
+``pip install unleap`` into that Python.
+
+From a checkout, for development:
+
+.. code-block:: bash
+
+   git clone https://github.com/piskuliche/unleap.git
+   cd unleap
+   pip install -e ".[test,docs]"
+
+``AMBERHOME`` must be set. If it isn't, unleap stops with ``AMBERHOME is not set``.
+
+Building these docs
+-------------------
+
+.. code-block:: bash
+
+   pip install -r docs/requirements.txt
+   make -C docs html          # output in docs/_build/html