mdprep 0.2.0__tar.gz → 0.3.0__tar.gz

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

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

mdprep-0.3.0/CHANGELOG.md

@@ -0,0 +1,219 @@
+# Changelog
+
+## 0.3.0 - 2026-10-19
+
+### Added
+
+- `mdprep plan` and `mdprep init --interactive`: a structure-aware decision
+  engine that reduces a 250+ setting schema to the questions one structure
+  actually needs, and asks them. Chemistry-sensitive values have no default and
+  cannot be skipped.
+- Each decision carries viewer hints (`focus`, `targets`, `target_resnames`) so
+  a 3D front end can frame exactly the residues a question is about.
+- `mdprep inspect` reports free monatomic metal ions.
+- A static web input builder (`web/`) that runs mdprep in the browser under
+  Pyodide, shows a 3D view framed on whatever each question is about, and
+  produces a validated manifest plus runnable Colab cells.
+- `mdprep.workflows.runtime.conda_packages_for` derives the external toolchain a
+  given manifest needs, so a generated setup cell installs PropKa, xTB or PySCF
+  only when the run will actually invoke them.
+
+- `mdprep doctor` checks that the external tools a given manifest will invoke
+  are installed, and names the one command that installs what is missing.
+- mmCIF and ModelCIF input: a structure predicted by Boltz or AlphaFold is read
+  directly, with no conversion step and no loss of the chain and residue
+  identifiers the manifest selects on.
+- Four-character residue names, hybrid-36 serial and residue numbers, and
+  residues whose name does not fit a PDB column, which a predicted structure
+  written to PDB reaches routinely. A name mdprep has to assign is recorded as
+  assigned, so nothing downstream reads chemistry into a name it invented.
+- `metals[].coordinating_ions` declares a non-metal ion bound in a metal site,
+  such as a coordinating halide, which previously had nowhere to live: it is
+  not a metal, and antechamber cannot treat a single atom.
+- The setup cell downloads the g-xTB build of xtb from the Grimme group's
+  releases and checks it against the published checksum, because conda-forge
+  carries only the GFN-only build.
+
+- `structure.keep_chains` restricts a build to named chains, which a bonded
+  MCPB site requires and a multi-copy crystal structure needs.
+- The decision engine proposes a metal coordination sphere from interatomic
+  distances, requires it to be confirmed, and generates the bonded MCPB block
+  with a GFN2 Seminario Hessian and GFN2 QM/MM refinement geometry.
+- `examples/16_besd_halogenase_gfn2_mcpb.yaml`, the BesD halogenase reference
+  case.
+- Detection of incomplete residues and chain breaks, asked about before any
+  expensive stage runs, and protection for waters coordinating a metal.
+- `examples/mdprep_colab_run.ipynb`, a Colab notebook that runs a manifest and
+  installs only the toolchain that manifest needs.
+
+- `metals[].coordinating_ions` declares a non-metal ion bound in a metal site,
+  such as a coordinating halide, which previously had nowhere to live: it is
+  not a metal and antechamber cannot treat a single atom.
+
+### Changed
+
+- The refinement stage defaults to `backend: openmm`, a force-field hydrogen
+  relaxation, instead of GFN2 QM/MM. The stage only ever moved hydrogens, and
+  a force field settles them in seconds. `backend: ash` keeps the QM/MM route
+  and is required to relax heavy atoms. `movable_atoms` and
+  `post_refinement_protonation` default to match the hydrogen-only backend.
+- Histidine HID/HIE selection stays with xTB: force-field energies of the two
+  tautomers are not comparable, because they are different residue templates
+  rather than one molecule with a proton moved.
+
+- Dropped the unused `scipy` and `pandas` runtime dependencies.
+- A ligand that coordinates a bonded metal site now defaults to taking its
+  charges from that site's MCPB fit instead of AM1-BCC.
+- A metal site's Hessian defaults to g-xTB rather than GFN2. GFN2 has no
+  parameters for most transition metals, and said so only after the run had
+  got as far as the Hessian.
+- **A ligand whose residue name an Amber force field already defines is now
+  refused, where it used to be renamed for the build.** `LYS` became `LY1`,
+  which satisfied tleap and moved the problem: the prepared system then
+  described a residue under a name the input never used, and every later
+  reader had to know about the substitution. A manifest that declares such a
+  ligand now fails, in the GUI before it asks anything and on the command line
+  before any quantum chemistry, and says which residue to rename. The web
+  builder offers to make the change in the input.
+- **`refinement.total_qm_multiplicity` is now required whenever any component
+  of the QM region is open-shell**, where it used to be taken from the first
+  open-shell component found. For a lone high-spin Fe(II) that is the right
+  answer and it was right by accident: it holds only while the ion is the
+  single unpaired centre and nothing couples to it, which nothing in a
+  manifest can check. Existing manifests that leave it out of an open-shell
+  region will fail validation and need the value added.
+- Preparing the same system the same way twice now yields the same atom count.
+  MD starting velocities stay random and the seed drawn for each run is
+  recorded, so a replicate can be repeated by putting that number back.
+
+### Fixed
+
+- Per-step MD snapshots are written in the box the manifest asked for. They
+  carried the pre-NPT cell, because `PDBFile` takes CRYST1 from the topology
+  and the topology was the one loaded at the start, and they were wrapped into
+  the parallelepiped OpenMM spans rather than imaged about the solute -- so a
+  truncated octahedron came back as a sheared prism with the protein off to
+  one side and its water drawn 70 A away instead of 54 A.
+- The ESP grid survives an xTB crash on its last point, and the fit uses the
+  grid that was actually evaluated rather than the one that was requested.
+- A metal in a predicted structure is named after its element, so a site is
+  not identified by a name the prediction never meant as one.
+- CONECT records that cover only part of a ligand are ignored rather than
+  treated as its whole connectivity.
+- tleap writes its own atom types into the element column of the PDB it
+  outputs; the reader no longer believes them.
+- The setup cell installs PDBFixer whenever a run will need it, not only when
+  structure repair happens to pull it in, and the resolver is checked against
+  every combination of options rather than the one that was reported.
+- A titratable side chain coordinating a metal is asked about, from the same
+  contact list the bonds come from, instead of refusing the run later.
+- Guessed force-field parameters (`ATTN, need revision`) and the OpenMM energy
+  check are both checked when the manifest asks for them.
+- Many GUI fixes: the Finish button reports what went wrong instead of doing
+  nothing, re-uploading a structure cannot leave the bundle describing the
+  previous one, a file that parses to no atoms is rejected, Start over clears
+  the answers, Enter fetches a PDB id, and an entry that is mmCIF-only is
+  fetched as `.cif`.
+
+## 0.2.1 - 2026-10-01
+
+### Fixed
+
+- A ligand whose residue name is one the Amber force fields already define is
+  now built under a name they do not. `tleap` resolves residues by name and
+  maps an amino-acid name to its terminal form first, so the BesD free-lysine
+  substrate was built from the `NLYS` protein template and the run died with
+  "Atom .R<NLYS 252>.A<OXT 25> does not have a type" for every one of its
+  ligand-named atoms; binding the ligand unit to `LYS` instead would have
+  pointed every lysine in the protein at the ligand's parameters. The leap
+  input PDB, a copy of the fitted mol2, the `tleap` script and the final
+  validation all use the new name, and every rename is reported.
+- The temporary xTB hydrogen environment no longer hydrogenates a residue
+  twice. OpenMM matches the hydrogens a residue already has through the bonds
+  its residue templates define, so hydrogens mdprep placed from
+  `ligands[].smiles`, named after their parent heavy atom, were invisible to it
+  and it built a second complete set beside them: the BesD free-lysine
+  substrate came out carrying both HB2/HB3 and HB/HBA. Such a residue is now
+  passed through untouched and reported, unless a protonation state was decided
+  for it, in which case OpenMM still rebuilds it in that state.
+- Amber ion atom types were built as `element + charge + "+"`, which produced
+  `Na1+` for every monovalent cation and could not express an anion at all.
+
+- Roe--Brooks stage 2 no longer fails with "Particle coordinate is NaN" on
+  solvated systems. Free ions were positionally restrained because Amber names
+  them `Na+`/`Cl-`, which match no bare element symbol, and coordinates handed
+  between stages were wrapped into the periodic box while the restraint
+  references stayed unwrapped, placing every wrapped restrained particle a full
+  box length from its reference. Stage hand-off and XML restarts now stay in
+  the unwrapped frame; only the per-step PDBs and the trajectory are wrapped.
+- Final-output validation no longer rejects its own PDB with "PDB atom serials
+  must be unique when present" above 99,999 atoms. Serials are decoded for the
+  column-12 overflow `tleap`/`ambpdb` write, for hybrid-36, and for `*****`; a
+  genuine wrap-around is renumbered in file order with a warning, and stays
+  fatal only when `CONECT` records make the connectivity ambiguous. The PDB
+  writer uses the same convention it reads, so structures of that size
+  round-trip unchanged.
+- `mdprep inspect --json` no longer emits unparseable JSON on a narrow
+  terminal, where rich reflowed long strings to the console width.
+
+### Changed
+
+- xTB histidine calculations pin `OMP_NUM_THREADS`, `MKL_NUM_THREADS` and
+  `OPENBLAS_NUM_THREADS` to the new `protonation.histidine.xtb.num_threads`
+  (default `1`), with `OMP_STACKSIZE` from `omp_stacksize` (default `1G`).
+  xTB otherwise opened one thread per hardware thread for every tautomer
+  cluster, spending large amounts of CPU time without reducing wall time.
+- `mdprep inspect` also reports free monatomic metal ions.
+
+## 0.2.0 - 2026-08-17
+
+### Added
+
+- Explicit nonbonded and bonded MCPB.py metal-center workflows, including
+  PySCF QMMESP/RESP charges and PySCF, GFN2-xTB, g-xTB, or MACE-POLAR-1
+  Hessian sources for Seminario parameters.
+- Optional ASH active-site QM/MM refinement with explicit QM components,
+  coordinating residues, 4 A residue and 8 A water active regions, and
+  hydrogen-only relaxation.
+- Manifest-driven Roe--Brooks OpenMM minimization, heating, density
+  equilibration, and production MD with accelerator-first/CPU-fallback
+  platform selection.
+- User-controlled production step and reporting/checkpoint intervals.
+- Manifest-directory-relative input paths and portable executable discovery.
+- GAFF/GAFF2, ff14SB/ff19SB, TIP3P/OPC, AM1-BCC, gas RESP, and embedded
+  QMMESP examples covering the supported preparation combinations.
+
+### Fixed
+
+- Roe--Brooks positional restraints are installed before Context creation and
+  their reference coordinates are converted explicitly from input units to nm.
+- Constraint-compatible heating handoff, evolving NPT box propagation, and
+  production progress totals.
+- MCPB/tLEaP residue-index and renamed-residue coordinate validation.
+
+## 0.1.0 - 2026-06-15
+
+Initial usable release.
+
+### Added
+
+- YAML manifest validation with pydantic.
+- PDB inspection, residue/atom selector parsing, altloc handling, water and heterogen classification, histidine/titratable residue detection, and possible disulfide detection.
+- `mdprep init` starter-manifest generation and safe structure normalization.
+- Manual protonation overrides, input-state preservation, disulfide `CYX` assignment, and input-hydrogen removal.
+- PropKa-based residue-state assignment and xTB/GFN2 or g-xTB HID/HIE histidine tautomer selection.
+- Ligand extraction and AmberTools parameter generation for `am1bcc` and `user_mol2`.
+- PySCF gas-phase RESP/ESP-like ligand charges.
+- PySCF QMMESP-like environment-polarized ligand charges with explicit target-ligand-only fitting.
+- Final `tleap` build, optional solvation, neutralization/salt handling, final Amber files, and validation reports.
+- External tests that skip cleanly when optional executables or libraries are unavailable.
+
+### Unsupported In 0.1.0
+
+- Noncanonical amino acids inside polymer chains.
+- Covalent ligands.
+- Bonded metal-center parameterization and MCPB-like workflows.
+- ORCA and Multiwfn backends.
+- mmCIF input.
+- Automatic loop modeling.
+- Production minimization or MD.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mdprep
-Version: 0.2.0
+Version: 0.3.0
 Summary: Reproducible Amber preparation for proteins, ligands, metal centers, and OpenMM MD.
 Project-URL: Homepage, https://github.com/miqueleg/mdprep
 Project-URL: Issues, https://github.com/miqueleg/mdprep/issues
