mdprep 0.2.0__tar.gz → 0.4.0__tar.gz

{mdprep-0.2.0 → mdprep-0.4.0}/.gitignore

@@ -16,3 +16,13 @@ runs/
 *.tar.gz
 *.tar.gz.sha256
 .DS_Store
+node_modules/
+package-lock.json
+
+# Worktrees created for spawned background tasks.
+.claude/worktrees/
+
+# Tutorial structures downloaded on demand.
+tutorials/
+web/vendor/
+*.zip

{mdprep-0.2.0 → mdprep-0.4.0}/AGENTS.md

@@ -65,8 +65,9 @@ Explicitly unsupported for v0.2:
 - covalent ligands
 - ORCA backend
 - Multiwfn dependency
-- multiple independent bonded MCPB sites
-- multi-chain MCPB protein inputs
+- multiple independent bonded MCPB sites (copies of one site in an oligomer
+  share a single fit through `parameters_from`; see `docs/oligomers.md`)
+- bonded MCPB sites bound by more than one protein chain
 
 ## Required Checks
 

mdprep-0.4.0/CHANGELOG.md

@@ -0,0 +1,367 @@
+# Changelog
+
+## 0.4.0 - 2026-10-20
+
+### Added
+
+- Dimers, trimers and tetramers. Every protein chain can be prepared in one
+  system, and when the chains are copies of one protein the builder asks
+  whether every copy should get the same parameters. If so it asks about the
+  first copy only and gives each answer to the matching residue of the others,
+  matched by sequence and by position rather than by residue number, which
+  copies often do not share (2FCT numbers its two alpha-ketoglutarates 897 and
+  898). A ligand is parameterised once; a bonded metal site is fitted once with
+  MCPB.py, and each copy's residues take the fit's templates and its metal the
+  fit's bonds. A copy whose site differs -- 6NIE's chains B and C bind
+  alpha-ketoglutarate through the other carboxylate oxygen -- is reported and
+  asked about on its own. See `docs/oligomers.md`.
+- `parameters_from` on ligands and metal sites: a block built with another
+  block's parameters, checked by `config-check` to repeat its settings and, for
+  a bonded site, to list its residues in the reference's order.
+- `examples/18_syrb2_dimer_shared_mcpb.yaml`: both copies of SyrB2, one fit.
+- `mdprep.analysis.charges.metal_sites`: each metal site's charge on its own,
+  which the official notebook now shows one table per site.
+- The web builder lists which chains are copies of one protein, shows the
+  chain and copy questions with each chain in its own colour, and names
+  residues with their chain.
+- Refusals the answers already make certain are given at the question that
+  causes them, in the web builder and in `mdprep init --interactive`: a second
+  bonded metal site needing a fit of its own, or a cofactor whose charges were
+  to come from a site made nonbonded. Every `DecisionError` names the question
+  to go back to (`decision_id`), and the page goes there.
+
+- The official Colab notebook, `examples/mdprep_colab.ipynb`: takes a bundle
+  from the web builder (or runs the SyrB2 example), prepares and equilibrates
+  the system, and shows every step -- the structure after each stage, the
+  protonation states, the charge on every atom in tables and in 3D, the metal
+  site's MCPB force constants, how temperature, density and volume
+  equilibrated, the structure after each Roe-Brooks step, and the trajectory
+  with its RMSD, RMSF and metal-site distances. The web builder links to it.
+- `mdprep closest-xray`: the X-ray structures closest to a predicted model,
+  from the RCSB sequence search, with resolution, waters and bound ligands;
+  those holding the model's metal come first.
+- `mdprep transplant-waters`: a reference structure's crystal waters on a
+  predicted model. PyMOL pairs the residues (by sequence, or by structure for a
+  distant homologue); each model chain takes its best reference chain; a water
+  bound to a metal moves with it onto the model's metal; clashing and bulk
+  waters are dropped; a reference of another fold is refused. Every decision
+  is in a JSON report.
+- `mdprep.analysis`: reads a prmtop, inpcrd and OpenMM DCD with numpy alone,
+  and provides charge tables, the metal site's force constants, imaged and
+  superposed trajectories, RMSD, RMSF and distances, and the equilibration and
+  production logs.
+- `equilibration.csv` in every Roe-Brooks run: every stage on one time axis,
+  with temperature, density, box volume and energies every 0.5 ps.
+- `docs/predicted_structures.md`: from a Boltz or AlphaFold3 prediction to a
+  model with its crystal waters, with the worked SyrB2 example.
+- `examples/17_syrb2_bound_water_mcpb.yaml` and the vendored 2FCT deposition.
+- When a structure with a metal has no waters at all, the metal question says
+  so and points to `mdprep transplant-waters`.
+
+- Waters bound to a bonded metal site, as the resting iron of an
+  alpha-ketoglutarate enzyme carries (SyrB2, PDB 2FCT). The decision engine
+  proposes the water as a donor; mdprep writes the TIP3P template MCPB.py
+  requires, supplies the H-O-H angle rigid TIP3P lacks, and counts the water as
+  neutral in the QM/MM refinement.
+- `structure.keep_crystal_ions` and its question: free monatomic ions resolved
+  in the crystal (Cl-, Na+, Br-, ...) are kept or removed as a group, and
+  listed in the structure report either way.
+
+### Changed
+
+- **Free crystal ions are kept by default.** A free monatomic ion in the input
+  used to count as an unknown heterogen, so a manifest with
+  `structure.remove_unknown_heterogens: true` dropped it. It is now governed by
+  `structure.keep_crystal_ions`, which defaults to `true`, so the same manifest
+  builds with the ion in place: 2FCT's free chloride, for one. Add
+  `keep_crystal_ions: false` to keep the old result. Every ion kept or removed
+  is listed in `reports/structure_report.md`.
+- Two bonded metal sites are refused by `mdprep config-check`, where 0.3.0
+  refused them only once a run had started.
+
+### Fixed
+
+- CUDA did not start on Colab's T4 GPUs (OpenCL did):
+  - conda-forge installed a CUDA runtime newer than the GPU driver, whose
+    kernels the driver refused (`CUDA_ERROR_UNSUPPORTED_PTX_VERSION`);
+  - the setup the notebook and the web builder run now caps `cuda-version`
+    at the driver's version, and rerunning section C repairs an existing
+    environment;
+  - `mdprep doctor` starts a CUDA system to check;
+  - a CUDA failure in the MD says what to do, and `auto` says which
+    platform it passed over.
+- The official notebook drew the final structure (E3) from tleap's PDB, which
+  has no elements, so the viewer read hydrogens such as HG21 as mercury and
+  bonded them to everything near. It is now drawn from the topology, as E8
+  and H are. Each protein molecule is now its own chain in every view, so no
+  cartoon runs from one copy of a dimer into the next or across a missing
+  loop. A chloride on the iron, one atom with no bond to draw, now shows as a
+  sphere.
+- Keeping one chain of a predicted oligomer kept every ligand chain too, so the
+  other copy's iron and cofactor floated in the box. A chain holding only
+  heterogens now goes with the protein chain it sits against.
+- The spin of the QM region was asked of any structure with two metals, even
+  when neither turned out bonded; it is now asked once a bonded site is
+  confirmed, whichever site that is.
+- `DecisionPlan.applicable` counted an answer whose own question was no longer
+  reachable -- a shell confirmed before the site was switched to nonbonded.
+- The ligand coordinate check after tleap could not tell two copies of one
+  cofactor apart, since tleap renumbers residues; it now takes the copy nearest
+  the ligand it checks.
+- The web builder and the wizard told a student to add a SMILES to a ligand
+  without hydrogens after asking for it and being given it.
+- `mdprep init --interactive` re-asked a rejected answer without saying why.
+
+- A residue name mdprep assigned (a predicted iron called `LIG1` read as `FE`)
+  lost that record when the structure was written and read back, and `FE` read
+  cold is the CCD code for Fe(III): the planner then proposed +3 for an Fe(II)
+  site. mdprep's PDB writer records assigned names in a remark its reader
+  honours.
+- The model-charge proposal ignored an oxidation state accepted as proposed,
+  so a student added the terms up by hand.
+- The old Colab run notebook ran the MD twice: `mdprep prepare` already runs it
+  when the manifest enables it. It now points to the official notebook, which
+  stops `prepare` before the MD.
+- A free crystal chloride was offered as a ligand and then refused as a
+  reserved residue name, telling the user to rename it. tleap builds it from
+  its ion library like any counterion; it is no longer a ligand candidate, and
+  a histidine xTB cluster that contains one counts its charge.
+- A topology with a water and a halide on the same metal went to NaN in
+  heating: their 1-4 pair through the metal had a Coulomb attraction and no
+  repulsion. Those 1-4 terms are now switched off in the prmtop and listed in
+  the tleap report.
+- tleap bonded the two ends of an unresolved loop into one peptide bond, 6.08 A
+  long in 2FCT. A TER is now written wherever C(i)-N(i+1) exceeds 2 A.
+- The crystal-water and unknown-heterogen questions disappeared whenever any
+  water coordinated any metal -- in 6NIE, three waters on a surface iron of
+  chain B hid the question for all 847. Both are asked now, and the
+  crystal-water question names the bound waters that are kept regardless.
+- A water bound to a metal was dropped with the other crystal waters when
+  those were removed: for a bonded site that left an MCPB bond to a residue
+  that no longer existed, and for a nonbonded one it stripped the ion's first
+  shell, though the question had said it would stay. The question and
+  normalisation now share one definition of a bound water
+  (`mdprep.structure.coordination`).
+- Declining a ligand while keeping unknown heterogens, dropping crystal waters
+  with a bonded site, or choosing OPC with a water bound to a bonded metal now
+  fail in the builder with what to change, instead of later in Colab.
+- The QM-region spin proposal ignored defaults the user had accepted without
+  typing them, so a bonded iron with the default model got no proposal.
+
+## 0.3.0 - 2026-10-19
+
+### Added
+
+- `mdprep plan` and `mdprep init --interactive`: a structure-aware decision
+  engine that reduces a 250+ setting schema to the questions one structure
+  actually needs, and asks them. Chemistry-sensitive values have no default and
+  cannot be skipped.
+- Each decision carries viewer hints (`focus`, `targets`, `target_resnames`) so
+  a 3D front end can frame exactly the residues a question is about.
+- `mdprep inspect` reports free monatomic metal ions.
+- A static web input builder (`web/`) that runs mdprep in the browser under
+  Pyodide, shows a 3D view framed on whatever each question is about, and
+  produces a validated manifest plus runnable Colab cells.
+- `mdprep.workflows.runtime.conda_packages_for` derives the external toolchain a
+  given manifest needs, so a generated setup cell installs PropKa, xTB or PySCF
+  only when the run will actually invoke them.
+
+- `mdprep doctor` checks that the external tools a given manifest will invoke
+  are installed, and names the one command that installs what is missing.
+- mmCIF and ModelCIF input: a structure predicted by Boltz or AlphaFold is read
+  directly, with no conversion step and no loss of the chain and residue
+  identifiers the manifest selects on.
+- Four-character residue names, hybrid-36 serial and residue numbers, and
+  residues whose name does not fit a PDB column, which a predicted structure
+  written to PDB reaches routinely. A name mdprep has to assign is recorded as
+  assigned, so nothing downstream reads chemistry into a name it invented.
+- `metals[].coordinating_ions` declares a non-metal ion bound in a metal site,
+  such as a coordinating halide, which previously had nowhere to live: it is
+  not a metal, and antechamber cannot treat a single atom.
+- The setup cell downloads the g-xTB build of xtb from the Grimme group's
+  releases and checks it against the published checksum, because conda-forge
+  carries only the GFN-only build.
+
+- `structure.keep_chains` restricts a build to named chains, which a bonded
+  MCPB site requires and a multi-copy crystal structure needs.
+- The decision engine proposes a metal coordination sphere from interatomic
+  distances, requires it to be confirmed, and generates the bonded MCPB block
+  with a GFN2 Seminario Hessian and GFN2 QM/MM refinement geometry.
+- `examples/16_besd_halogenase_gfn2_mcpb.yaml`, the BesD halogenase reference
+  case.
+- Detection of incomplete residues and chain breaks, asked about before any
+  expensive stage runs, and protection for waters coordinating a metal.
+- `examples/mdprep_colab_run.ipynb`, a Colab notebook that runs a manifest and
+  installs only the toolchain that manifest needs.
+
+- `metals[].coordinating_ions` declares a non-metal ion bound in a metal site,
+  such as a coordinating halide, which previously had nowhere to live: it is
+  not a metal and antechamber cannot treat a single atom.
+
+### Changed
+
+- The refinement stage defaults to `backend: openmm`, a force-field hydrogen
+  relaxation, instead of GFN2 QM/MM. The stage only ever moved hydrogens, and
+  a force field settles them in seconds. `backend: ash` keeps the QM/MM route
+  and is required to relax heavy atoms. `movable_atoms` and
+  `post_refinement_protonation` default to match the hydrogen-only backend.
+- Histidine HID/HIE selection stays with xTB: force-field energies of the two
+  tautomers are not comparable, because they are different residue templates
+  rather than one molecule with a proton moved.
+
+- Dropped the unused `scipy` and `pandas` runtime dependencies.
+- A ligand that coordinates a bonded metal site now defaults to taking its
+  charges from that site's MCPB fit instead of AM1-BCC.
+- A metal site's Hessian defaults to g-xTB rather than GFN2. GFN2 has no
+  parameters for most transition metals, and said so only after the run had
+  got as far as the Hessian.
+- **A ligand whose residue name an Amber force field already defines is now
+  refused, where it used to be renamed for the build.** `LYS` became `LY1`,
+  which satisfied tleap and moved the problem: the prepared system then
+  described a residue under a name the input never used, and every later
+  reader had to know about the substitution. A manifest that declares such a
+  ligand now fails, in the GUI before it asks anything and on the command line
+  before any quantum chemistry, and says which residue to rename. The web
+  builder offers to make the change in the input.
+- **`refinement.total_qm_multiplicity` is now required whenever any component
+  of the QM region is open-shell**, where it used to be taken from the first
+  open-shell component found. For a lone high-spin Fe(II) that is the right
+  answer and it was right by accident: it holds only while the ion is the
+  single unpaired centre and nothing couples to it, which nothing in a
+  manifest can check. Existing manifests that leave it out of an open-shell
+  region will fail validation and need the value added.
+- Preparing the same system the same way twice now yields the same atom count.
+  MD starting velocities stay random and the seed drawn for each run is
+  recorded, so a replicate can be repeated by putting that number back.
+
+### Fixed
+
+- Per-step MD snapshots are written in the box the manifest asked for. They
+  carried the pre-NPT cell, because `PDBFile` takes CRYST1 from the topology
+  and the topology was the one loaded at the start, and they were wrapped into
+  the parallelepiped OpenMM spans rather than imaged about the solute -- so a
+  truncated octahedron came back as a sheared prism with the protein off to
+  one side and its water drawn 70 A away instead of 54 A.
+- The ESP grid survives an xTB crash on its last point, and the fit uses the
+  grid that was actually evaluated rather than the one that was requested.
+- A metal in a predicted structure is named after its element, so a site is
+  not identified by a name the prediction never meant as one.
+- CONECT records that cover only part of a ligand are ignored rather than
+  treated as its whole connectivity.
+- tleap writes its own atom types into the element column of the PDB it
+  outputs; the reader no longer believes them.
+- The setup cell installs PDBFixer whenever a run will need it, not only when
+  structure repair happens to pull it in, and the resolver is checked against
+  every combination of options rather than the one that was reported.
+- A titratable side chain coordinating a metal is asked about, from the same
+  contact list the bonds come from, instead of refusing the run later.
+- Guessed force-field parameters (`ATTN, need revision`) and the OpenMM energy
+  check are both checked when the manifest asks for them.
+- Many GUI fixes: the Finish button reports what went wrong instead of doing
+  nothing, re-uploading a structure cannot leave the bundle describing the
+  previous one, a file that parses to no atoms is rejected, Start over clears
+  the answers, Enter fetches a PDB id, and an entry that is mmCIF-only is
+  fetched as `.cif`.
+
+## 0.2.1 - 2026-10-01
+
+### Fixed
+
+- A ligand whose residue name is one the Amber force fields already define is
+  now built under a name they do not. `tleap` resolves residues by name and
+  maps an amino-acid name to its terminal form first, so the BesD free-lysine
+  substrate was built from the `NLYS` protein template and the run died with
+  "Atom .R<NLYS 252>.A<OXT 25> does not have a type" for every one of its
+  ligand-named atoms; binding the ligand unit to `LYS` instead would have
+  pointed every lysine in the protein at the ligand's parameters. The leap
+  input PDB, a copy of the fitted mol2, the `tleap` script and the final
+  validation all use the new name, and every rename is reported.
+- The temporary xTB hydrogen environment no longer hydrogenates a residue
+  twice. OpenMM matches the hydrogens a residue already has through the bonds
+  its residue templates define, so hydrogens mdprep placed from
+  `ligands[].smiles`, named after their parent heavy atom, were invisible to it
+  and it built a second complete set beside them: the BesD free-lysine
+  substrate came out carrying both HB2/HB3 and HB/HBA. Such a residue is now
+  passed through untouched and reported, unless a protonation state was decided
+  for it, in which case OpenMM still rebuilds it in that state.
+- Amber ion atom types were built as `element + charge + "+"`, which produced
+  `Na1+` for every monovalent cation and could not express an anion at all.
+
+- Roe--Brooks stage 2 no longer fails with "Particle coordinate is NaN" on
+  solvated systems. Free ions were positionally restrained because Amber names
+  them `Na+`/`Cl-`, which match no bare element symbol, and coordinates handed
+  between stages were wrapped into the periodic box while the restraint
+  references stayed unwrapped, placing every wrapped restrained particle a full
+  box length from its reference. Stage hand-off and XML restarts now stay in
+  the unwrapped frame; only the per-step PDBs and the trajectory are wrapped.
+- Final-output validation no longer rejects its own PDB with "PDB atom serials
+  must be unique when present" above 99,999 atoms. Serials are decoded for the
+  column-12 overflow `tleap`/`ambpdb` write, for hybrid-36, and for `*****`; a
+  genuine wrap-around is renumbered in file order with a warning, and stays
+  fatal only when `CONECT` records make the connectivity ambiguous. The PDB
+  writer uses the same convention it reads, so structures of that size
+  round-trip unchanged.
+- `mdprep inspect --json` no longer emits unparseable JSON on a narrow
+  terminal, where rich reflowed long strings to the console width.
+
+### Changed
+
+- xTB histidine calculations pin `OMP_NUM_THREADS`, `MKL_NUM_THREADS` and
+  `OPENBLAS_NUM_THREADS` to the new `protonation.histidine.xtb.num_threads`
+  (default `1`), with `OMP_STACKSIZE` from `omp_stacksize` (default `1G`).
+  xTB otherwise opened one thread per hardware thread for every tautomer
+  cluster, spending large amounts of CPU time without reducing wall time.
+- `mdprep inspect` also reports free monatomic metal ions.
+
+## 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.4.0/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# 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.
+
+## Releasing
+
+Publishing is automatic and tokenless. `.github/workflows/release.yml` fires
+on a `v*` tag and uploads to PyPI through Trusted Publishing, so no API token
+exists to leak or rotate. PyPI is configured to trust this repository, this
+workflow file by name, and the `pypi` environment; renaming either breaks
+publishing until the publisher at
+<https://pypi.org/manage/project/mdprep/settings/publishing/> is updated.
+
+To cut a release:
+
+1. Bump the version in `pyproject.toml` and `src/mdprep/__init__.py`, and in
+   the README's first line. `tests/test_packaging_metadata.py` fails if the
+   first two disagree.
+2. Retitle the changelog's `## Unreleased` section to `## <version> - <date>`.
+   The workflow refuses a tag with no such heading.
+3. Update the `mdprep[md,qm]==` pin in `examples/*.ipynb` and the assertion in
+   `tests/test_colab_smoke_notebook.py`. The web builder installs from git
+   master and needs no bump.
+4. Execute the official notebook end to end (below) and fix whatever it
+   finds: it is what students run, and nothing else exercises it whole.
+5. Merge, then `git tag -a vX.Y.Z` and push the tag.
+
+The workflow then refuses a tag that does not match the version in the tree,
+builds, checks that the sdist carries the project and nothing that was lying
+in the working tree, installs the wheel and runs `mdprep selftest --quick`
+from it, publishes to PyPI, and attaches the same two files to the GitHub
+release -- creating one from the changelog section if you have not written
+one by hand.
+
+Use semantic versioning against the *manifest*, not just the API: a change
+that makes an existing manifest stop validating is breaking, whatever it did
+to the Python surface.
+
+### Executing the official notebook outside Colab
+
+`examples/mdprep_colab.ipynb` runs anywhere with a Linux GPU. Its uploads and
+installs are redirected by environment variables, so a Python with mdprep,
+`pymol-open-source-whl`, `py3Dmol`, `pandas`, `matplotlib` and `nbclient`
+can execute it against a micromamba runtime built once:
+
+```bash
+MDPREP_COLAB_PREFIX=/scratch/colab \
+MDPREP_SKIP_KERNEL_INSTALL=1 \
+MDPREP_SPEC=$PWD \
+MDPREP_TEST_UPLOAD_MODEL=/path/to/predicted_model.cif \
+MDPREP_TEST_UPLOAD_BUNDLE=/path/to/mdprep-bundle.zip \
+python -c "import nbformat; from nbclient import NotebookClient; \
+nb = nbformat.read('examples/mdprep_colab.ipynb', 4); \
+NotebookClient(nb, timeout=5400).execute(); nbformat.write(nb, 'executed.ipynb')"
+```
+
+`MDPREP_COLAB_PREFIX` stands in for `/content` (micromamba goes in its `bin/`,
+the environment in `mamba-root/`), and `MDPREP_TEST_EXAMPLE_DIR=examples`
+makes the SyrB2 example read the manifest from the checkout instead of GitHub.
+

