mdprep 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,5 +1,135 @@
 # Changelog
 
+## 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.0}/CONTRIBUTING.md

@@ -93,16 +93,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 +109,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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mdprep
-Version: 0.4.0
+Version: 0.5.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.4.0 prepares reproducible Amber molecular-dynamics systems from a
+`mdprep` 0.5.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
@@ -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.0}/README.md

@@ -1,6 +1,6 @@
 # mdprep
 
-`mdprep` 0.4.0 prepares reproducible Amber molecular-dynamics systems from a
+`mdprep` 0.5.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
@@ -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.0}/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.0/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.0}/docs/guided_manifests.md

@@ -46,11 +46,30 @@ that. These have no suggested value, and a front end cannot skip them:
 - **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 +83,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

mdprep-0.5.0/docs/heterogens.md

@@ -0,0 +1,152 @@
+# Heterogens That Are Not Ligands
+
+A deposition's heterogens are not all molecules to parameterise. Some are
+pieces of the protein: a selenomethionine is a methionine labelled to solve
+the phases, written as a heterogen because its name is not one of the twenty.
+Some are bonded to it: the sugars of a glycoprotein, a covalent intermediate,
+the heme of a myeloperoxidase. Many are what the crystal was grown in:
+glycerol, sulfate, PEG, methanol.
+
+Offering each of these as a ligand asks for the SMILES and charge of fifteen
+glycerols, and builds a sugar bonded to an asparagine as a free molecule at
+bond length from it. So mdprep sorts them first, and asks about each group as
+a group. Nothing is removed without the manifest saying so: every removal is
+listed under `structure.remove_residues` with its reason, and reported.
+
+## How mdprep knows
+
+A bond cannot be told from a clash by distance: a predicted complex has ligand
+atoms 1.8 A from the protein that are not bonded to it. A deposition says
+which atoms are bonded across residues, and mdprep reads that:
+
+| | PDB file | mmCIF |
+| --- | --- | --- |
+| Bonds between residues | `LINK` | `_struct_conn` |
+| Modified polymer residues and their parents | `MODRES` | `_pdbx_struct_mod_residue` |
+
+A bond to a symmetry mate is not a bond in the molecule being built and is
+ignored. Two things are also found without them, for a file another program
+rewrote or a prediction:
+
+- a heterogen with a backbone (`N`, `CA`, `C`) peptide-bonded to the protein
+  is a residue of the chain; a free amino acid, which has the same atoms and no
+  peptide bond, stays a ligand;
+- a carbohydrate (NAG, MAN, BMA, FUC, ...) with an atom within 1.75 A of the
+  protein's is bonded to it. Nothing else sits that close to a protein in a
+  crystal; a sugar is the one heterogen for which distance is enough.
+
+`mdprep plan` lists what it found under `modified_residues`, `glycans`,
+`covalent_heterogens` and `additives`.
+
+## Modified residues
+
+A modified amino acid inside a chain cannot be built: no force field template
+bonds it in. The question is whether to replace each with its standard parent
+(`MSE` with `MET`, `CSO` with `CYS`, `SEP` with `SER`, `PCA` with `GLN`),
+which keeps the backbone and the atoms the two share and builds the rest
+through PDBFixer:
+
+```yaml
+structure:
+  repair:
+    backend: pdbfixer
+    replace_modified_residues:
+      - selector: {chain: A, resname: MSE, resid: 14}
+        parent: MET
+```
+
+For selenomethionine the answer is proposed, yes: the selenium is how the
+methionine was labelled, not chemistry of the protein. For anything else
+nothing is proposed, because the modification may be what the structure is
+about: a phosphoserine replaced by serine has lost its phosphate. Answering no
+stops the build. The parent comes from the file's `MODRES` records when it has
+them, otherwise from a short table in `mdprep.structure.heterogens`; a
+modified residue with no known parent is refused when the structure is loaded
+(noncanonical amino acids inside a chain are not supported).
+
+A replacement needs nothing else repaired: what the parent has and the
+modified residue lacked is built whether or not `add_missing_heavy_atoms` is
+set, and a chain's terminal `OXT` is left to tleap, as it is when nothing is
+repaired.
+
+A pyroglutamate (`PCA`), the N-terminus of many secreted proteins, is a
+glutamine whose side chain has closed onto its own nitrogen as a lactam. The
+two share atom names but not their places -- kept where they are, the
+glutamine's CD would sit 1.5 A from its backbone N -- so a side chain bonded
+to its own backbone (only proline's may be) is deleted beyond CB and built
+again from the parent's template. The report lists the rebuilt atoms under
+`side_chain_rebuilt`, and a warning says how close the new side chain comes
+to its neighbours: PDBFixer places it in its template's rotamer and only
+pushes apart atoms closer than 1.3 A, so on 1CPO the glutamine's NE2 starts
+1.5 A from Ser4's OG, and tleap puts Ser4's hydroxyl hydrogen almost on top of
+it. Minimise before anything else: a plain minimisation of the prepared 1CPO
+separates them, leaving Ser4's hydroxyl hydrogen-bonded to Glu1's carbonyl and
+every bond of both residues at its length. The replacement also changes the
+chemistry: a pyroglutamate's N-terminus is a neutral lactam, a glutamine's a
+charged amine.
+
+## Glycans
+
+Sugars bonded to the protein, and every sugar bonded to those. mdprep does not
+build glycans -- their force field, GLYCAM, is not part of it -- so the
+question is whether to remove them, and the proposal is yes: the protein is
+prepared as if deglycosylated, which is the usual choice when they are far
+from the site being studied. Check that none is near yours. Answering no stops
+the build.
+
+## Heterogens bonded to the protein
+
+Anything else the file declares bonded to the protein: a covalent
+intermediate, an inhibitor, a cofactor attached to a side chain. mdprep does
+not build covalent ligands, so the question is whether to remove them, and
+nothing is proposed, because the intermediate may be what the structure was
+solved to show. Answering no stops the build.
+
+Refused when the structure is loaded, with the reason:
+
+- a bonded cofactor that holds a metal -- the heme of a myeloperoxidase or
+  lactoperoxidase, held by ester and sulfonium bonds; removing it would take
+  its metal site with it;
+- a bonded heterogen that coordinates a metal;
+- a declared bond between two protein residues that is neither a peptide bond
+  nor a disulfide (a Tyr-Cys or His-Tyr crosslink), which tleap would build
+  unbonded.
+
+## Crystallisation additives
+
+Components of buffers, cryoprotectants and precipitants: GOL, EDO, PEG, PG4,
+PGE, 1PE, P6G, 2PE, 12P, 15P, PE4, PE5, P33, MPD, MRD, MOH, EOH, IPA, DMS, ACT,
+ACY, FMT, SO4, PO4, NO3, NH4, TRS, EPE, MES, BTB, B3P, CIT, FLC, MLI, IMD, BME,
+DTT and CAC. Removing them is proposed, every one listed with what it is. Some
+are not artefacts -- a sulfate can sit where a substrate's phosphate binds, an
+alcohol in a substrate tunnel -- so check the list against your active site.
+Answer no and each is asked about as a ligand instead, where it can be
+included or declined one by one.
+
+A heterogen that coordinates a metal is part of that site, and is never on
+this list whatever its name.
+
+## Metals that are not part of the system
+
+A metal that is not inside a cofactor can also be removed: a nickel from a
+His-tag purification, a cadmium or zinc from the crystallisation buffer. Its
+model question offers **Remove it** besides bonded and nonbonded, and nothing
+more is asked about it. A cofactor's metal -- a heme's iron -- cannot be
+removed without its cofactor.
+
+Magnesium and calcium are proposed nonbonded even with a coordination shell:
+they are closed-shell ions held by electrostatics, which an ion model
+describes. Every other metal with a shell is proposed bonded.
+
+## What is refused outright
+
+- **Metal clusters**: a residue holding several metal atoms, such as an
+  iron-sulfur cluster (SF4, FES, F3S) -- the [4Fe-4S] clusters of a reductive
+  dehalogenase, the [2Fe-2S] of a Rieske oxygenase.
+- **Oxoanions**: a metal whose other atoms are bonded to nothing but it,
+  such as the vanadate of a vanadium haloperoxidase. It is neither a metal
+  site mdprep can build around a one-atom metal nor a ligand antechamber can
+  parameterise.
+
+See [enzyme_families.md](enzyme_families.md) for how each family of
+halogenating and dehalogenating enzymes is handled.