PyPI - mlmm-toolkit - Versions diffs - 0.2.4.dev0__tar.gz → 0.2.6__tar.gz - Mend

mlmm-toolkit 0.2.4.dev0tar.gz → 0.2.6tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (554) hide show

{mlmm_toolkit-0.2.4.dev0 → mlmm_toolkit-0.2.6}/.github/workflows/release.yml RENAMED Viewed

@@ -21,6 +21,13 @@ jobs:
           fetch-depth: 0
           fetch-tags: true
+      - name: Set version from tag
+        run: |
+          TAG="${{ github.event.release.tag_name }}"
+          VERSION="${TAG#v}"
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION=$VERSION" >> "$GITHUB_ENV"
+          echo "Building version: $VERSION"
       - name: Setup Python
         uses: actions/setup-python@v5
         with:

{mlmm_toolkit-0.2.4.dev0 → mlmm_toolkit-0.2.6}/.gitignore RENAMED Viewed

@@ -32,6 +32,8 @@ tests/smoke/*_smoke.pdb
 tests/smoke/*_smoke_refactor.pdb
 tests/smoke/test_*.png
+mlmm/_version.py
 # Sphinx documentation
 docs/_build/
 docs/_static/*.css.map

{mlmm_toolkit-0.2.4.dev0 → mlmm_toolkit-0.2.6}/CHANGELOG.md RENAMED Viewed

@@ -4,7 +4,7 @@ All notable changes to **mlmm-toolkit** will be documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/).
-## [0.2.3] — 2026-03-18
+## [0.2.4] — 2026-03-18
 ### Added
 - GitHub Pages deployment and PyPI release workflows.
@@ -66,7 +66,7 @@ This release replaces the previous pysisyphus-wrapper architecture with a unifie
 ### Added — Dependencies & Extras
-- **Optional backends**: `pip install "mlmm-toolkit[orb]"`, `"mlmm-toolkit[mace]"`, `"mlmm-toolkit[aimnet2]"`.
+- **Optional backends**: `pip install "mlmm-toolkit[orb]"`, `"mlmm-toolkit[aimnet]"`. MACE (`mace-torch`) conflicts with `fairchem-core` (UMA) due to incompatible `e3nn` versions; use separate conda environments if both are needed.
 - **Optional DFT**: `pip install "mlmm-toolkit[dft]"` for PySCF + gpu4pyscf-cuda12x + CuPy.
 - **Optional PDBFixer**: `pip install "mlmm-toolkit[pdbfixer]"` for hydrogen addition.
 - **New core dependencies**: `click`, `torch_geometric`, `torch_scatter`, `pyparsing`, `tabulate`.

{mlmm_toolkit-0.2.4.dev0/mlmm_toolkit.egg-info → mlmm_toolkit-0.2.6}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlmm-toolkit
-Version: 0.2.4.dev0
+Version: 0.2.6
 Summary: mlmm - ML/MM toolkit for enzyme reaction analysis
 Author-email: Takuto Ohmura <ohmura.takuto@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -726,10 +726,8 @@ Requires-Dist: pandas
 Requires-Dist: tabulate
 Provides-Extra: orb
 Requires-Dist: orb-models; extra == "orb"
-Provides-Extra: mace
-Requires-Dist: mace-torch; extra == "mace"
-Provides-Extra: aimnet2
-Requires-Dist: aimnet; extra == "aimnet2"
+Provides-Extra: aimnet
+Requires-Dist: aimnet>=0.1.0; extra == "aimnet"
 Provides-Extra: pdbfixer
 Requires-Dist: pdbfixer; extra == "pdbfixer"
 Provides-Extra: dft
@@ -762,13 +760,13 @@ Quantum mechanics/molecular mechanics (QM/MM) methods have long been used to ana
 Each workflow step is also available as an [individual subcommand](#cli-subcommands) ([`opt`](docs/opt.md), [`scan`](docs/scan.md), [`scan2d`](docs/scan2d.md), [`path-search`](docs/path_search.md), [`tsopt`](docs/tsopt.md), [`freq`](docs/freq.md), [`irc`](docs/irc.md), [`dft`](docs/dft.md), [`energy-diagram`](docs/energy_diagram.md), [etc.](#cli-subcommands)), allowing fine-grained control over each stage. A **single command** can generate a first-pass enzymatic reaction path with ML/MM accuracy:
 ```bash
-mlmm all -i R.pdb P.pdb -c PRE -l "PRE:-2"
+mlmm all -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3'
 ```
-The full workflow — **MEP search → TS optimization → IRC → thermochemistry → single-point DFT** — can be run in one command:
+The full workflow — **ML/MM model setup → MEP search → TS optimization → IRC → thermochemistry → single-point DFT** — can be run in one command:
 ```bash
-mlmm all -i R.pdb P.pdb -c PRE -l "PRE:-2" --tsopt --thermo --dft
+mlmm all -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' --tsopt --thermo --dft
 ```
 Given **(i) two or more PDB files** (R → ... → P), **or (ii) one PDB with `--scan-lists`**, **or (iii) one TS candidate with `--tsopt`**, `mlmm-toolkit` automatically:
@@ -857,7 +855,7 @@ If you are on an HPC cluster that uses *environment modules*, load CUDA **before
 module load cuda/12.6
 ```
-> `fairchem-core` is a core dependency. `aimnet2` and other ML backends (`orb-models`, `mace-torch`) are optional extras (e.g. `pip install "mlmm-toolkit[aimnet2]"`).
+> `fairchem-core` (UMA) is a core dependency. ORB and AIMNet2 are optional extras (e.g. `pip install "mlmm-toolkit[aimnet]"`). MACE requires uninstalling `fairchem-core` first due to an `e3nn` version conflict.
 ### DFT single-point (`mlmm dft`)
@@ -882,6 +880,7 @@ module unload amber
 ```bash
 conda install -c conda-forge cyipopt -y
+pip install pydmf
 ```
 ### Authenticate for UMA (Hugging Face)
@@ -898,15 +897,16 @@ huggingface-cli login
 |-----------|------------|---------------|
 | **UMA** (default) | <https://github.com/facebookresearch/fairchem> | *(included)* |
 | **ORB** | <https://github.com/orbital-materials/orb-models> | `pip install "mlmm-toolkit[orb]"` |
-| **MACE** | <https://github.com/ACEsuit/mace> | see note below |
-| **AIMNet2** | <https://github.com/isayevlab/aimnetcentral> | `pip install "mlmm-toolkit[aimnet2]"` |
+| **MACE** | <https://github.com/ACEsuit/mace> | See below |
+| **AIMNet2** | <https://github.com/isayevlab/aimnetcentral> | `pip install "mlmm-toolkit[aimnet]"` |
-> **Note:** MACE and UMA cannot coexist due to conflicting `e3nn` versions (`fairchem-core` requires `e3nn>=0.5`, `mace-torch` requires `e3nn==0.4.4`). To use MACE, uninstall `fairchem-core` first:
+> **MACE installation:** MACE requires `e3nn==0.4.4`, which conflicts with `fairchem-core` (UMA).
+> To use MACE, first uninstall UMA's dependency, then install MACE:
 > ```bash
 > pip uninstall fairchem-core
 > pip install mace-torch
 > ```
-> This means UMA will no longer be available in that environment. We recommend using a **separate conda environment** for MACE.
+> UMA and MACE cannot coexist in the same environment. Use separate conda environments if you need both.
 ---
@@ -924,7 +924,7 @@ huggingface-cli login
    Use [`mlmm extract`](docs/extract.md) or any molecular viewer to select residues around the substrate:
    ```bash
-   mlmm extract -i complex.pdb -c PRE -r 6.0 -l "PRE:-2" -o ml_region.pdb
+   mlmm extract -i complex.pdb -c 'SAM,GPP' -r 6.0 -l 'SAM:1,GPP:-3' -o ml_region.pdb
    ```
    **Important:** atom order, residue names, and residue numbers must match between the *full* PDB and the *ML-region* PDB. (In PyMOL, tick **"Original atom order"** when exporting.)
@@ -935,14 +935,14 @@ huggingface-cli login
 ### Full workflow (multi-structure)
 ```bash
-mlmm all -i R.pdb P.pdb -c PRE -l "PRE:-2" \
+mlmm all -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' \
     --tsopt --thermo --dft
 ```
 ### Scan mode (single structure)
 ```bash
-mlmm all -i R.pdb -c PRE -l "PRE:-2" \
-    --scan-lists "[('PRE 353 O1\'','PRE 353 C3',1.2)]"
+mlmm all -i R.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' \
+    --scan-lists "[('SAM 359 CS1','GPP 360 C8',1.3)]"
 ```
 ### TS optimization only
@@ -954,10 +954,10 @@ mlmm tsopt -i TS_candidate_layered.pdb --parm complex.parm7 \
 ### Step-by-step workflow
 ```bash
 # 1. Generate MM parameters
-mlmm mm-parm -i complex.pdb -l "PRE:-2"
+mlmm mm-parm -i complex.pdb -l 'SAM:1,GPP:-3'
 # 2. Extract active-site pocket
-mlmm extract -i complex.pdb -c '353' -l "PRE:-2" -r 6.0
+mlmm extract -i complex.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' -r 6.0
 # 3. Assign 3-layer ONIOM regions
 mlmm define-layer -i complex.pdb --model-pdb pocket.pdb --radius-freeze 10.0
@@ -1147,8 +1147,18 @@ mlmm <subcommand> --help-advanced
 ---
 ## Citation
-If you find this work helpful for your research, please cite:
-[1] Ohmura, T., Inoue, S., Terada, T. (2025). ML/MM toolkit – Towards Accelerated Mechanistic Investigation of Enzymatic Reactions. ChemRxiv. [doi:10.26434/chemrxiv-2025-jft1k](https://doi.org/10.26434/chemrxiv-2025-jft1k)
+If you find this work helpful for your research, please cite:
+```bibtex
+@article{ohmura2025mlmm,
+  author       = {Ohmura, Takuto and Inoue, Sei and Terada, Tohru},
+  title        = {ML/MM Toolkit -- Towards Accelerated Mechanistic Investigation of Enzymatic Reactions},
+  year         = {2025},
+  journal      = {ChemRxiv},
+  doi          = {10.26434/chemrxiv-2025-jft1k},
+  url          = {https://doi.org/10.26434/chemrxiv-2025-jft1k}
+}
+```
 ---

{mlmm_toolkit-0.2.4.dev0 → mlmm_toolkit-0.2.6}/README.md RENAMED Viewed

@@ -11,13 +11,13 @@ Quantum mechanics/molecular mechanics (QM/MM) methods have long been used to ana
 Each workflow step is also available as an [individual subcommand](#cli-subcommands) ([`opt`](docs/opt.md), [`scan`](docs/scan.md), [`scan2d`](docs/scan2d.md), [`path-search`](docs/path_search.md), [`tsopt`](docs/tsopt.md), [`freq`](docs/freq.md), [`irc`](docs/irc.md), [`dft`](docs/dft.md), [`energy-diagram`](docs/energy_diagram.md), [etc.](#cli-subcommands)), allowing fine-grained control over each stage. A **single command** can generate a first-pass enzymatic reaction path with ML/MM accuracy:
 ```bash
-mlmm all -i R.pdb P.pdb -c PRE -l "PRE:-2"
+mlmm all -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3'
 ```
-The full workflow — **MEP search → TS optimization → IRC → thermochemistry → single-point DFT** — can be run in one command:
+The full workflow — **ML/MM model setup → MEP search → TS optimization → IRC → thermochemistry → single-point DFT** — can be run in one command:
 ```bash
-mlmm all -i R.pdb P.pdb -c PRE -l "PRE:-2" --tsopt --thermo --dft
+mlmm all -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' --tsopt --thermo --dft
 ```
 Given **(i) two or more PDB files** (R → ... → P), **or (ii) one PDB with `--scan-lists`**, **or (iii) one TS candidate with `--tsopt`**, `mlmm-toolkit` automatically:
@@ -106,7 +106,7 @@ If you are on an HPC cluster that uses *environment modules*, load CUDA **before
 module load cuda/12.6
 ```
-> `fairchem-core` is a core dependency. `aimnet2` and other ML backends (`orb-models`, `mace-torch`) are optional extras (e.g. `pip install "mlmm-toolkit[aimnet2]"`).
+> `fairchem-core` (UMA) is a core dependency. ORB and AIMNet2 are optional extras (e.g. `pip install "mlmm-toolkit[aimnet]"`). MACE requires uninstalling `fairchem-core` first due to an `e3nn` version conflict.
 ### DFT single-point (`mlmm dft`)
@@ -131,6 +131,7 @@ module unload amber
 ```bash
 conda install -c conda-forge cyipopt -y
+pip install pydmf
 ```
 ### Authenticate for UMA (Hugging Face)
@@ -147,15 +148,16 @@ huggingface-cli login
 |-----------|------------|---------------|
 | **UMA** (default) | <https://github.com/facebookresearch/fairchem> | *(included)* |
 | **ORB** | <https://github.com/orbital-materials/orb-models> | `pip install "mlmm-toolkit[orb]"` |
-| **MACE** | <https://github.com/ACEsuit/mace> | see note below |
-| **AIMNet2** | <https://github.com/isayevlab/aimnetcentral> | `pip install "mlmm-toolkit[aimnet2]"` |
+| **MACE** | <https://github.com/ACEsuit/mace> | See below |
+| **AIMNet2** | <https://github.com/isayevlab/aimnetcentral> | `pip install "mlmm-toolkit[aimnet]"` |
-> **Note:** MACE and UMA cannot coexist due to conflicting `e3nn` versions (`fairchem-core` requires `e3nn>=0.5`, `mace-torch` requires `e3nn==0.4.4`). To use MACE, uninstall `fairchem-core` first:
+> **MACE installation:** MACE requires `e3nn==0.4.4`, which conflicts with `fairchem-core` (UMA).
+> To use MACE, first uninstall UMA's dependency, then install MACE:
 > ```bash
 > pip uninstall fairchem-core
 > pip install mace-torch
 > ```
-> This means UMA will no longer be available in that environment. We recommend using a **separate conda environment** for MACE.
+> UMA and MACE cannot coexist in the same environment. Use separate conda environments if you need both.
 ---
@@ -173,7 +175,7 @@ huggingface-cli login
    Use [`mlmm extract`](docs/extract.md) or any molecular viewer to select residues around the substrate:
    ```bash
-   mlmm extract -i complex.pdb -c PRE -r 6.0 -l "PRE:-2" -o ml_region.pdb
+   mlmm extract -i complex.pdb -c 'SAM,GPP' -r 6.0 -l 'SAM:1,GPP:-3' -o ml_region.pdb
    ```
    **Important:** atom order, residue names, and residue numbers must match between the *full* PDB and the *ML-region* PDB. (In PyMOL, tick **"Original atom order"** when exporting.)
@@ -184,14 +186,14 @@ huggingface-cli login
 ### Full workflow (multi-structure)
 ```bash
-mlmm all -i R.pdb P.pdb -c PRE -l "PRE:-2" \
+mlmm all -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' \
     --tsopt --thermo --dft
 ```
 ### Scan mode (single structure)
 ```bash
-mlmm all -i R.pdb -c PRE -l "PRE:-2" \
-    --scan-lists "[('PRE 353 O1\'','PRE 353 C3',1.2)]"
+mlmm all -i R.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' \
+    --scan-lists "[('SAM 359 CS1','GPP 360 C8',1.3)]"
 ```
 ### TS optimization only
@@ -203,10 +205,10 @@ mlmm tsopt -i TS_candidate_layered.pdb --parm complex.parm7 \
 ### Step-by-step workflow
 ```bash
 # 1. Generate MM parameters
-mlmm mm-parm -i complex.pdb -l "PRE:-2"
+mlmm mm-parm -i complex.pdb -l 'SAM:1,GPP:-3'
 # 2. Extract active-site pocket
-mlmm extract -i complex.pdb -c '353' -l "PRE:-2" -r 6.0
+mlmm extract -i complex.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' -r 6.0
 # 3. Assign 3-layer ONIOM regions
 mlmm define-layer -i complex.pdb --model-pdb pocket.pdb --radius-freeze 10.0
@@ -396,8 +398,18 @@ mlmm <subcommand> --help-advanced
 ---
 ## Citation
-If you find this work helpful for your research, please cite:
-[1] Ohmura, T., Inoue, S., Terada, T. (2025). ML/MM toolkit – Towards Accelerated Mechanistic Investigation of Enzymatic Reactions. ChemRxiv. [doi:10.26434/chemrxiv-2025-jft1k](https://doi.org/10.26434/chemrxiv-2025-jft1k)
+If you find this work helpful for your research, please cite:
+```bibtex
+@article{ohmura2025mlmm,
+  author       = {Ohmura, Takuto and Inoue, Sei and Terada, Tohru},
+  title        = {ML/MM Toolkit -- Towards Accelerated Mechanistic Investigation of Enzymatic Reactions},
+  year         = {2025},
+  journal      = {ChemRxiv},
+  doi          = {10.26434/chemrxiv-2025-jft1k},
+  url          = {https://doi.org/10.26434/chemrxiv-2025-jft1k}
+}
+```
 ---

mlmm_toolkit-0.2.6/docs/_static/theme_toggle.js ADDED Viewed

@@ -0,0 +1,34 @@
+// Override Furo's 3-state theme toggle (light/dark/auto) with 2-state (light ↔ dark).
+(function () {
+  "use strict";
+  function resolveAuto() {
+    return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  }
+  function applyTheme(theme) {
+    document.body.dataset.theme = theme;
+    localStorage.setItem("theme", theme);
+  }
+  function toggle() {
+    var current = document.body.dataset.theme;
+    if (current !== "light" && current !== "dark") current = resolveAuto();
+    applyTheme(current === "dark" ? "light" : "dark");
+  }
+  // Intercept all theme-toggle buttons (header + sidebar)
+  document.addEventListener("click", function (e) {
+    var btn = e.target.closest("button.theme-toggle");
+    if (!btn) return;
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    toggle();
+  }, true);
+  // On load: resolve "auto" to explicit light/dark
+  var stored = localStorage.getItem("theme");
+  if (!stored || stored === "auto") {
+    applyTheme(resolveAuto());
+  }
+})();

mlmm_toolkit-0.2.4.dev0/docs/add_elem_info.md → mlmm_toolkit-0.2.6/docs/add-elem-info.md RENAMED Viewed

@@ -59,8 +59,8 @@ mlmm add-elem-info -i 1abc.pdb --overwrite
 ## See Also
-- [Common Error Recipes](recipes_common_errors.md) -- Symptom-first failure routing
+- [Common Error Recipes](recipes-common-errors.md) -- Symptom-first failure routing
 - [Troubleshooting](troubleshooting.md) -- Detailed troubleshooting guide
-- [mm_parm](mm_parm.md) -- Build AMBER topology (requires correct element columns)
+- [mm_parm](mm-parm.md) -- Build AMBER topology (requires correct element columns)
 - [extract](extract.md) -- Extract active-site pocket from protein-ligand complex

{mlmm_toolkit-0.2.4.dev0 → mlmm_toolkit-0.2.6}/docs/all.md RENAMED Viewed

@@ -2,7 +2,7 @@
 ## Overview
-> **Summary:** End-to-end enzymatic reaction workflow -- active-site extraction, ML/MM layer assignment, MM topology preparation, optional staged scan, MEP search (GSM) on full-system layered PDBs, with optional TS optimization, pseudo-IRC, thermochemistry, DFT, and DFT//MLIP diagrams.
+> **Summary:** End-to-end enzymatic reaction workflow -- active-site extraction, ML/MM layer assignment, MM topology preparation, optional staged scan, MEP search (GSM) on full-system layered PDBs, with optional TS optimization, EulerPC IRC, thermochemistry, DFT, and DFT//MLIP diagrams.
 `mlmm all` runs a one-shot pipeline that operates on full-system layered PDBs with ML/MM. It supports three modes:
@@ -10,7 +10,7 @@
 - **Single-structure + staged scan** -- Provide one PDB plus `--scan-lists`. The scan generates intermediate/product candidates that become MEP endpoints.
   - One `--scan-lists` literal runs a single scan stage.
   - Multiple stages are passed as multiple values after a single `--scan-lists` flag.
-- **TSOPT-only** -- Provide a single PDB, omit `--scan-lists`, and set `--tsopt`. The tool runs TS optimization on the layered full-system PDB, performs pseudo-IRC, minimizes both ends, and builds energy diagrams.
+- **TSOPT-only** -- Provide a single PDB, omit `--scan-lists`, and set `--tsopt`. The tool runs TS optimization on the layered full-system PDB, performs EulerPC IRC, minimizes both ends, and builds energy diagrams.
 ```{important}
 `--tsopt` produces **TS candidates**. `all` automatically runs IRC and freq for validation, but always inspect the results (imaginary mode + endpoint connectivity) before mechanistic interpretation.
@@ -25,8 +25,8 @@ mlmm all -i R.pdb P.pdb -c "SAM,GPP" -l "SAM:1,GPP:-3" --out-dir ./result_all
 ## Output checklist
 - `result_all/summary.log`
-- `result_all/summary.yaml`
-- `result_all/path_search/mep.pdb` (or `result_all/path_search/seg_*/`)
+- `result_all/summary.json`
+- `result_all/path_opt/mep.pdb` (or `result_all/path_opt/seg_*/`; `path_search/` when `--refine-path` is used)
 ## Common examples
@@ -83,7 +83,7 @@ mlmm all -i A.pdb B.pdb C.pdb -c "308,309" -l "-1" \
 mlmm all -i A.pdb -c "308,309" --scan-lists "[(10,55,2.20),(23,34,1.80)]" \
  --multiplicity 1 --out-dir result_scan_all --tsopt --thermo --dft
-# Single-structure TSOPT-only mode (no path_search)
+# Single-structure TSOPT-only mode (no MEP search)
 mlmm all -i A.pdb -c "GPP,MMT" -l "GPP:-3,MMT:-1" \
  --tsopt --thermo --dft --out-dir result_tsopt_only
 ```