{mdprep-0.2.0 → mdprep-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mdprep
-Version: 0.2.0
+Version: 0.4.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
@@ -19,13 +19,17 @@ 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: all
+Requires-Dist: openmm>=8.1; extra == 'all'
+Requires-Dist: parmed>=4.2; extra == 'all'
+Requires-Dist: pdbfixer>=1.9; extra == 'all'
+Requires-Dist: pyscf>=2.6; extra == 'all'
+Requires-Dist: rdkit>=2023.3; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: build>=1; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
@@ -34,8 +38,11 @@ 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: ligands
+Requires-Dist: rdkit>=2023.3; extra == 'ligands'
 Provides-Extra: md
 Requires-Dist: openmm>=8.1; extra == 'md'
+Requires-Dist: pdbfixer>=1.9; extra == 'md'
 Provides-Extra: qm
 Requires-Dist: parmed>=4.2; extra == 'qm'
 Requires-Dist: pyscf>=2.6; extra == 'qm'
@@ -45,7 +52,7 @@ Description-Content-Type: text/markdown
 
 # mdprep
 
-`mdprep` 0.2.0 prepares reproducible Amber molecular-dynamics systems from a
+`mdprep` 0.4.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
@@ -65,6 +72,10 @@ recorded in the output reports.
   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.
+- Dimers, trimers, tetramers: every protein chain in one system. Copies of one
+  protein can share parameters -- asked about once, matched residue for
+  residue by sequence and position rather than number, and a bonded metal site
+  fitted once and reused in every copy ([docs/oligomers.md](docs/oligomers.md)).
 - 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
@@ -73,6 +84,11 @@ recorded in the output reports.
   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.
+- Predicted models: the closest X-ray structure from the RCSB, and its crystal
+  waters transplanted onto the model with PyMOL -- a water on the metal moves
+  with it.
+- An official Colab notebook that prepares, equilibrates, and shows every step:
+  charges, metal-site parameters, the equilibration, the trajectory.
 
 ## Installation
 
@@ -105,9 +121,16 @@ Start from a standard protein PDB:
 
 ```bash
 mdprep inspect input.pdb
-mdprep init input.pdb -o system.yaml
+mdprep plan input.pdb                           # what must you decide?
+mdprep init input.pdb --interactive -o system.yaml
 ```
 
+`mdprep plan` lists only the manifest decisions this structure actually
+requires, and `--interactive` asks them and writes a validated manifest. See
+[Guided manifest generation](docs/guided_manifests.md). The non-interactive
+`mdprep init input.pdb -o system.yaml` still writes the commented starter
+manifest.
+
 A minimal protein-only `system.yaml` is:
 
 ```yaml
@@ -177,6 +200,28 @@ 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.
 
+For a guided workflow, use the [web input builder](https://miqueleg.github.io/mdprep/):
+it shows the structure in 3D, asks only the questions your structure needs, and
+writes a validated manifest and a bundle. Then open the
+[official Colab notebook](https://colab.research.google.com/github/miqueleg/mdprep/blob/master/examples/mdprep_colab.ipynb)
+([`examples/mdprep_colab.ipynb`](examples/mdprep_colab.ipynb)), upload the
+bundle, and it installs what the manifest needs, prepares the system,
+equilibrates it, and lets you investigate every step: the structure at each
+stage, the protonation states, the charge on every atom, the metal site's
+force constants, how the box equilibrated, and the MD trajectory.
+
+No crystal structure of your protein? Predict the complex with its cofactors
+(Boltz or AlphaFold3 in ColabFold), then let mdprep find the closest X-ray
+structure and bring its crystal waters across -- including a water bound to
+the metal, which a prediction never has:
+
+```bash
+mdprep closest-xray model.cif
+mdprep transplant-waters model.cif --reference 2FCT
+```
+
+See [Predicted structures](docs/predicted_structures.md).
+
 ## Common workflows
 
 Generate a starter manifest using PropKa and ff19SB/OPC:
@@ -215,12 +260,18 @@ specified in steps in the manifest.
 
 | Task | Documentation | Example |
 | --- | --- | --- |
+| Generating a manifest | [Guided manifest generation](docs/guided_manifests.md) | `mdprep plan`, `mdprep init --interactive` |
+| Generating one in a browser | [Web input builder](web/README.md) | `python web/build.py` |
 | 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` |
+| Predicted models: closest X-ray, crystal waters | [Predicted structures](docs/predicted_structures.md) | `mdprep closest-xray`, `mdprep transplant-waters` |
+| A water bound to a metal | [Metal centers](docs/metals.md#waters-bound-in-a-metal-site) | `examples/17_syrb2_bound_water_mcpb.yaml` |
+| Preparing, running and investigating in Colab | [Colab example notes](examples/README.md) | `examples/mdprep_colab.ipynb` |
+| Guided Colab builder (legacy) | [Colab example notes](examples/README.md) | `examples/mdprep_interactive_colab.ipynb` |
 | 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.
@@ -243,10 +294,12 @@ 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.
+mdprep does not support noncanonical amino acids inside peptide chains,
+covalent ligands, automatic loop modeling (a missing loop is left as two
+termini), a metal-bound hydroxide, ORCA, Multiwfn, more than one independently
+fitted bonded MCPB site (copies of one site in an oligomer share a single
+fit), or a bonded MCPB site bound by two chains. Unsupported chemistry fails
+explicitly.
 
 ## Development and release checks