mdprep 0.3.0__tar.gz → 0.4.0__tar.gz

{mdprep-0.3.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.3.0 → mdprep-0.4.0}/CHANGELOG.md

@@ -1,5 +1,153 @@
 # 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-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.3.0 → mdprep-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mdprep
-Version: 0.3.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
@@ -52,7 +52,7 @@ Description-Content-Type: text/markdown
 
 # mdprep
 
-`mdprep` 0.3.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
@@ -72,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
@@ -80,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
 
@@ -191,22 +200,27 @@ 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 3D workflow, upload
-[`examples/mdprep_interactive_colab.ipynb`](examples/mdprep_interactive_colab.ipynb)
-to Google Colab. It accepts an RCSB PDB ID or uploaded PDB, requires review of
-all structural and chemistry decisions, creates a validated manifest, and can
-either download a portable input bundle or run mdprep in Colab. BesD PDB 7JSD
-is the default structural example; charges, spin states, and metal chemistry
-remain explicit user decisions. For bonded MCPB preparation, a dedicated cell
-installs the pinned official g-xTB Linux build and accepts it only after
-checksum verification and a successful `--gxtb --hess` smoke calculation. The
-guided metal workflow supports one explicitly bonded, single-chain MCPB site
-and can select either that g-xTB Hessian or PySCF B3LYP/6-31G*; every
-coordination bond remains explicitly selected. The notebook derives the MCPB
-small/large-model charge and multiplicity and the complete QM-region
-multiplicity from the reviewed component electronic states, displays the
-calculation, and refuses ambiguous multi-open-shell spin coupling rather than
-guessing it. All multi-selection fields use comma-separated values.
+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
 
@@ -254,7 +268,9 @@ specified in steps in the manifest.
 | 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` |
-| Running a manifest in Colab | [Colab example notes](examples/README.md) | `examples/mdprep_colab_run.ipynb` |
+| 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` |
 
@@ -278,10 +294,12 @@ charge model, protonation, force field, QM method, or metal model.
 
 ## Current limitations
 
-Version 0.3.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
 

{mdprep-0.3.0 → mdprep-0.4.0}/README.md

@@ -1,6 +1,6 @@
 # mdprep
 
-`mdprep` 0.3.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
@@ -20,6 +20,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
@@ -28,6 +32,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
 
@@ -139,22 +148,27 @@ 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 3D workflow, upload
-[`examples/mdprep_interactive_colab.ipynb`](examples/mdprep_interactive_colab.ipynb)
-to Google Colab. It accepts an RCSB PDB ID or uploaded PDB, requires review of
-all structural and chemistry decisions, creates a validated manifest, and can
-either download a portable input bundle or run mdprep in Colab. BesD PDB 7JSD
-is the default structural example; charges, spin states, and metal chemistry
-remain explicit user decisions. For bonded MCPB preparation, a dedicated cell
-installs the pinned official g-xTB Linux build and accepts it only after
-checksum verification and a successful `--gxtb --hess` smoke calculation. The
-guided metal workflow supports one explicitly bonded, single-chain MCPB site
-and can select either that g-xTB Hessian or PySCF B3LYP/6-31G*; every
-coordination bond remains explicitly selected. The notebook derives the MCPB
-small/large-model charge and multiplicity and the complete QM-region
-multiplicity from the reviewed component electronic states, displays the
-calculation, and refuses ambiguous multi-open-shell spin coupling rather than
-guessing it. All multi-selection fields use comma-separated values.
+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
 
@@ -202,7 +216,9 @@ specified in steps in the manifest.
 | 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` |
-| Running a manifest in Colab | [Colab example notes](examples/README.md) | `examples/mdprep_colab_run.ipynb` |
+| 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` |
 
@@ -226,10 +242,12 @@ charge model, protonation, force field, QM method, or metal model.
 
 ## Current limitations
 
-Version 0.3.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
 

{mdprep-0.3.0 → mdprep-0.4.0}/docs/README.md

@@ -8,6 +8,8 @@
 - [Protonation](protonation.md)
 - [Ligands](ligands.md)
 - [Metal centers](metals.md)
+- [Dimers, trimers and tetramers](oligomers.md)
+- [Predicted structures](predicted_structures.md)
 - [MCPB Hessian-method benchmark](mcpb_xtb_benchmark.md)
 - [7E07 Fe(III) bonded-site tutorial](../examples/tutorials/7E07_bonded_fe3/README.md)
 - [QMMESP charges with PySCF](qmmesp_pyscf.md)

{mdprep-0.3.0 → mdprep-0.4.0}/docs/guided_manifests.md

@@ -107,7 +107,16 @@ Each decision carries a stable `id`, the `question`, its `kind`
 (`choice`, `integer`, `number`, `text`, `boolean`), the allowed `choices`, the
 `default` (`null` when there is none), `requires_user_input`, the `evidence`
 from the structure, and a `when` list naming the earlier answers that make it
