mdprep 0.4.0__tar.gz → 0.5.1__tar.gz

{mdprep-0.4.0 → mdprep-0.5.1}/CHANGELOG.md

@@ -1,5 +1,223 @@
 # Changelog
 
+## 0.5.1 - 2026-10-26
+
+### Added
+
+- `ligands[].keep_input_hydrogens`: what to do with input hydrogens that
+  disagree with the ligand's SMILES. Unset, they are replaced and reported;
+  `true` makes the disagreement an error (a `user_mol2` implies it); `false`
+  replaces them without comparing.
+- The structure report's input-hydrogen record (how many were removed from
+  protein, water and each other residue, and which ligands kept theirs) and
+  its ligand-hydrogen record (placed from the SMILES, kept because they agree
+  with it, or replaced, with the atoms that disagreed). The builder's findings
+  list the removed hydrogens too.
+
+### Changed
+
+- A ligand's SMILES is used whether or not the input has hydrogens on it.
+  Hydrogens it has are compared with the SMILES heavy atom by heavy atom and
+  kept only if they agree; otherwise they are replaced by the SMILES's and the
+  disagreeing atoms are reported (`LIGAND_HYDROGENS_REPLACED`). A ligand with
+  any hydrogens at all used to be left as it was and its SMILES ignored, and
+  the builder did not ask for one. In consequence a ligand that arrives with
+  hydrogens needs a SMILES, unless a `user_mol2` describes it: one without is
+  refused as the structure is read, as is one with neither hydrogens nor a
+  SMILES (a hydrogen-free molecule can be declared with `expected_formula`,
+  as before, or with a SMILES that gives it none). The 7E07 tutorial's
+  ligands carry their SMILES now.
+- Every ligand whose hydrogens come from or are checked against a SMILES has
+  its electrons counted against its net charge and multiplicity as the
+  structure is read; a count the multiplicity cannot have stops the run.
+- The web builder and the official Colab notebook install a pinned mdprep
+  release (0.5.0) instead of git master, so everyone in a workshop runs the
+  same code and the manifest the builder writes is read by the version that
+  wrote it. CONTRIBUTING's release steps raise the pin after the tag has
+  published, and a test checks that the page and the notebook name the same
+  release.
+
+### Fixed
+
+- A structure that arrives with hydrogens -- a deposition refined with riding
+  hydrogens, or a model run through PyMOL, reduce, PDBFixer or a format converter --
+  no longer stops the run. `structure.remove_input_hydrogens` used to act only
+  at the end of protonation, so the hydrogens reached everything before it:
+  PyMOL and format converters protonate chlorides, and the builder refused the HCl as
+  a ligand named after an Amber ion; reduce numbers every hydrogen it adds 0,
+  and the reader refused the file for its CONECT records; a lysine's riding
+  HZ3 stopped the temporary hydrogenation for xTB, which built the neutral
+  lysine PropKa asked for; and PDBFixer's alpha-ketoglutarate, protonated as
+  the neutral acid, was kept and gave MCPB negative angle force constants.
+  The hydrogens are now removed as the structure is read, in the builder,
+  `mdprep plan`, `mdprep init` and the structure stage alike, so the plan is
+  made about the structure that is built and PDBFixer repairs that structure
+  too. A ligand's are compared with its SMILES (see Changed).
+- Structure repair lost atoms without saying so when several in a residue
+  shared a name: PDBFixer keeps one of them, and the check that no atom went
+  missing looked atoms up by name. A format converter names every hydrogen H,
+  so six of an alpha-ketoglutarate's went in and one came out. A ligand's
+  hydrogens now go round PDBFixer, which has nothing to do with them, and any
+  other merge stops the repair with the atoms it affected.
+- Atoms written more than once at partial occupancy without altloc labels --
+  a format converter keeps both conformers of a residue and drops the A and B,
+  leaving two OD2s in an aspartate at 0.50 each -- are read as the alternate
+  locations they are: labelled in file order, chosen by the altloc policy, and
+  reported. PDBFixer used to keep one of each pair without saying which.
+- A docked ligand carrying only its polar hydrogens stopped antechamber with
+  an odd number of electrons, after the protonation stage had run: having
+  hydrogens at all made the builder skip its SMILES question and the
+  preparation keep them. It now gets the SMILES's hydrogens, and a manifest
+  without its SMILES is refused at once with the reason.
+- CONECT records in a file whose atom serials repeat are followed to the
+  atoms' new numbers when the serial they name is unique, and dropped with a
+  warning when it is not, instead of the file being refused.
+- The temporary hydrogenation for the xTB histidine comparison stops only
+  when a heavy atom goes missing. A hydrogen the residue had and its assigned
+  state does not is dropped, as the hydrogens are temporary anyway.
+- One test of what a hydrogen is, the element the reader settled on, instead
+  of five that disagreed. A mercury ion written without an element column was
+  a hydrogen to two of them, and deuterium was one to only two.
+- A four-character atom name starting with H in a residue without element
+  columns (HG21, HO2') is read as a hydrogen, not as mercury or holmium.
+- The official notebook's 3D views hid the metal site they were drawn to
+  show: an Fe/alpha-KG enzyme holds its iron inside a beta-barrel, and the
+  opaque cartoon covered it. With a metal present the cartoon is now
+  translucent, every residue within the site radius is drawn as sticks (it
+  was only those within 3 A), and the view is framed on the site. Section
+  H's `SITE_RADIUS` reached the atoms it selected but not the drawing, so
+  raising it changed nothing visible; it now does both.
+
+## 0.5.0 - 2026-10-23
+
+### Added
+
+- The web builder's **Load SyrB2 (PDB 2FCT)** button: the workshop's worked
+  example, for a student with no structure of their own, fetched from RCSB as
+  a typed ID would be.
+- `mdprep.workflows.runtime.full_toolchain_manifest()`: a manifest that calls
+  every program mdprep installs, for an environment built before the real
+  manifest exists.
+- Hemes and other metals deposited inside a cofactor. The PDB writes heme b as
+  one residue, HEM, with its iron among its atoms; mdprep now moves the metal
+  into a residue of its own as any structure is read, named after the element
+  with the cofactor's chain and number, and the porphyrin left behind is a
+  ligand that coordinates it. A cytochrome P450 becomes an ordinary bonded
+  iron site: the four porphyrin nitrogens, the cysteine and the water. The
+  oxidation state is asked, not read off the assigned name. Heme b's SMILES
+  and net charge (-4, both propionates ionised) are proposed with the
+  assumption stated. See `docs/metals.md`.
+- `examples/19_cyp119_heme_mcpb.yaml` and the vendored 1IO7 deposition:
+  CYP119 at rest, low-spin Fe(III).
+- `mcpb.pyscf.xtb.electronic_temperature_kelvin`: Fermi smearing for the xTB
+  Hessian and the GFN2 ESP of the large model. An open-shell heme's SCF does
+  not converge at xTB's own 300 K; the builder sets 1000 K for a site whose
+  donors include a heme, and an SCF failure without it names the setting.
+- A residue still holding several metal atoms (an iron-sulfur cluster) and
+  heme c, a covalent ligand, are refused with the reason before any question
+  is asked.
+- Heterogens that are not ligands. mdprep reads the bonds a deposition
+  declares (PDB LINK, mmCIF `_struct_conn`) and its modified residues (MODRES,
+  `_pdbx_struct_mod_residue`), and sorts the heterogens before asking about
+  ligands: modified residues in a chain, glycans, other heterogens bonded to
+  the protein, and crystallisation additives. Each group is one question with
+  every member listed. Glycans and additives are proposed for removal, a
+  selenomethionine for replacement by methionine; anything else is asked
+  without a proposal, and keeping what cannot be built stops at the question.
+  See `docs/heterogens.md`.
+- `structure.remove_residues`: residues left out on purpose, each with its
+  reason, applied before anything else looks at the structure and reported.
+- `structure.repair.replace_modified_residues`: modified residues replaced by
+  their standard parents through PDBFixer, exactly the ones listed.
+- A metal that is not inside a cofactor can be removed on its model question
+  (a nickel from a His-tag purification). Magnesium and calcium are proposed
+  nonbonded.
+- The SMILES and net charge of FAD, FMN, SAM, SAH, NAD+, NADH, NADP+ and NADPH
+  are proposed, at pH 7, with the protonation stated; each is tested against
+  a deposited cofactor.
+- `examples/20_upo_5oxu_heme_glycans.yaml` (an unspecific peroxygenase:
+  heme-thiolate, magnesium, N-glycans, additives) and
+  `examples/21_prna_fad_halogenase.yaml` (a flavin-dependent halogenase),
+  with their depositions. `docs/enzyme_families.md` lists what mdprep does
+  with each family of halogenating and dehalogenating enzymes.
+- Refused when the structure is loaded, with the reason: a cofactor bonded to
+  the protein that holds a metal (myeloperoxidase's heme), an oxoanion such as
+  vanadate, a modified residue with no standard parent, and a declared bond
+  between protein residues that is neither a peptide bond nor a disulfide.
+
+### Changed
+
+- The spin is asked once, for the QM region. The per-metal multiplicity
+  question is gone; the QM region's answer is also the bonded site's
+  `ions[].multiplicity` and MCPB model spins.
+- Crystallisation additives are no longer offered one by one as ligands
+  unless their removal is declined.
+- The official Colab notebook takes its structure only from the builder's
+  bundle. Its predicted-model section (closest X-ray structure, crystal
+  waters), the SyrB2 example and the upload of an earlier run's results are
+  gone; `mdprep closest-xray` and `mdprep transplant-waters` still bring
+  waters across on the command line. It installs every program mdprep runs
+  first, before there is a bundle, so the install runs while the builder's
+  questions are answered; the MD follows the preparation directly, and the
+  investigation of both comes after. Sections, old to new: C to A, D to C,
+  F to D, G to F, H to G, I to H, J to I; B and E1-E8 keep their letters.
+
+- The protonation of a titratable side chain on a metal is asked right after
+  the coordination shell is confirmed, before the spin and the model charge.
+- Proposals carry their own explanation, shown by the builder and the
+  `mdprep init --interactive` wizard alike.
+
+### Fixed
+
+- A metal-bound cysteine stated as CYM stopped the protonation stage: OpenMM
+  calls the thiolate's hydrogen variant CYX. Every cysteine donor -- a zinc
+  finger's, a heme's -- reached this.
+- The proposed model charge read a donor's charge from its residue name, so a
+  cysteine stated as CYM counted as neutral and an aspartate stated as ASH as
+  -1. It now counts the state given, and proposes nothing until it is given.
+- The builder named a residue once per highlighted atom.
+- The ligand bond-order check measured conjugated single bonds against
+  saturated lengths, so every amide, amino-heterocycle and flavin looked like
+  a wrong tautomer and a SMILES for FAD, NAD or SAM could not be applied.
+- A heme on both a bonded iron and a nonbonded magnesium, as in a
+  peroxygenase, was refused for taking its charges from the magnesium's
+  non-existent fit.
+- QM/MM refinement stopped on a nonbonded metal or a crystal ion next to the
+  QM region; both are MM environment with known parameters.
+- A lysine PropKa made neutral lost a hydrogen's charge in the embedding of
+  the xTB histidine comparison: OpenMM names its amine hydrogens HZ1 and HZ2,
+  ff14SB's LYN HZ2 and HZ3. The histidines around it were compared beside a
+  lysine at -0.39 e, and the report asked for the lysine to be declared as a
+  ligand. PrnA's Lys79 reached this: its four histidines keep their states,
+  but their HID-HIE gaps moved by 1 to 3 kcal/mol, enough to flip a closer
+  call.
+- A vanadate was split into a vanadium and four unbonded oxygens.
+- Replacing a modified residue stopped the run unless
+  `structure.repair.add_missing_heavy_atoms` was set: PDBFixer keeps a blank
+  insertion code as a space, so the replaced residue's own new atoms counted
+  as unrequested. Any replacement in a structure missing nothing else reached
+  this, 1CPO's pyroglutamate among them. A chain's terminal OXT, which the
+  planner never asks about, stopped such a run too; it is left to tleap.
+- A pyroglutamate replaced by glutamine kept its lactam's CD 1.5 A from its
+  own backbone nitrogen. A replaced side chain bonded to its own backbone is
+  rebuilt beyond CB from the parent's template, listed under
+  `side_chain_rebuilt`, with a warning naming its closest contact.
+- The g-xTB Hessian of a high-spin heme site could fail to converge, or
+  converge in whichever of two states the thread count led it to: on 2QFK's
+  aquo Fe(III), 27 kcal/mol apart, with Fe-N force constants up to 1.7 times
+  different. `mcpb.pyscf.xtb.scf_annealing_kelvin` converges the SCF straight
+  and from each hotter temperature listed, single-threaded, and takes the
+  Hessian from the lowest; the builder sets it, with `max_scf_iterations:
+  3000`, for every heme site. Examples 19 and 20 carry both. 2QFK itself now
+  stops every time at the same place, a negative His-Fe-N angle constant,
+  instead of passing or failing by the thread count. See `docs/metals.md`.
+- A Seminario term MCPB.py found negative and wrote as zero was reported only
+  as a 0.0 in the frcmod; the error now names it, its atoms and its value.
+- The bond-order check read a porphyrin bond by bond, so 2QFK's heme, refined
+  with one pyrrole's beta-beta bond at single-bond length, was refused as a
+  wrong tautomer of heme b. A porphyrin's core is skipped like a carboxylate;
+  a chlorin's reduced ring is still checked.
+
 ## 0.4.0 - 2026-10-20
 
 ### Added

{mdprep-0.4.0 → mdprep-0.5.1}/CONTRIBUTING.md

@@ -74,11 +74,17 @@ To cut a release:
 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.
+   `tests/test_colab_smoke_notebook.py`.
 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.
+6. **Once the tag has published to PyPI**, raise the release the students'
+   tools install: `MDPREP_INSTALL` in `web/app.js` and the `MDPREP_VERSION`
+   default in `examples/mdprep_colab.ipynb`. They are pinned so that everyone
+   in a workshop installs the same code, and the manifest the builder writes
+   is read by the version that wrote it. Doing this after the tag keeps the
+   deployed builder from pointing at a release PyPI does not have yet; a test
+   checks that the page and the notebook name the same one.
 
 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
@@ -93,16 +99,15 @@ to the Python surface.
 
 ### Executing the official notebook outside Colab
 
-`examples/mdprep_colab.ipynb` runs anywhere with a Linux GPU. Its uploads and
+`examples/mdprep_colab.ipynb` runs anywhere with a Linux GPU. Its upload 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:
+`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); \
@@ -110,6 +115,6 @@ 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.
+the environment in `mamba-root/`). The bundle is one the web builder
+downloaded; its SyrB2 button gives one for 2FCT.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mdprep
-Version: 0.4.0
+Version: 0.5.1
 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.4.0 prepares reproducible Amber molecular-dynamics systems from a
+`mdprep` 0.5.1 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
@@ -71,7 +71,15 @@ recorded in the output reports.
 - 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.
+  coordinating atoms, charges, and multiplicities -- including a metal
+  deposited inside a cofactor: a cytochrome P450's heme iron, bonded to the
+  porphyrin, the cysteine and a water ([docs/metals.md](docs/metals.md#a-metal-inside-a-cofactor-hemes)).
+- Heterogens that are not ligands, read from the file's LINK and MODRES
+  records: glycans and crystallisation additives removed on one question
+  each, selenomethionine replaced by methionine, and FAD, FMN, SAM and the
+  nicotinamides offered with their SMILES and charge
+  ([docs/heterogens.md](docs/heterogens.md)). What this means for each family
+  of halogenating enzymes is in [docs/enzyme_families.md](docs/enzyme_families.md).
 - 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
@@ -202,13 +210,15 @@ 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
+writes a validated manifest and a bundle. With no structure of your own, it
+loads SyrB2 (PDB 2FCT) in one click. 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.
+([`examples/mdprep_colab.ipynb`](examples/mdprep_colab.ipynb)): it installs
+the programs mdprep runs while you are still in the builder, and with the
+bundle uploaded it 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
@@ -270,6 +280,9 @@ specified in steps in the manifest.
 | 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` |
+| A heme: cytochrome P450 | [Metal centers](docs/metals.md#a-metal-inside-a-cofactor-hemes) | `examples/19_cyp119_heme_mcpb.yaml` |
+| Glycans, additives, modified residues: a peroxygenase | [Heterogens](docs/heterogens.md) | `examples/20_upo_5oxu_heme_glycans.yaml` |
+| A flavin-dependent halogenase | [Enzyme families](docs/enzyme_families.md) | `examples/21_prna_fad_halogenase.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` |
@@ -294,8 +307,11 @@ charge model, protonation, force field, QM method, or metal model.
 
 ## Current limitations
 
-mdprep does not support noncanonical amino acids inside peptide chains,
-covalent ligands, automatic loop modeling (a missing loop is left as two
+mdprep does not support noncanonical amino acids inside peptide chains
+(a modified residue with a standard parent can be replaced by it), covalent
+ligands (heme c and the bonded hemes of peroxidases among them; glycans and
+other bonded heterogens can only be removed), metal clusters, oxoanions such
+as vanadate, 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

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

@@ -1,6 +1,6 @@
 # mdprep
 
-`mdprep` 0.4.0 prepares reproducible Amber molecular-dynamics systems from a
+`mdprep` 0.5.1 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
@@ -19,7 +19,15 @@ recorded in the output reports.
 - 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.
+  coordinating atoms, charges, and multiplicities -- including a metal
+  deposited inside a cofactor: a cytochrome P450's heme iron, bonded to the
+  porphyrin, the cysteine and a water ([docs/metals.md](docs/metals.md#a-metal-inside-a-cofactor-hemes)).
+- Heterogens that are not ligands, read from the file's LINK and MODRES
+  records: glycans and crystallisation additives removed on one question
+  each, selenomethionine replaced by methionine, and FAD, FMN, SAM and the
+  nicotinamides offered with their SMILES and charge
+  ([docs/heterogens.md](docs/heterogens.md)). What this means for each family
+  of halogenating enzymes is in [docs/enzyme_families.md](docs/enzyme_families.md).
 - 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
@@ -150,13 +158,15 @@ 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
+writes a validated manifest and a bundle. With no structure of your own, it
+loads SyrB2 (PDB 2FCT) in one click. 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.
+([`examples/mdprep_colab.ipynb`](examples/mdprep_colab.ipynb)): it installs
+the programs mdprep runs while you are still in the builder, and with the
+bundle uploaded it 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
@@ -218,6 +228,9 @@ specified in steps in the manifest.
 | 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` |
+| A heme: cytochrome P450 | [Metal centers](docs/metals.md#a-metal-inside-a-cofactor-hemes) | `examples/19_cyp119_heme_mcpb.yaml` |
+| Glycans, additives, modified residues: a peroxygenase | [Heterogens](docs/heterogens.md) | `examples/20_upo_5oxu_heme_glycans.yaml` |
+| A flavin-dependent halogenase | [Enzyme families](docs/enzyme_families.md) | `examples/21_prna_fad_halogenase.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` |
@@ -242,8 +255,11 @@ charge model, protonation, force field, QM method, or metal model.
 
 ## Current limitations
 
-mdprep does not support noncanonical amino acids inside peptide chains,
-covalent ligands, automatic loop modeling (a missing loop is left as two
+mdprep does not support noncanonical amino acids inside peptide chains
+(a modified residue with a standard parent can be replaced by it), covalent
+ligands (heme c and the bonded hemes of peroxidases among them; glycans and
+other bonded heterogens can only be removed), metal clusters, oxoanions such
+as vanadate, 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

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

@@ -8,6 +8,8 @@
 - [Protonation](protonation.md)
 - [Ligands](ligands.md)
 - [Metal centers](metals.md)
+- [Heterogens that are not ligands](heterogens.md)
+- [Halogenating and dehalogenating enzymes](enzyme_families.md)
 - [Dimers, trimers and tetramers](oligomers.md)
 - [Predicted structures](predicted_structures.md)
 - [MCPB Hessian-method benchmark](mcpb_xtb_benchmark.md)

mdprep-0.5.1/docs/enzyme_families.md

@@ -0,0 +1,78 @@
+# Halogenating and Dehalogenating Enzymes
+
+Enzymes that put a halogen on a carbon, or take one off, come from a dozen
+families with little chemistry in common: non-heme iron, heme-thiolate and
+heme-histidine centres, vanadate, flavins, SAM, corrinoids and iron-sulfur
+clusters, and several with no cofactor at all. This page lists what mdprep
+does with a representative of each, so that you know before you start whether
+your enzyme is something it prepares, what it will ask, and where it stops.
+
+Every representative below was loaded into the planner (`mdprep plan`, the web
+builder and the Colab notebook all use it); the ones marked **prepared** were
+also taken through the whole toolchain to a validated Amber topology.
+
+| Family | Representative | What mdprep does |
+| --- | --- | --- |
+| Fe(II)/alpha-ketoglutarate halogenases | SyrB2 (2FCT), BesD (6NIE) | **Prepared.** Bonded Fe(II) site with the chloride and alpha-ketoglutarate in the MCPB model; examples 16-18. |
+| Cytochrome P450 | CYP119 (1IO7) | **Prepared.** The heme's iron is read out into a residue of its own and bonded to the porphyrin, the cysteine thiolate and the water; example 19. |
+| Unspecific peroxygenases (UPO) | AaeUPO (5OXU, 2YOR) | **Prepared.** Heme-thiolate as for a P450; the N-glycans and crystallisation additives removed on two questions; the magnesium on the heme's propionate nonbonded; example 20. |
+| Chloroperoxidase | *C. fumago* CPO (1CPO) | **Prepared.** Heme-thiolate with no water on the iron: five-coordinate high-spin Fe(III), spin 6. 21 sugars (N- and O-linked) removed; the N-terminal pyroglutamate replaced by glutamine, whose side chain is rebuilt and starts close to Ser4 (minimise before anything else); the manganese nonbonded beside the bonded iron, since one bonded site is fitted per preparation. |
+| Dehaloperoxidase | DHP A (2QFK) | **Not prepared.** A globin: heme bonded to the proximal histidine and the distal water, high-spin aquo Fe(III), spin 6; ammonium and sulfate additives removed. g-xTB's SCF for this site has several states, and in the lowest the search finds, one His-Fe-N angle's Seminario force constant is negative: mdprep stops there and names it ([metals.md](metals.md#a-zero-force-constant-is-reported-not-shipped)). |
+| Myeloperoxidase, lactoperoxidase | MPO (1CXP) | **Refused**: the heme is bonded to the protein through three side chains (a covalently attached cofactor). |
+| Vanadium haloperoxidases | *C. inaequalis* VCPO (1IDQ) | **Refused**: vanadate is an oxoanion, not a metal site mdprep can build. |
+| Flavin-dependent halogenases | PrnA (2AR8), RebH (2OA1) | **Prepared** (PrnA). FAD's SMILES and charge (-2) are proposed; the substrate or product is typed in; example 21. RebH's free tryptophan carries the amino acid's name and is offered a rename first. |
+| SAM-dependent fluorinase and chlorinase | FlA (1RQR, 2V7V) | **Prepared** (2V7V). SAM, SAH proposed; 5'-fluoro-5'-deoxyadenosine typed in (`FCC1OC(n2cnc3c(N)ncnc32)C(O)C1O`, charge 0). The active site lies between two subunits: keep all chains. 1RQR's selenomethionines are replaced by methionine on one question, and its free methionine is offered a rename. |
+| Haloalkane dehalogenases | DhaA (4E46), DhlA (2DHC) | **Prepared** (both). No cofactor: 4E46's isopropanol and acetates removed and its chloride kept as a crystal ion; 2DHC's 1,2-dichloroethane typed in as a ligand. |
+| L-2-haloacid dehalogenases | 1ZRN | **Prepared.** The ester intermediate on the catalytic aspartate is a heterogen bonded to the protein: removing it is asked, with nothing proposed; removed, the aspartate is prepared free. |
+| Fluoroacetate dehalogenase | FAcD (3R3U) | **Prepared.** The nickel from the His-tag purification removed on its model question. |
+| Iodotyrosine deiodinase | IYD (4TTB) | **Prepared.** FMN's SMILES and charge (-2) are proposed. FMN sits between the two chains of the dimer: keep both, and chain B's FMN takes chain A's parameters. |
+| Reductive dehalogenases | RdhA (4UR0, 4RAS) | **Refused**: two [4Fe-4S] clusters, which no single metal site describes (as are the [2Fe-2S] clusters of Rieske oxygenases). |
+
+## What a student meets on the way
+
+- **Glycans.** Fungal peroxygenases are glycoproteins. Sugars bonded to the
+  protein are found from the file's LINK records, or by bond length if it has
+  none, and removing them is one question, proposed yes. See
+  [heterogens.md](heterogens.md#glycans).
+- **Crystallisation additives.** Glycerol, methanol, sulfate, phosphate, PEG:
+  one question, proposed yes, every residue listed. Answer no to be asked
+  about each as a ligand.
+- **Modified residues.** Selenomethionine is replaced by methionine on one
+  question. Anything else modified is asked with nothing proposed. A
+  pyroglutamate (chloroperoxidase's N-terminus) becomes a glutamine whose side
+  chain is built afresh and whose N-terminus is charged; the report says how
+  close the new side chain starts to its neighbours. See
+  [heterogens.md](heterogens.md#modified-residues).
+- **Active sites between chains.** IYD's FMN and the fluorinase's substrate
+  are each held by two subunits: chain A alone leaves a third to nearly half
+  of the residues around them out, so keep all chains (the default). Copies
+  share their parameters ([oligomers.md](oligomers.md)); a ligand the file
+  names after the other chain of its site, as 2V7V does one of its three, is
+  asked about again, and the same answers serve.
+- **A metal that is not part of the system.** A His-tag nickel, a buffer
+  cadmium: the metal's model question offers to remove it.
+- **Magnesium and calcium** are proposed nonbonded.
+- **Organic cofactors.** FAD, FMN, SAM, SAH, NAD+, NADH, NADP+ and NADPH are
+  recognised by name and atoms, and their SMILES and charge at pH 7 are
+  proposed with the protonation they assume. A reduced flavin (FADH-) is a
+  different molecule: change the SMILES and the charge if that is the state you
+  simulate.
+- **Two metals and one heme.** In a peroxygenase the heme holds its iron and,
+  through a propionate, a magnesium; in chloroperoxidase a manganese. The iron
+  is fitted with MCPB.py and the heme's charges come from that fit; the other
+  metal stays a nonbonded ion, and the QM/MM refinement of the iron's site
+  treats it as part of the MM environment.
+- **The iron's spin.** It is asked, with what usually decides it: the
+  chloroperoxidase iron has no water across from its cysteine (five-coordinate,
+  high-spin Fe(III), 6), the dehaloperoxidase iron has one across from its
+  histidine (high-spin aquo Fe(III), 6), a resting peroxygenase's water makes
+  it low-spin (2).
+
+## Where mdprep stops
+
+Covalently attached cofactors (heme c, the hemes of myeloperoxidase and
+lactoperoxidase), vanadate and other oxoanions, iron-sulfur clusters,
+corrinoids together with their clusters, modified residues with no standard
+parent, and protein-protein crosslinks other than disulfides are refused when
+the structure is loaded, with the reason. Two metal sites that would each need
+their own MCPB fit are refused at the question that makes them so.

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

@@ -41,16 +41,40 @@ that. These have no suggested value, and a front end cannot skip them:
 
 - **Ligand net charge.** It cannot be read from a PDB file, and a wrong value
   produces a plausible-looking topology with the wrong electrostatics.
+- **Ligand SMILES**, for every ligand, whether or not the file has hydrogens
+  on it: a ligand's protonation comes from its SMILES, and hydrogens the file
+  has are compared with it when the system is prepared -- kept if they agree,
+  replaced if not. The question says how many the file had. The SMILES of a
+  few well-known cofactors is proposed.
 - **Metal site model and oxidation state.** Neither the residue name nor the
   element implies an oxidation state. Zn is almost always +2; Fe and Cu are not.
 - **Removing unknown heterogens.** Normalization must never discard a residue
   that was not explicitly configured, so the question names every residue at
   stake.
+- **Removing a heterogen bonded to the protein**, a covalent intermediate for
+  instance, and **replacing a modified residue** other than a selenomethionine.
 - **Production length**, when MD is enabled. There is no sensible default.
 
 Free monatomic metals are offered as metal sites, never as GAFF ligands. Bulk
 counterions are treated as solvent and are not asked about at all.
 
+## Heterogens that are not ligands
+
+Before the ligands, the planner sorts out the heterogens that are not ones,
+and asks about each group once, with every member listed:
+
+- **Modified residues** in a chain -- replace each with its standard parent?
+  Proposed yes for selenomethionine; asked without a proposal otherwise.
+- **Glycans** bonded to the protein -- remove them? Proposed yes.
+- **Other heterogens bonded to the protein** -- remove them? No proposal.
+- **Crystallisation additives** -- remove them? Proposed yes. Answer no to be
+  asked about each as a ligand.
+
+Keeping a group mdprep cannot build stops the build at that question, and
+every removal is written to `structure.remove_residues` with its reason. See
+[heterogens.md](heterogens.md), and [enzyme_families.md](enzyme_families.md)
+for what this means for each family of halogenating enzymes.
+
 ## Metal sites
 
 Choosing `bonded_mcpb` proposes a coordination sphere from interatomic
@@ -64,11 +88,34 @@ and the site is reported for manual work rather than invented. The oxidation
 state, the spin multiplicity and the capped-model charge have no defaults
 either, because none of them can be read off a structure.
 
+The spin is asked once, for the QM region: the metal, everything bonded to it
+and the cofactors. One bonded site is fitted per preparation and the cofactors
+in it are closed shell, so that one answer is also the spin of the site's
+MCPB.py models (`ions[].multiplicity`, `mcpb.small_model_spin`,
+`mcpb.large_model_spin`), and the metal is not asked separately. The question
+says what usually decides it: high-spin Fe(II) is 5, high-spin Fe(III) 6,
+Zn(II) 1, and for a heme, the ligands across the heme plane.
+
 A ligand that coordinates the metal takes its charges from that site's MCPB fit
 rather than an independent AM1-BCC calculation, since fitting a bonded donor
 separately leaves the site electrostatically inconsistent. A ligand that does
 not coordinate keeps AM1-BCC.
 
+A titratable side chain on the metal -- an aspartate, a cysteine -- is asked
+its protonation right after the shell is confirmed, before the model charge. The model charge is then proposed from the states as given:
+a heme's cysteine is named CYS and counts as the thiolate, -1, once it has been
+stated as CYM.
+
+A metal deposited inside a cofactor, a heme's iron, is read out into a residue
+of its own, and the porphyrin left behind is a ligand on it. Heme b's SMILES
+and net charge are proposed, with the protonation they assume, and so are
+FAD's, FMN's, SAM's, SAH's and the nicotinamides'; any other ligand's are
+asked. See [metals.md](metals.md#a-metal-inside-a-cofactor-hemes) and
+[ligands.md](ligands.md#cofactors-whose-smiles-is-proposed).
+
+Magnesium and calcium are proposed nonbonded, and a metal that is not inside
+a cofactor can be removed instead of modelled -- a nickel from a His-tag, say.
+
 The Hessian defaults to GFN2, which is orders of magnitude cheaper than DFT and
 is what makes a bonded site tractable outside a cluster; g-xTB and PySCF DFT
 are offered too. The geometry comes from the QM/MM refinement stage, which is