@@ -19,13 +19,17 @@ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Chemistry
 Requires-Python: >=3.11
 Requires-Dist: numpy>=1.24
-Requires-Dist: pandas>=2
 Requires-Dist: pydantic-settings>=2
 Requires-Dist: pydantic>=2
 Requires-Dist: pyyaml>=6
 Requires-Dist: rich>=13
-Requires-Dist: scipy>=1.10
 Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: openmm>=8.1; extra == 'all'
+Requires-Dist: parmed>=4.2; extra == 'all'
+Requires-Dist: pdbfixer>=1.9; extra == 'all'
+Requires-Dist: pyscf>=2.6; extra == 'all'
+Requires-Dist: rdkit>=2023.3; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: build>=1; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
@@ -34,8 +38,11 @@ Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: twine>=5; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Provides-Extra: ligands
+Requires-Dist: rdkit>=2023.3; extra == 'ligands'
 Provides-Extra: md
 Requires-Dist: openmm>=8.1; extra == 'md'
+Requires-Dist: pdbfixer>=1.9; extra == 'md'
 Provides-Extra: qm
 Requires-Dist: parmed>=4.2; extra == 'qm'
 Requires-Dist: pyscf>=2.6; extra == 'qm'
@@ -45,7 +52,7 @@ Description-Content-Type: text/markdown
 
 # mdprep
 