@@ -94,7 +94,7 @@ mlmm all -i A.pdb -c "GPP,MMT" -l "GPP:-3,MMT:-1" \
    - Define the substrate (`-c/--center`, by PDB, residue IDs, or residue names).
    - Optionally provide `--ligand-charge` as a total number (distributed) or a mapping (e.g., `GPP:-3,MMT:-1`).
    - The extractor writes per-input pocket PDBs under `<out-dir>/pockets/`. The first pocket is copied as `<out-dir>/ml_region.pdb` to define the ML region for all subsequent ML/MM calculations.
-   - The extractor's **first-model total pocket charge** is used as the total charge in later steps, cast to the nearest integer with a console note if rounding occurs.
+   - The extractor's **first-model net ML-region charge** is used as the net ML-region charge in later steps, cast to the nearest integer with a console note if rounding occurs.
    - Additional extractor toggles: `--radius`, `--radius-het2het`, `--include-H2O/--no-include-H2O`, `--exclude-backbone/--no-exclude-backbone`, `--add-linkH/--no-add-linkH`, `--selected-resn`, `--verbose/--no-verbose`.
    - If `-c/--center` is omitted, extraction is skipped and full input structures are used directly.
@@ -110,12 +110,12 @@ mlmm all -i A.pdb -c "GPP,MMT" -l "GPP:-3,MMT:-1" \
 4. **MEP search on full-system layered PDBs**
    - All MEP calculations run on full-system layered PDBs (with `--parm` and `--detect-layer`), not on pockets.
