mdprep 0.2.0__tar.gz

mdprep-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,52 @@
+name: tests
+
+permissions:
+  contents: read
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  unit:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+      - name: Run unit tests
+        run: pytest -q -m "not external and not slow"
+      - name: Check CLI
+        run: |
+          python -m mdprep.cli --help
+          python -m mdprep.cli config-check examples/*.yaml
+          python -m mdprep.cli selftest --quick
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Test wheel installation
+        run: |
+          python -m pip install --force-reinstall dist/*.whl
+          cd /tmp
+          mdprep --version
+          mdprep --help
+          mdprep selftest --quick

mdprep-0.2.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+prepared/
+runs/
+*.log
+*.out
+*.tmp
+*.tar.gz
+*.tar.gz.sha256
+.DS_Store

mdprep-0.2.0/AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md
+
+You are developing `mdprep`, a Python package for reproducible Amber MD system
+preparation.
+
+## Development Rules
+
+- Use Python 3.11+ and type hints.
+- Use pydantic models for YAML manifest validation.
+- The legacy molecule-conversion toolkit identified by the dedicated ban test
+  is intentionally prohibited.
+- User overrides always win over automated predictions.
+- Do not silently guess catalytic chemistry, protonation, ligand charge, or
+  metal-center behavior.
+- Structure normalization must never delete unknown heterogens silently; require
+  explicit manifest configuration.
+- Generated manifests must validate with `mdprep config-check`.
+- Every residue rename must be recorded in reports.
+- Automated protonation must not be silently skipped; fail clearly when a
+  requested backend is unavailable or cannot produce an unambiguous assignment.
+- Manual overrides always override PropKa and xTB decisions.
+- PropKa/xTB tests must skip cleanly or use fakes if executables are
+  unavailable.
+- Temporary xTB tautomer hydrogens must never be written to the final prepared
+  PDB.
+- Ligand atom names, atom order, coordinates, residue identity, and total
+  charge must be preserved or failures must be explicit.
+- Do not add molecule-conversion fallback paths.
+- Final topology generation must go through `tleap`.
+- All `tleap` scripts and logs must be preserved.
+- Do not silently ignore `tleap` warnings or errors; report them and fail when
+  configured to do so.
+- All final `.prmtop`/`.inpcrd` outputs must be validated.
+- Unsupported chemistry must fail with a clear error.
+- External commands must go through `mdprep.external.runner`.
+- External command records must include command, working directory, return code,
+  stdout, stderr, and runtime.
+- Unit tests must not require AmberTools, xTB, PySCF, or PropKa.
+- External tests must skip cleanly if required executables are unavailable.
+- External AmberTools tests must skip cleanly if `antechamber` or `parmchk2`
+  is unavailable.
+- External `tleap`, ParmEd, and OpenMM tests must skip cleanly when optional
+  executables or libraries are unavailable.
+- PySCF is the primary QM backend for ligand RESP/ESP and QMMESP-like charges.
+- Do not add ORCA or Multiwfn in this task series.
+- RESP/ESP fitting must be deterministic and tested.
+- QMMESP charges must fit only target ligand atom charges.
+- MM point charges are only for density polarization.
+- Never include environment point charges as ligand charge centers.
+- Never write environment point charges into ligand mol2 files.
+- Final Amber builds must use final fitted ligand mol2 files, not provisional
+  mol2 files.
+- External PySCF tests must skip cleanly if PySCF is unavailable.
+- All user-facing features need tests and docs.
+- All example YAML files must validate in tests.
+
+## Current v0.2 Limits
+
+Do not add new scientific features without a focused task, tests, examples
+where practical, and documentation.
+
+Explicitly unsupported for v0.2:
+
+- noncanonical amino acids inside peptide chains
+- covalent ligands
+- ORCA backend
+- Multiwfn dependency
+- multiple independent bonded MCPB sites
+- multi-chain MCPB protein inputs
+
+## Required Checks
+
+Run these before handing off:
+
+```bash
+pytest -q
+python -m mdprep.cli --help
+python -m mdprep.cli config-check examples/*.yaml
+python -m mdprep.cli selftest --quick
+```

mdprep-0.2.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## 0.2.0 - 2026-08-17
+
+### Added
+
+- Explicit nonbonded and bonded MCPB.py metal-center workflows, including
+  PySCF QMMESP/RESP charges and PySCF, GFN2-xTB, g-xTB, or MACE-POLAR-1
+  Hessian sources for Seminario parameters.
+- Optional ASH active-site QM/MM refinement with explicit QM components,
+  coordinating residues, 4 A residue and 8 A water active regions, and
+  hydrogen-only relaxation.
+- Manifest-driven Roe--Brooks OpenMM minimization, heating, density
+  equilibration, and production MD with accelerator-first/CPU-fallback
+  platform selection.
+- User-controlled production step and reporting/checkpoint intervals.
+- Manifest-directory-relative input paths and portable executable discovery.
+- GAFF/GAFF2, ff14SB/ff19SB, TIP3P/OPC, AM1-BCC, gas RESP, and embedded
+  QMMESP examples covering the supported preparation combinations.
+
+### Fixed
+
+- Roe--Brooks positional restraints are installed before Context creation and
+  their reference coordinates are converted explicitly from input units to nm.
+- Constraint-compatible heating handoff, evolving NPT box propagation, and
+  production progress totals.
+- MCPB/tLEaP residue-index and renamed-residue coordinate validation.
+
+## 0.1.0 - 2026-06-15
+
+Initial usable release.
+
+### Added
+
+- YAML manifest validation with pydantic.
+- PDB inspection, residue/atom selector parsing, altloc handling, water and heterogen classification, histidine/titratable residue detection, and possible disulfide detection.
+- `mdprep init` starter-manifest generation and safe structure normalization.
+- Manual protonation overrides, input-state preservation, disulfide `CYX` assignment, and input-hydrogen removal.
+- PropKa-based residue-state assignment and xTB/GFN2 or g-xTB HID/HIE histidine tautomer selection.
+- Ligand extraction and AmberTools parameter generation for `am1bcc` and `user_mol2`.
+- PySCF gas-phase RESP/ESP-like ligand charges.
+- PySCF QMMESP-like environment-polarized ligand charges with explicit target-ligand-only fitting.
+- Final `tleap` build, optional solvation, neutralization/salt handling, final Amber files, and validation reports.
+- External tests that skip cleanly when optional executables or libraries are unavailable.
+
+### Unsupported In 0.1.0
+
+- Noncanonical amino acids inside polymer chains.
+- Covalent ligands.
+- Bonded metal-center parameterization and MCPB-like workflows.
+- ORCA and Multiwfn backends.
+- mmCIF input.
+- Automatic loop modeling.
+- Production minimization or MD.

mdprep-0.2.0/CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: "If you use mdprep, please cite this software."
+title: "mdprep: reproducible Amber preparation for proteins, ligands, and metal centers"
+version: "0.2.0"
+date-released: "2026-08-17"
+license: "MIT"
+authors:
+  - name: "Miquel Estévez-Gay"
+repository-code: "https://github.com/miqueleg/mdprep"

mdprep-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+## Setup
+
+```bash
+mamba env create -f environment.yml
+conda activate mdprep
+pip install -e .
+mdprep selftest --quick
+```
+
+For packaging and lint tooling, use `environment-dev.yml` or install the
+`dev` extra in a suitable environment.
+
+## Tests
+
+Default tests must not require AmberTools, xTB, PropKa, PySCF, ParmEd, or
+OpenMM:
+
+```bash
+pytest -q
+python -m mdprep.cli config-check examples/*.yaml
+python -m mdprep.cli selftest --quick
+```
+
+External tests must skip cleanly when optional tools are unavailable:
+
+```bash
+pytest -q -m "external"
+pytest -q -m "external or ambertools or tleap or propka or xtb or pyscf or qmmesp"
+```
+
+## Chemistry Rules
+
+- The legacy molecule-conversion toolkit identified by the dedicated ban test
+  is intentionally prohibited.
+- Do not add molecule-conversion fallbacks.
+- User overrides always win.
+- Do not silently guess catalytic chemistry, ligand charge, protonation, or
+  metal-center behavior.
+- Every chemical decision and every residue rename must be reported.
+- Unsupported chemistry must fail with a clear error.
+- External commands must go through `mdprep.external.runner`.
+
+## QMMESP Rules
+
+- MM point charges polarize only the selected target ligand QM density.
+- The RESP/ESP fit is performed only on target ligand atoms.
+- Environment point charges must not be fitted.
+- Environment point charges must not be written to ligand mol2 files.
+- The final Amber system must use final PySCF-fitted mol2 charges, not
+  provisional charges.
+
+## Adding Features
+
+New user-facing features need docs, tests, examples when practical, and clear
+failure behavior for unsupported chemistry. Keep changes local to the relevant
+workflow stage and avoid broad rewrites unless there is a tested reason.

mdprep-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miquel Estévez-Gay
+
+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.

mdprep-0.2.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include AGENTS.md
+include LICENSE
+include CITATION.cff
+include CHANGELOG.md
+include CONTRIBUTING.md
+include environment.yml
+include environment-dev.yml
+recursive-include docs *.md
+recursive-include examples *.md *.yaml *.pdb *.mol2 *.frcmod
+recursive-include tests/data *

mdprep-0.2.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.5
+Name: mdprep
+Version: 0.2.0
+Summary: Reproducible Amber preparation for proteins, ligands, metal centers, and OpenMM MD.
+Project-URL: Homepage, https://github.com/miqueleg/mdprep
+Project-URL: Issues, https://github.com/miqueleg/mdprep/issues
+Author: Miquel Estévez Gay
+License: MIT
+License-File: LICENSE
+Keywords: amber,ligand,mcpb,metal,molecular-dynamics,openmm,protein,pyscf,qmmm,resp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: scipy>=1.10
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Provides-Extra: md
+Requires-Dist: openmm>=8.1; extra == 'md'
+Provides-Extra: qm
+Requires-Dist: parmed>=4.2; extra == 'qm'
+Requires-Dist: pyscf>=2.6; extra == 'qm'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mdprep
+
+`mdprep` 0.2.0 prepares reproducible Amber molecular-dynamics systems from a
+PDB structure and a validated YAML manifest. It supports standard proteins,
+independent ligands and cofactors, explicit metal models, optional active-site
+QM/MM refinement, final `tleap` assembly, validation, and an optional OpenMM
+equilibration/production stage.
+
+The manifest is the source of truth. Chemistry-sensitive decisions—ligand
+charge and multiplicity, catalytic protonation, metal oxidation/spin state,
+coordinating bonds, and QM components—must be supplied explicitly and are
+recorded in the output reports.
+
+## Highlights
+
+- ff14SB or ff19SB proteins with TIP3P or OPC water.
+- PropKa protonation, manual catalytic overrides, disulfides, and optional
+  GFN2-xTB/g-xTB HID–HIE selection.
+- Multiple GAFF or GAFF2 ligands/cofactors with AM1-BCC, user mol2/frcmod,
+  PySCF gas-phase RESP, or electrostatically embedded PySCF QMMESP charges.
+- Amber nonbonded metal models or bonded MCPB.py models with explicit
+  coordinating atoms, charges, and multiplicities.
+- MCPB Seminario Hessians from PySCF, GFN2-xTB, g-xTB, or MACE-POLAR-1;
+  PySCF supplies the embedded large-model ESP/RESP calculation.
+- Optional ASH/OpenMM active-site QM/MM refinement before final
+  parameterization.
+- Final `prmtop`, `inpcrd`, and PDB generation through `tleap`, followed by
+  topology, coordinate, charge, and optional OpenMM energy validation.
+- Optional Roe–Brooks OpenMM minimization, heating, density equilibration, and
+  manifest-sized production MD with GPU-first/CPU-fallback execution.
+
+## Installation
+
+Conda or Mamba is recommended because the real workflows use AmberTools,
+PropKa, xTB, OpenMM, ParmEd, and PySCF:
+
+```bash
+git clone https://github.com/miqueleg/mdprep.git
+cd mdprep
+mamba env create -f environment.yml
+conda activate mdprep
+mdprep selftest --quick
+```
+
+For a lighter Python-only installation, which does not install external
+chemistry executables:
+
+```bash
+python -m pip install .
+```
+
+Optional Python extras are available as `.[md]` for OpenMM and `.[qm]` for
+PySCF/ParmEd. External commands are discovered through `PATH`; manifests may
+also name a reviewed relative executable. No developer-machine path is embedded
+in the distributed examples.
+
+## Basic example
+
+Start from a standard protein PDB:
+
+```bash
+mdprep inspect input.pdb
+mdprep init input.pdb -o system.yaml
+```
+
+A minimal protein-only `system.yaml` is:
+
+```yaml
+project:
+  name: my_system
+  input_structure: input.pdb
+  output_dir: prepared/my_system
+
+structure:
+  keep_crystal_waters: true
+  altloc_policy: highest_occupancy
+  remove_unknown_heterogens: false
+  preserve_chain_ids: true
+  remove_input_hydrogens: true
+
+protein:
+  forcefield: ff14SB
+  water_model: TIP3P
+
+protonation:
+  ph: 7.0
+  method: manual_only
+  overrides: []
+
+disulfides:
+  auto_detect: true
+  detection_cutoff_angstrom: 2.2
+  force: []
+  forbid: []
+
+ligands: []
+metals: []
+
+solvation:
+  enabled: true
+  box: truncated_octahedron
+  buffer_angstrom: 10.0
+  neutralize: true
+  salt_concentration_molar: 0.15
+  positive_ion: Na+
+  negative_ion: Cl-
+
+validation:
+  run_openmm_energy_check: true
+  fail_on_warnings: false
+  fail_on_missing_parameters: true
+  fail_on_noninteger_ligand_charge: true
+
+molecular_dynamics:
+  enabled: false
+```
+
+The same validated manifest is available as
+[`examples/00_basic_protein.yaml`](examples/00_basic_protein.yaml).
+
+Validate and prepare it:
+
+```bash
+mdprep config-check system.yaml
+mdprep prepare system.yaml
+mdprep validate \
+  prepared/my_system/final/system.prmtop \
+  prepared/my_system/final/system.inpcrd
+```
+
+Relative paths are resolved from the manifest directory. Unknown heterogens
+are not deleted or guessed: configure them under `ligands` or `metals`, or
+explicitly request their removal.
+
+## Common workflows
+
+Generate a starter manifest using PropKa and ff19SB/OPC:
+
+```bash
+mdprep init input.pdb -o system.yaml \
+  --forcefield ff19SB \
+  --water-model OPC \
+  --protonation-method propka
+```
+
+Stop after a stage while reviewing a complex system:
+
+```bash
+mdprep prepare system.yaml --stop-after structure
+mdprep prepare system.yaml --stop-after protonation --overwrite
+mdprep prepare system.yaml --stop-after refinement --overwrite
+mdprep prepare system.yaml --stop-after ligands --overwrite
+mdprep prepare system.yaml --stop-after metals --overwrite
+mdprep prepare system.yaml --stop-after tleap --overwrite
+```
+
+Run the manifest-configured Roe–Brooks protocol from an existing Amber build:
+
+```bash
+mdprep run-md system.yaml \
+  --prmtop prepared/my_system/final/system.prmtop \
+  --inpcrd prepared/my_system/final/system.inpcrd
+```
+
+When `molecular_dynamics.enabled: true`, an ordinary `mdprep prepare` continues
+through MD. Production length and trajectory/state/checkpoint intervals are
+specified in steps in the manifest.
+
+## Where to go next
+
+| Task | Documentation | Example |
+| --- | --- | --- |
+| Manifest fields | [Manifest reference](docs/manifest_reference.md) | [All examples](examples/README.md) |
+| Protonation and histidines | [Protonation](docs/protonation.md) | `examples/02_manual_catalytic_protonation.yaml` |
+| Ligands, AM1-BCC, RESP, QMMESP | [Ligands](docs/ligands.md) and [QMMESP](docs/qmmesp_pyscf.md) | `examples/03_multi_ligand_am1bcc.yaml`, `04_qmmesp_pyscf_ligand.yaml` |
+| Metal centers and MCPB.py | [Metal centers](docs/metals.md) | `examples/08_nonbonded_zinc_1264.yaml`, `09_bonded_zinc_mcpb_prepare.yaml` |
+| Active-site QM/MM refinement | [QM/MM refinement](docs/qmmm_refinement.md) | `examples/10_qmmm_refinement_ash.yaml` |
+| Roe–Brooks OpenMM MD | [Molecular dynamics](docs/molecular_dynamics.md) | `examples/15_roe_brooks_openmm.yaml` |
+| Complete Fe(III) workflow | [7E07 tutorial](examples/tutorials/7E07_bonded_fe3/README.md) | `examples/tutorials/7E07_bonded_fe3/system.yaml` |
+
+All public example manifests are schema-validated in the test suite.
+
+## Outputs and reproducibility
+
+A complete run preserves:
+
+- the input and locked manifests;
+- normalized/protonated/refined intermediate PDBs;
+- ligand, QM, MCPB.py, and `tleap` inputs and logs;
+- final Amber topology, coordinates, and PDB;
+- structure, protonation, ligand, metal, `tleap`, and validation reports;
+- executable and Python-package version information;
+- optional MD PDBs, density history, trajectory, state log, and restarts.
+
+External failures are reported with command, working directory, return code,
+stdout, stderr, and runtime. mdprep does not silently fall back to another
+charge model, protonation, force field, QM method, or metal model.
+
+## Current limitations
+
+Version 0.2.0 does not support noncanonical amino acids inside peptide chains,
+covalent ligands, mmCIF input, automatic loop modeling, ORCA, Multiwfn,
+multiple independent bonded MCPB sites, or multi-chain MCPB protein inputs.
+Unsupported chemistry fails explicitly.
+
+## Development and release checks
+
+```bash
+mamba env create -f environment-dev.yml
+conda activate mdprep-dev
+pytest -q
+python -m mdprep.cli --help
+python -m mdprep.cli config-check examples/*.yaml
+python -m mdprep.cli selftest --quick
+python -m hatchling build
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [CHANGELOG.md](CHANGELOG.md), and
+[CITATION.cff](CITATION.cff). mdprep is distributed under the MIT license.