-`mdprep` 0.2.0 prepares reproducible Amber molecular-dynamics systems from a
+`mdprep` 0.3.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
@@ -105,9 +112,16 @@ Start from a standard protein PDB:
 
 ```bash
 mdprep inspect input.pdb
-mdprep init input.pdb -o system.yaml
+mdprep plan input.pdb                           # what must you decide?
+mdprep init input.pdb --interactive -o system.yaml
 ```
 
+`mdprep plan` lists only the manifest decisions this structure actually
+requires, and `--interactive` asks them and writes a validated manifest. See
+[Guided manifest generation](docs/guided_manifests.md). The non-interactive
+`mdprep init input.pdb -o system.yaml` still writes the commented starter
+manifest.
+
 A minimal protein-only `system.yaml` is:
 
 ```yaml
@@ -177,6 +191,23 @@ 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.
+
 ## Common workflows
 
 Generate a starter manifest using PropKa and ff19SB/OPC:
@@ -215,12 +246,16 @@ specified in steps in the manifest.
 
 | Task | Documentation | Example |
 | --- | --- | --- |
+| Generating a manifest | [Guided manifest generation](docs/guided_manifests.md) | `mdprep plan`, `mdprep init --interactive` |
+| Generating one in a browser | [Web input builder](web/README.md) | `python web/build.py` |
 | Manifest fields | [Manifest reference](docs/manifest_reference.md) | [All examples](examples/README.md) |
 | Protonation and histidines | [Protonation](docs/protonation.md) | `examples/02_manual_catalytic_protonation.yaml` |
 | Ligands, AM1-BCC, RESP, QMMESP | [Ligands](docs/ligands.md) and [QMMESP](docs/qmmesp_pyscf.md) | `examples/03_multi_ligand_am1bcc.yaml`, `04_qmmesp_pyscf_ligand.yaml` |
 | Metal centers and MCPB.py | [Metal centers](docs/metals.md) | `examples/08_nonbonded_zinc_1264.yaml`, `09_bonded_zinc_mcpb_prepare.yaml` |
 | Active-site QM/MM refinement | [QM/MM refinement](docs/qmmm_refinement.md) | `examples/10_qmmm_refinement_ash.yaml` |
 | Roe–Brooks OpenMM MD | [Molecular dynamics](docs/molecular_dynamics.md) | `examples/15_roe_brooks_openmm.yaml` |
+| Running a manifest in Colab | [Colab example notes](examples/README.md) | `examples/mdprep_colab_run.ipynb` |
+| Guided Colab builder (legacy) | [Colab example notes](examples/README.md) | `examples/mdprep_interactive_colab.ipynb` |
 | Complete Fe(III) workflow | [7E07 tutorial](examples/tutorials/7E07_bonded_fe3/README.md) | `examples/tutorials/7E07_bonded_fe3/system.yaml` |
 
 All public example manifests are schema-validated in the test suite.
@@ -243,7 +278,7 @@ charge model, protonation, force field, QM method, or metal model.
 
 ## Current limitations
 
-Version 0.2.0 does not support noncanonical amino acids inside peptide chains,
+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-0.2.0 → mdprep-0.3.0}/README.md

@@ -1,6 +1,6 @@
 # mdprep
 
-`mdprep` 0.2.0 prepares reproducible Amber molecular-dynamics systems from a
+`mdprep` 0.3.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
@@ -60,9 +60,16 @@ Start from a standard protein PDB:
 
 ```bash
 mdprep inspect input.pdb