-   - **`--refine-path` (default):** Runs recursive `path_search` with kink-detection and refinement.
-   - **`--no-refine-path`:** Runs single-pass `path-opt` GSM per adjacent pair, then concatenates trajectories, extracts HEI per segment, detects bond changes, and writes `summary.yaml` — enabling Stage 4 post-processing (TSOPT, thermo, DFT) on both modes.
+   - **`path-opt` (default):** Runs `path-opt` GSM per adjacent pair, then concatenates trajectories, extracts HEI per segment, detects bond changes, and writes `summary.json` — enabling Stage 4 post-processing (TSOPT, thermo, DFT).
+   - **`--refine-path`:** Runs recursive `path_search` with automatic refinement, detecting multistep reactions and building a detailed MEP for each elementary step.  Complex multistep mechanisms may require manual trial-and-error. Both modes support Stage 4 post-processing.
    - For multi-input runs, the original full PDBs are supplied as merge references automatically. In the scan-derived series (single-structure case), the single original full PDB is reused (repeated) as the reference template.
 5. **Summary and optional post-processing**
-   - Per-segment trajectories, full MEP trajectory, and a `summary.yaml` are written under `<out-dir>/path_search/`.
+   - Per-segment trajectories, full MEP trajectory, and a `summary.json` are written under `<out-dir>/path_opt/` (or `<out-dir>/path_search/` when `--refine-path` is used).
    - `--tsopt`: run TS optimization on each HEI, follow with EulerPC IRC, and emit segment energy diagrams.
    - `--thermo`: Compute ML/MM thermochemistry on (R, TS, P) and add a Gibbs diagram.
    - `--dft`: Do DFT single-point on (R, TS, P) and add a DFT diagram. With `--thermo`, also generate a DFT//MLIP Gibbs diagram.