-relevant.
+relevant. A decision is asked when every condition in `when` holds and, if its
+`when_any` list is not empty, at least one condition there does too; an answer
+counts only while its own question is still asked.
+
+In a structure with several copies of one protein, a copy's questions carry
+`copy_of`: the id of the same question about the counterpart residue in the
+first copy. They are skipped when the copies share parameters
+(`structure.same_parametrization`), and `build_manifest` gives them that
+question's answer. A front end needs to do nothing about this beyond
+honouring `when_any`; see [oligomers.md](oligomers.md).
 
 ### Driving a 3D viewer
 
@@ -115,8 +124,11 @@ Each decision also says what a viewer should put on screen while it is being
 answered:
 
 - `focus` is `none` (no structural aspect, such as a project name),
-  `targets` (emphasise and frame the residues below), or `structure` (show the
-  whole system, as for the force field or the solvent box).
+  `targets` (emphasise and frame the residues below), `structure` (show the
+  whole system, as for the force field or the solvent box), or `chains` (the
+  whole system with each chain in its own colour and the residues below
+  emphasised in every copy, as for which chains to keep and whether copies
+  match).
 - `targets` lists the residues to highlight, each with `chain`, `resname`,
   `resid`, `icode`, and `element`/`atom_name` where they apply. **`targets[0]`
   is the subject of the decision** -- the ligand being charged, the ion being
@@ -150,3 +162,12 @@ manifest = build_manifest(plan, answers)  # raises if a blocking answer is missi
 `build_manifest` returns a plain dictionary, and raises `DecisionError` rather
 than defaulting anything a user was supposed to decide. That guarantee is what
 makes it safe to put a graphical front end in front of mdprep at all.
+
+A `DecisionError` carries `decision_id`, the question whose answer would
+resolve it, when there is one; the web builder takes the user back to it.
+Some refusals are certain before the last question -- a second bonded metal
+site that would need an MCPB fit of its own, or a cofactor whose charges were
+to come from a site that is no longer bonded. `answer_conflicts(plan,
+answers)` returns that refusal as soon as the answers given make it certain,
+so a front end can say so at the question that caused it, as the web builder
+and `mdprep init --interactive` do.

{mdprep-0.3.0 → mdprep-0.4.0}/docs/manifest_reference.md

@@ -30,11 +30,18 @@ relative executable path when needed.
 
 ## structure
 
-- `keep_chains`: chains to build; empty keeps all. Naming one chain is required
-  for a bonded MCPB metal site, whose inputs are single-chain, and is how a
-  crystal structure containing several copies of a complex is reduced to one.
-  Chains holding only heterogens or water are kept regardless.
-- `keep_crystal_waters`: keep waters in the input PDB.
+- `keep_chains`: chains to build; empty keeps all, which is how a dimer,
+  trimer or tetramer is prepared whole. Naming chains is how a crystal
+  structure holding several copies of a complex is reduced to one. A chain
+  holding only heterogens -- a prediction's ligand, say -- is listed with the
+  protein chain it belongs to; see [oligomers.md](oligomers.md).
+- `keep_crystal_waters`: keep waters in the input PDB. A water bound to a
+  metal the build keeps -- bonded or nonbonded, within 2.6 A -- stays with it
+  regardless, and a bonded site with QM/MM refinement requires `true`.
+- `keep_crystal_ions`: keep free monatomic ions (Cl-, Na+, Br-, ...) resolved
+  in the input. Default `true`. tleap builds them from its ion library; a
+  halide bound to a bonded metal site is kept regardless. Every ion kept or
+  removed is listed in `reports/structure_report.md`.
 - `altloc_policy`: `highest_occupancy`, `first`, or `fail`.
 - `remove_unknown_heterogens`: remove unconfigured heterogens instead of
   failing.
@@ -109,6 +116,10 @@ Each ligand has:
 - optional `user_frcmod`
 - preservation controls for names and coordinates
 - optional `qmmesp` block for PySCF charge workflows
+- optional `parameters_from`: the id of a ligand with the same residue name
+  whose parameters this one is built with -- the same cofactor in another copy
+  of the protein, parameterised once. Every other setting must repeat that
+  ligand's. See [oligomers.md](oligomers.md).
 
 ## qmmesp
 
@@ -142,6 +153,15 @@ Each site has:
   - `multiplicity`: optional for ordinary metal parameterization, but mandatory
     when the ion's site is selected for QM/MM refinement.
 
+- `parameters_from`: optional; the id of the site in another copy of the
+  protein whose parameters this site reuses. A bonded copy is not fitted: it
+  takes the reference's MCPB.py templates and bond parameters residue by
+  residue, so it lists its ions, coordinating ions, bonds and additional
+  residues in the reference's order, each the counterpart of the one in the
+  same place. Every other setting repeats the reference's. Only one bonded site
+  per preparation may be fitted, that is, have no `parameters_from`. See
+  [oligomers.md](oligomers.md).
+
 For `model: nonbonded`, `nonbonded.parameter_set` is mandatory and must be
 `12_6`, `cm`, `hfe`, `iod`, or `12_6_4`. Availability is checked against the
 active AmberTools data for the configured TIP3P or OPC water model.