-mdprep init input.pdb -o system.yaml
+mdprep plan input.pdb                           # what must you decide?
+mdprep init input.pdb --interactive -o system.yaml
 ```
 
+`mdprep plan` lists only the manifest decisions this structure actually
+requires, and `--interactive` asks them and writes a validated manifest. See
+[Guided manifest generation](docs/guided_manifests.md). The non-interactive
+`mdprep init input.pdb -o system.yaml` still writes the commented starter
+manifest.
+
 A minimal protein-only `system.yaml` is:
 
 ```yaml
@@ -132,6 +139,23 @@ 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.
+
 ## Common workflows
 
 Generate a starter manifest using PropKa and ff19SB/OPC:
@@ -170,12 +194,16 @@ specified in steps in the manifest.
 
 | Task | Documentation | Example |
 | --- | --- | --- |
+| Generating a manifest | [Guided manifest generation](docs/guided_manifests.md) | `mdprep plan`, `mdprep init --interactive` |
+| Generating one in a browser | [Web input builder](web/README.md) | `python web/build.py` |
 | Manifest fields | [Manifest reference](docs/manifest_reference.md) | [All examples](examples/README.md) |
 | Protonation and histidines | [Protonation](docs/protonation.md) | `examples/02_manual_catalytic_protonation.yaml` |
 | Ligands, AM1-BCC, RESP, QMMESP | [Ligands](docs/ligands.md) and [QMMESP](docs/qmmesp_pyscf.md) | `examples/03_multi_ligand_am1bcc.yaml`, `04_qmmesp_pyscf_ligand.yaml` |
 | Metal centers and MCPB.py | [Metal centers](docs/metals.md) | `examples/08_nonbonded_zinc_1264.yaml`, `09_bonded_zinc_mcpb_prepare.yaml` |
 | Active-site QM/MM refinement | [QM/MM refinement](docs/qmmm_refinement.md) | `examples/10_qmmm_refinement_ash.yaml` |
 | Roe–Brooks OpenMM MD | [Molecular dynamics](docs/molecular_dynamics.md) | `examples/15_roe_brooks_openmm.yaml` |