@@ -123,7 +123,7 @@ mlmm all -i A.pdb -c "GPP,MMT" -l "GPP:-3,MMT:-1" \
    - When you have ample VRAM available, setting `--hessian-calc-mode` to `Analytical` is strongly recommended.
 6. **TSOPT-only mode** (single input, `--tsopt`, no `--scan-lists`)
-   - Skips steps (4)-(5) and runs `tsopt` on the layered full-system PDB, does a pseudo-IRC and minimizes both ends, builds ML/MM energy diagrams for R-TS-P, and optionally adds Gibbs, DFT, and DFT//MLIP diagrams.
+   - Skips steps (4)-(5) and runs `tsopt` on the layered full-system PDB, performs EulerPC IRC and minimizes both ends, builds ML/MM energy diagrams for R-TS-P, and optionally adds Gibbs, DFT, and DFT//MLIP diagrams.
    - In this mode only, the IRC endpoint with **higher energy** is adopted as the reactant (R).
 ### Charge and spin precedence
@@ -157,10 +157,10 @@ mlmm all -i A.pdb -c "GPP,MMT" -l "GPP:-3,MMT:-1" \
 | `-i, --input PATH...` | Two or more full PDBs in reaction order (single input allowed with `--scan-lists` or `--tsopt`). | Required |
 | `-c, --center TEXT` | Substrate specification (PDB path, residue IDs, or residue names). Omit to skip extraction. | _None_ |
 | `-l, --ligand-charge TEXT` | Total charge or residue-specific mapping (e.g., `GPP:-3,MMT:-1`). | _None_ |