+| Running a manifest in Colab | [Colab example notes](examples/README.md) | `examples/mdprep_colab_run.ipynb` |
+| Guided Colab builder (legacy) | [Colab example notes](examples/README.md) | `examples/mdprep_interactive_colab.ipynb` |
 | Complete Fe(III) workflow | [7E07 tutorial](examples/tutorials/7E07_bonded_fe3/README.md) | `examples/tutorials/7E07_bonded_fe3/system.yaml` |
 
 All public example manifests are schema-validated in the test suite.
@@ -198,7 +226,7 @@ charge model, protonation, force field, QM method, or metal model.
 
 ## Current limitations
 
-Version 0.2.0 does not support noncanonical amino acids inside peptide chains,
+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-0.2.0 → mdprep-0.3.0}/docs/README.md

@@ -2,6 +2,8 @@
 
 - [Installation](installation.md)
 - [Quickstart](quickstart.md)
+- [Guided manifest generation](guided_manifests.md)
+- [Web input builder](../web/README.md)
 - [Manifest reference](manifest_reference.md)
 - [Protonation](protonation.md)
 - [Ligands](ligands.md)

mdprep-0.3.0/docs/guided_manifests.md

@@ -0,0 +1,152 @@
+# Guided Manifest Generation
+
+A manifest exposes several hundred settings, but a given structure only needs a
+few dozen of them, and only a handful are decisions a researcher has to make.
+`mdprep plan` works out which, and `mdprep init --interactive` asks them.
+
+On a solvated protein--ligand complex this is the difference between 250+
+available settings and **19 questions, 3 of which need real thought**.
+
+## See what a structure requires
+
+```bash
+mdprep plan input.pdb
+```
+
+This reports what mdprep found (chains, ligands, metal ions, histidines,
+possible disulfides) and then every decision that follows from it, marking the
+ones that cannot be defaulted and which earlier answer each one depends on.
+
+## Answer the questions and write a manifest
+
+```bash
+mdprep init input.pdb --interactive -o system.yaml
+```
+
+Each question shows what was found, why the setting matters, and the available
+values. Press Enter to accept the value shown; there is no value to accept for
+a chemistry-sensitive question, so it is asked until you answer it.
+
+The manifest is validated against the full schema before it is written, so a
+file produced this way always passes `mdprep config-check`. Nothing is
+generated when the wizard is interrupted.
+
+The non-interactive `mdprep init` is unchanged and still produces the commented
+starter manifest.
+
+## What is never defaulted
+
+mdprep does not guess chemistry, and the wizard must not become a way around
+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.
+- **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.
+- **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.
+
+## Metal sites
+
+Choosing `bonded_mcpb` proposes a coordination sphere from interatomic
+distances: atoms of a donor element (N, O, S, P, Se, halide) within 2.6 A of
+the metal. Carbon and hydrogen are excluded, which is what keeps the carbons
+sitting behind a coordinating carboxylate oxygen out of the shell.
+
+The proposal is **not** a decision. You are shown every candidate bond with its
+measured distance and must confirm the set before anything is written; decline,
+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.
+
+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.
+
+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
+enabled automatically for a bonded site, so nothing has to be optimised by hand
+first.
+
+[examples/16_besd_halogenase_gfn2_mcpb.yaml](../examples/16_besd_halogenase_gfn2_mcpb.yaml)
+is the worked reference: BesD, an alpha-ketoglutarate-dependent halogenase with
+Fe(II) in a 2-His triad, chloride in the carboxylate position, and a lysine
+substrate.
+
+## What the wizard will not write for you
+
+A bonded site whose proposed coordination shell you decline is left out of the
+generated file with a note; add it by hand following [metals.md](metals.md).
+
+The RESP charge methods likewise add a `qmmesp` block you must complete. See
+[ligands.md](ligands.md) and [qmmesp_pyscf.md](qmmesp_pyscf.md).
+
+## The web input builder
+
+[`web/`](../web/README.md) is a static page that does all of the above in a
+browser, with a 3D viewer that frames the residues each question is about. It
+runs this same package under Pyodide rather than reimplementing any of it, and
+hands you a manifest plus the Colab cell that runs it.
+
+## Building another front end
+
+The decision plan is the contract. `mdprep plan --json` emits it in full:
+
+```bash
+mdprep plan input.pdb --json
+```
+
+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.
+
+### Driving a 3D viewer
+
+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` 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
+  modelled -- and any later entries are surrounding context.
+- `target_resnames` stands in for a set too large to enumerate usefully, such
+  as every crystallographic water; a viewer selects on the names directly.
+
+So a ligand charge question frames that ligand, a disulfide question frames
+both cysteines of every candidate pair, the unknown-heterogen question frames
+every residue at stake, and a metal question frames the ion together with
+whatever lies within 3 A of it.
+
+That contact search exists only to frame the view. It is **not** a
+determination of coordination: mdprep requires coordinating bonds to be
+declared explicitly, and the evidence string says "within 3.0 A" rather than
+claiming a coordination shell.
+
+A web form, a notebook or another CLI consumes that JSON and never needs to
+re-implement any of the logic. In Python:
+
+```python
+from mdprep.config.decisions import plan_decisions, build_manifest
+
+plan = plan_decisions("input.pdb")
+for decision in plan.applicable(answers_so_far):
+    ...  # render it however you like
+
+manifest = build_manifest(plan, answers)  # raises if a blocking answer is missing
+```
+
+`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.