-| `-q, --charge INT` | Force total system charge (highest priority override). | _None_ |
+| `-q, --charge INT` | Force net system charge (highest priority override). | _None_ |
 | `-o, --out-dir PATH` | Top-level output directory. | `./result_all/` |
 | `--parm FILE` | AMBER parm7 topology file for the full (real) system. When omitted, `all` auto-generates one via `mm_parm`. | _None_ |
-| `--model-pdb FILE` | Pre-built ML-region PDB. When provided, pocket extraction is skipped and this file defines the ML region directly. | _None_ |
+| `--model-pdb FILE` | Pre-built ML-region PDB. When provided, ML-region determination is skipped and this file defines the ML region directly. | _None_ |
 | `--ref-pdb FILE` | Reference PDB for XYZ input. Required when the input is XYZ so that PDB metadata (residues, chains, B-factors) can be recovered. | _None_ |
 | `--convert-files/--no-convert-files` | Global toggle for XYZ/TRJ to PDB companions when templates are available. | `True` |
 | `--dump/--no-dump` | Save optimizer dumps. Always forwarded to `path-search`/`path-opt`; forwarded to `scan`/`tsopt` only when explicitly set here. `freq` defaults to dump=True unless you pass `--no-dump`. | `False` |
@@ -175,9 +175,10 @@ mlmm all -i A.pdb -c "GPP,MMT" -l "GPP:-3,MMT:-1" \
 | `-r, --radius FLOAT` | Pocket inclusion cutoff (Å). | `2.6` |
 | `--radius-het2het FLOAT` | Independent hetero-hetero cutoff (Å). | `0.0` |
 | `--include-H2O/--no-include-H2O` | Include water molecules (HOH/WAT/TIP3/SOL). | `True` |