{mdprep-0.2.0 → mdprep-0.3.0}/docs/installation.md

@@ -1,22 +1,55 @@
 # Installation
 
-Recommended user install:
+One command, then check it:
 
 ```bash
-mamba env create -f environment.yml
+conda env create -f environment.yml   # or: mamba env create -f environment.yml
 conda activate mdprep
-pip install -e .
-mdprep selftest --quick
+mdprep doctor
+```
+
+`environment.yml` installs everything the tutorials need, mdprep included.
+`mdprep doctor` then reports what is present and what is not, and prints the
+command to install anything missing. Given a manifest it reports only what
+that manifest will actually use, so nobody installs a quantum chemistry
+package for a job that never calls it:
+
+```bash
+mdprep doctor examples/16_besd_halogenase_gfn2_mcpb.yaml
 ```
 
+To write and validate manifests without preparing anything, the much smaller
+`environment-minimal.yml` is enough.
+
+## What gets installed, and why
+
+| | Needed for |
+|---|---|
+| AmberTools | `tleap`, `antechamber`, `parmchk2`, `MCPB.py` |
+| PropKa | `protonation.method: propka` and `propka_xtb_his` |
+| xTB | histidine tautomers, GFN2 charges, GFN2 Hessians and ESP |
+| OpenMM | force-field refinement, the MM point charges behind the embedded histidine comparison, validation |
+| PDBFixer | `structure.repair`, temporary hydrogenation |
+| RDKit | placing ligand hydrogens from `ligands[].smiles` |
+| ParmEd | topology and charge validation |
+| PySCF | QMMESP and DFT MCPB RESP fitting |
+
+## ASH
+
+`refinement.backend: ash` is the one thing `environment.yml` cannot provide.
+ASH is a manual checkout from
+[RagnarB83/ash](https://github.com/RagnarB83/ash), put on `PYTHONPATH`; it
+also wants `geometric`, which `environment.yml` does install.
+
+**Do not `pip install ash`.** The `ash` distribution on PyPI is unrelated
+software, and installing it produces an environment that looks correct and is
+not. The default `refinement.backend: openmm` needs none of this, holds every
+heavy atom fixed, and relaxes the hydrogens in seconds.
+
 All distributed manifests use relative file paths or executable names.
 Activate the environment containing the requested backend (or put its
 executable on `PATH`) before running mdprep. Runtime reports record resolved
-executables, but no developer-machine path is embedded in the package.
-
-The environment includes the optional external tooling used by supported
-workflows: AmberTools (including MCPB.py), PropKa, xTB, OpenMM, ParmEd, and
-PySCF. Bonded MCPB completion additionally requires user-run Gaussian or
+executables, but no developer-machine path is embedded in the package. Bonded MCPB completion additionally requires user-run Gaussian or
 GAMESS calculations matching the selected MCPB input format when using
 `workflow: complete`. `workflow: pyscf` instead uses either a user-supplied,
 already optimized MCPB small-model PDB or the geometry inherited from a