-| `--exclude-backbone/--no-exclude-backbone` | Remove backbone atoms on non-substrate amino acids. | `True` |
+| `--exclude-backbone/--no-exclude-backbone` | Remove backbone atoms on non-substrate amino acids. | `False` |
 | `--add-linkH/--no-add-linkH` | Add link hydrogens for severed bonds. | `False` |
 | `--selected-resn TEXT` | Residues to force include. | `""` |
+| `--modified-residue TEXT` | Comma-separated residue names (with optional charge) to treat as amino acids for backbone truncation and charge assignment. Examples: `HD1,HD2,HD3` or `HD1:0,SEP:-2`. | `""` |
 | `--verbose/--no-verbose` | Enable INFO-level extractor logging. | `True` |
 ### MM Preparation Options
@@ -201,10 +202,11 @@ mlmm all -i A.pdb -c "GPP,MMT" -l "GPP:-3,MMT:-1" \
 | `--thresh TEXT` | Convergence preset (`gau_loose`, `gau`, `gau_tight`, `gau_vtight`, `baker`, `never`). | `gau` |
 | `--thresh-post TEXT` | Convergence preset for post-IRC endpoint optimizations. | `baker` |
 | `--preopt/--no-preopt` | Pre-optimize endpoints before segmentation. | `True` |
-| `--refine-path/--no-refine-path` | If True, run recursive `path-search`; if False, chain `path-opt` segments (single-pass GSM per pair, with trajectory concatenation, HEI extraction, bond-change detection, and summary.yaml). Both modes support Stage 4 (TSOPT/thermo/DFT). | `True` |
+| `--refine-path/--no-refine-path` | If True, run recursive `path-search`; if False, chain `path-opt` segments (single-pass GSM per pair, with trajectory concatenation, HEI extraction, bond-change detection, and summary.json). Both modes support Stage 4 (TSOPT/thermo/DFT). | `False` |
 | `-b, --backend CHOICE` | MLIP backend for the ML region: `uma` (default), `orb`, `mace`, `aimnet2`. | `uma` |
 | `--embedcharge/--no-embedcharge` | Enable xTB point-charge embedding correction for MM-to-ML environmental effects. | `False` |
 | `--embedcharge-cutoff FLOAT` | Cutoff radius (Å) for embed-charge MM atoms. | `12.0` |
+| `--cmap/--no-cmap` | Enable CMAP (backbone cross-map dihedral correction) in model parm7. Default: disabled (consistent with Gaussian ONIOM). | `--no-cmap` |
 | `--hessian-calc-mode CHOICE` | ML/MM Hessian mode (`Analytical` or `FiniteDifference`). | `FiniteDifference` |
 | `--detect-layer/--no-detect-layer` | Detect ML/MM layers from input PDB B-factors (B=0/10/20) in downstream tools. If disabled, downstream tools require `--model-pdb` or `--model-indices`. | `True` |
@@ -227,7 +229,7 @@ TSOPT optimizer selection order: `--opt-mode-post` (if set) -> `--opt-mode` (onl
 | Option | Description | Default |
 | --- | --- | --- |
-| `--tsopt/--no-tsopt` | Run TS optimization + pseudo-IRC per reactive segment. | `False` |
+| `--tsopt/--no-tsopt` | Run TS optimization + EulerPC IRC per reactive segment. | `False` |
 | `--thermo/--no-thermo` | Run vibrational analysis (`freq`) on R/TS/P. | `False` |
 | `--dft/--no-dft` | Run single-point DFT on R/TS/P. | `False` |
 | `--flatten/--no-flatten` | Enable extra-imaginary-mode flattening in `tsopt`. | `False` |
@@ -260,7 +262,7 @@ TSOPT optimizer selection order: `--opt-mode-post` (if set) -> `--opt-mode` (onl
 ```text
 <out-dir>/
- ml_region.pdb                         # ML-region definition (copy of the first pocket)
+ ml_region.pdb                         # ML-region definition (copy of the first determined ML region)
  pockets/
   pocket_<input1_basename>.pdb
   pocket_<input2_basename>.pdb
@@ -273,7 +275,7 @@ TSOPT optimizer selection order: `--opt-mode-post` (if set) -> `--opt-mode` (onl
   stage_01/result.pdb
   stage_02/result.pdb
   ...
- summary.yaml                          # mirrored top-level summary (when path_search runs)
+ summary.json                          # mirrored top-level summary (when path_search runs)
  summary.log
  mep_plot.png
  energy_diagram_MEP.png
@@ -282,10 +284,10 @@ TSOPT optimizer selection order: `--opt-mode-post` (if set) -> `--opt-mode` (onl
  energy_diagram_DFT_all.png
  energy_diagram_G_DFT_plus_UMA_all.png
  irc_plot_all.png
- path_search/                          # present when path_search is executed
+ path_opt/                             # default; path_search/ when --refine-path is used
   mep_trj.xyz
   mep.pdb
-  summary.yaml
+  summary.json
   summary.log
   mep_plot.png
   energy_diagram_MEP.png
@@ -321,8 +323,8 @@ The log is organized into numbered sections:
 - **[4] Energy diagrams (overview)** -- diagram tables for MEP/MLIP/Gibbs/DFT series plus an optional cross-method summary table.
 - **[5] Output directory structure** -- a compact tree of generated files with inline annotations.
-### Reading `summary.yaml`
-The YAML is a compact, machine-readable summary. Common top-level keys include:
+### Reading `summary.json`
+The JSON is a compact, machine-readable summary. Common top-level keys include:
 - `out_dir`, `n_images`, `n_segments` -- run metadata and total counts.
 - `segments` -- list of per-segment entries with `index`, `tag`, `kind`, `barrier_kcal`, `delta_kcal`, and `bond_changes`.
 - `energy_diagrams` (optional) -- diagram payloads with `labels`, `energies_kcal`, `energies_au`, `ylabel`, and `image` paths.
@@ -339,7 +341,7 @@ The resulting effective YAML is forwarded to downstream subcommands. Each tool r
 | Subcommand | YAML Sections |
 |------------|---------------|
-| [`path-search`](path_search.md) | `geom`, `calc`/`mlmm`, `gs`, `opt`, `lbfgs`, `bond`, `search` |
+| [`path-search`](path-search.md) | `geom`, `calc`/`mlmm`, `gs`, `opt`, `lbfgs`, `bond`, `search` |
 | [`scan`](scan.md) | `geom`, `calc`/`mlmm`, `opt`, `lbfgs` |
 | [`tsopt`](tsopt.md) | `geom`, `calc`/`mlmm`, `opt`, `hessian_dimer`, `rsirfo` |
 | [`freq`](freq.md) | `geom`, `calc`/`mlmm`, `freq`, `thermo` |
@@ -358,7 +360,7 @@ mlmm:
  backend: uma                    # MLIP backend: uma | orb | mace | aimnet2
  embedcharge: false              # xTB point-charge embedding correction
  uma_model: uma-s-1p1            # uma-s-1p1 | uma-m-1p1
- ml_hessian_mode: Analytical     # recommended when VRAM permits
+ hessian_calc_mode: Analytical     # recommended when VRAM permits
 gs:
  max_nodes: 12
  climb: true
@@ -366,18 +368,18 @@ dft:
  grid_level: 6
 ```
-For a complete reference of all YAML options, see **[YAML Configuration Reference](yaml_reference.md)**.
+For a complete reference of all YAML options, see **[YAML Configuration Reference](yaml-reference.md)**.
 ## See Also
-- [extract](extract.md) -- Standalone pocket extraction (called internally by `all`)
-- [mm_parm](mm_parm.md) -- Build AMBER topology (called internally by `all`)
-- [path-search](path_search.md) -- Standalone recursive MEP search
+- [extract](extract.md) -- Standalone ML-region determination (called internally by `all`)
+- [mm_parm](mm-parm.md) -- Build AMBER topology (called internally by `all`)
+- [path-search](path-search.md) -- Standalone recursive MEP search
 - [tsopt](tsopt.md) -- Standalone TS optimization
 - [freq](freq.md) -- Vibrational analysis and thermochemistry
 - [dft](dft.md) -- Single-point DFT calculations
 - [trj2fig](trj2fig.md) -- Plot energy profiles from trajectories
-- [Common Error Recipes](recipes_common_errors.md) -- Symptom-first failure routing
+- [Common Error Recipes](recipes-common-errors.md) -- Symptom-first failure routing
 - [Troubleshooting](troubleshooting.md) -- Common errors and fixes
-- [YAML Reference](yaml_reference.md) -- Complete YAML configuration options
+- [YAML Reference](yaml-reference.md) -- Complete YAML configuration options
 - [Glossary](glossary.md) -- Definitions of MEP, TS, IRC, GSM

mlmm_toolkit-0.2.6/docs/bond-summary.md ADDED Viewed

@@ -0,0 +1,68 @@
+# bond-summary
+Detect and report covalent bond changes between consecutive molecular structures.
+## Synopsis
+```bash
+mlmm bond-summary -i R.xyz -i P.xyz
+mlmm bond-summary -i R.xyz -i TS.xyz -i P.xyz
+mlmm bond-summary -i R.pdb -i IM1.pdb -i IM2.pdb -i P.pdb
+```
+## Description
+`bond-summary` compares consecutive pairs of input structures and reports
+bonds that are formed or broken. For *N* input files it produces *N − 1*
+comparison blocks (A→B, B→C, …).
+Bond perception uses element-specific covalent radii with configurable
+tolerances. Distances are reported in Ångström.
+Supported formats: **XYZ**, **PDB**, **GJF** (auto-detected by extension).
+## Options
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-i, --input FILE` | Input structure file (repeat for each file, ≥ 2 required) | — |
+| `--device TEXT` | Compute device (`cpu`, `cuda`) | `cpu` |
+| `--bond-factor FLOAT` | Scaling factor for covalent radii sum | `1.20` |
+| `--one-based / --zero-based` | Atom index convention in output | `--one-based` |
+## Examples
+### Two-structure comparison
+```bash
+mlmm bond-summary -i 1.R.xyz -i 3.P.xyz
+```
+Output:
+```
+============================================================
+  1.R.xyz  →  3.P.xyz
+============================================================
+Bond formed (2):
+  - O14-H106 : 1.502 Å --> 1.011 Å
+  - P95-O107 : 3.477 Å --> 1.523 Å
+Bond broken (2):
+  - P95-O97 : 1.585 Å --> 3.270 Å
+  - H106-O107 : 1.034 Å --> 1.673 Å
+```
+### Multi-structure (reaction pathway)
+```bash
+mlmm bond-summary -i 1.R.xyz -i 3.IM1.xyz -i 5.IM2.xyz -i 7.P.xyz
+```
+Produces three comparison blocks: R→IM1, IM1→IM2, IM2→P.
+## Notes
+- All input structures must have **identical atom counts and element ordering**.
+- Bond detection uses the same algorithm as the internal `bond_changes` module
+  used by the `all` workflow for IRC endpoint validation.
+- To adjust sensitivity to borderline bonds (e.g., metal coordination at 2.0–2.4 Å),
+  increase `--bond-factor` (e.g., `1.30`).

mlmm-toolkit 0.2.4.dev0__tar.gz → 0.2.6__tar.gz

mlmm-toolkit 0.2.4.dev0tar.gz → 0.2.6tar.gz