mlmm-toolkit 0.4.0__tar.gz → 0.4.2__tar.gz

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/CHANGELOG.md

@@ -8,6 +8,30 @@ The format follows [Keep a Changelog](https://keepachangelog.com/).
 
 _No changes yet._
 
+## [0.4.2] — 2026-10-22
+
+### Changed
+
+- Compute the Hessian of the `--embedcharge` xTB correction far more efficiently: only the ML atoms and link hydrogens are displaced, the ML–MM block comes from the point-charge forces and the MM–MM block from the xTB charges of the ML region, so `freq`, `tsopt` and `irc` with an MLIP no longer grow with the number of MM atoms (the coupling of two MM charges through the polarized ML region is left out).
+
+### Fixed
+
+- `--embedcharge-cutoff` is measured once on the `--ref-pdb` structure (else the `-i` PDB), and `all` uses one structure for all its stages, so dimer segments, restarts and R, TS and P keep the same point charges; MM atoms one or two bonds from the ML region stay out at any cutoff, so `--embedcharge-cutoff 12` does not restore the 0.4.0 selection as the 0.4.1 entry says.
+- `dft`, `path-opt` and `path-search` apply `--ref-pdb` to a PDB input, as the other commands do.
+- The MM host of a manual `link_mlmm` pair is never a point charge, even without a parm7 bond.
+- MLIP backends stop with an error, as DFT does, when `--embedcharge` selects no point charges.
+
+## [0.4.1] — 2026-10-21
+
+### Fixed
+
+- Count the ML–MM electrostatics of `--embedcharge` once in `-b dft`, `mlmm dft`, and the xTB correction of the MLIP backends, following ONIOM-EE as in Gaussian ([#18](https://github.com/t-0hmura/mlmm_toolkit/issues/18), [#19](https://github.com/t-0hmura/mlmm_toolkit/pull/19)); the xTB correction now includes the link hydrogens.
+
+### Changed
+
+- `--embedcharge-cutoff` has no default: every MM atom except those one or two bonds from the ML region is a point charge (`--embedcharge-cutoff 12` restores the previous selection).
+- Place the scaled link hydrogen with an H radius of 0.31 Å (C–H 1.077 Å for a cut C–C bond); ML/MM results with a cut bond change slightly.
+
 ## [0.4.0] — 2026-10-12
 
 ### Breaking changes

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/CITATION.cff

@@ -12,7 +12,7 @@ authors:
 license: GPL-3.0-or-later
 repository-code: "https://github.com/t-0hmura/mlmm_toolkit"
 url: "https://t-0hmura.github.io/mlmm_toolkit/"
-version: "0.4.0"
+version: "0.4.2"
 preferred-citation:
   type: article
   title: "ML/MM toolkit – Towards Accelerated Mechanistic Investigation of Enzymatic Reactions"

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlmm-toolkit
-Version: 0.4.0
+Version: 0.4.2
 Summary: mlmm - ML/MM toolkit for enzyme reaction analysis
 Author-email: Takuto Ohmura <ohmura.takuto@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -81,10 +81,7 @@ Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
 Dynamic: license-file
 
 <p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/t-0hmura/mlmm_toolkit/main/docs/_static/mlmm-toolkit-logo-dark.svg">
-    <img src="https://raw.githubusercontent.com/t-0hmura/mlmm_toolkit/main/docs/_static/mlmm-toolkit-logo.svg" alt="mlmm-toolkit" width="520">
-  </picture>
+  <img src="https://raw.githubusercontent.com/t-0hmura/mlmm_toolkit/main/docs/_static/mlmm-toolkit-logo-plate.svg" alt="mlmm-toolkit" width="546">
 </p>
 
 # `mlmm-toolkit`: An End-to-End ML/MM ONIOM Platform for Automated Enzymatic Reaction Mechanism Analysis

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/README.md

@@ -1,8 +1,5 @@
 <p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/t-0hmura/mlmm_toolkit/main/docs/_static/mlmm-toolkit-logo-dark.svg">
-    <img src="https://raw.githubusercontent.com/t-0hmura/mlmm_toolkit/main/docs/_static/mlmm-toolkit-logo.svg" alt="mlmm-toolkit" width="520">
-  </picture>
+  <img src="https://raw.githubusercontent.com/t-0hmura/mlmm_toolkit/main/docs/_static/mlmm-toolkit-logo-plate.svg" alt="mlmm-toolkit" width="546">
 </p>
 
 # `mlmm-toolkit`: An End-to-End ML/MM ONIOM Platform for Automated Enzymatic Reaction Mechanism Analysis

mlmm_toolkit-0.4.2/docs/agent-skills.md

@@ -0,0 +1,48 @@
+# Skills for AI Agents
+
+`mlmm-toolkit` ships instructions for AI agents (Claude Code, Codex, Cursor, and others) in the `skills/` directory. With the skills loaded, an agent can run and analyze calculations from plain-language instructions.
+
+## First example
+
+To install them, tell your AI agent:
+
+> Import `https://github.com/t-0hmura/mlmm_toolkit/tree/main/skills` as skills, and install mlmm-toolkit by following `mlmm-install`.
+
+If you cloned the GitHub repository, you can give the local `skills/` path instead. Then you can ask, for example:
+
+> Read *the paper*, build a model from the PDB structure *PDB ID*, and study the mechanism of *the reaction step* with the mlmm-toolkit skills.
+
+## Skills
+
+Each folder in `skills/` is one skill (`<name>/SKILL.md`).
+
+| Skill | What it covers |
+| --- | --- |
+| `mlmm-overview` (start here) | What mlmm-toolkit is, which of the three `all` modes fits your structures, TS strategy, and how to read the outputs |
+| `mlmm-cli` | When to use each subcommand, how to judge success, and pitfalls and recovery |
+| `mlmm-model-setup` | Structure files and Amber parm7/rst7, the charge and multiplicity, the ML region and layers, and keeping the same atoms across states and variants |
+| `mlmm-install` | Installing mlmm-toolkit, the MLIP backends, DFT, xTB, and AmberTools, and probing an unknown environment |
+| `mlmm-hpc` | PBS / SLURM job scripts, walltime, monitoring, and dynamic dispatch |
+| `colab-local-gpu-runtime` | Running the Colab interface on a local NVIDIA GPU through WSL2 and Docker Desktop on Windows |
+
+## Install by hand
+
+Copy the skill folders into your agent's skill directory:
+
+* Claude Code: `.claude/skills/` in a project, or `~/.claude/skills/` for all projects.
+* Codex: `.agents/skills/` in a repository, or `~/.agents/skills/` for all repositories.
+
+For example, from the root of the repository:
+
+```bash
+mkdir -p ~/.claude/skills
+cp -r skills/mlmm-* skills/colab-local-gpu-runtime ~/.claude/skills/
+```
+
+The skills leave exact flags and defaults to the installed CLI (`mlmm <subcommand> --help-advanced`) and the [command reference](reference/commands/index.md).
+
+## See also
+
+* [Getting Started](getting-started.md) — the shortest run, and which page to read next
+* [Installation](installation.md) — setting up the environment
+* [`skills/README.md`](https://github.com/t-0hmura/mlmm_toolkit/blob/main/skills/README.md) — the skill list on GitHub

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/backends.md

@@ -134,11 +134,15 @@ a `H_double: false` in the config is overridden with a warning.
 ## xTB electrostatic correction
 
 For MLIP/MM workflows, `--embedcharge/--no-embedcharge` (default off) adds
-`E_xTB(ML + MM point charges) - E_xTB(ML)` and the corresponding force and
-Hessian difference, so the ML region feels the MM point charges.
+`E_xTB(ML + link H + MM point charges) - E_xTB(ML + link H)` and the
+corresponding force and Hessian difference, so the ML region feels the MM point
+charges. xTB sees the same ML region and link hydrogens as the MLIP. The
+embedding follows ONIOM-EE: MM atoms one or two bonds from the ML region are not
+point charges, and MODEL-low adds the Coulomb energy between the ML force-field
+charges and the point charges ([ML/MM Calculator](mlmm-calc.md)).
 
-With `-b dft`, `--embedcharge` instead places the MM point charges directly in
-the PySCF Hamiltonian, without the xTB correction.
+With `-b dft`, `--embedcharge` instead places the same MM point charges directly
+in the PySCF Hamiltonian, without the xTB correction.
 
 ## DFT/MM backend
 
@@ -275,7 +279,11 @@ ML-region energy, forces, and Hessian in the correct units.
 - A backend whose package is not installed stops with an error such as ``orb-models is required for the ORB backend. Install with `pip install orb-models`.``
 - `--embedcharge` runs xTB with and without the MM point charges at every
   energy, force, and Hessian evaluation; keep the ML region to about 200–300
-  atoms and benchmark the actual system first.
+  atoms and benchmark the actual system first. The Hessian of the xTB
+  correction is a finite difference over the ML atoms and link hydrogens: the
+  point-charge forces of those runs give the ML–MM part, and the MM–MM part
+  uses the xTB atomic charges of the ML region, so the cost does not grow with
+  the number of MM atoms.
 
 ## See Also
 

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/dft-backend.md

@@ -76,7 +76,7 @@ With `-b dft`, the output has the same layout as an MLIP/MM run in the same mode
 | `-b, --backend dft` | Use DFT for the ML region (GPU4PySCF; CPU PySCF with `--dft-engine cpu`). | `uma` |
 | `--parm7 FILE`, `--model-pdb FILE` | Reuse the MM topology and the ML region of an earlier run. Without them, `all` builds them again from the input. | — |
 | `--func-basis TEXT` | Functional and basis as `FUNCTIONAL/BASIS`. Applies to both `-b dft` and `--dft`. | `wb97m-v/def2-svp` |
-| `--embedcharge/--no-embedcharge`, `--embedcharge-cutoff FLOAT` | With `-b dft`, put the MM point charges within the cutoff (Å) of the ML region into the DFT Hamiltonian. | `--no-embedcharge`, `12.0` |
+| `--embedcharge/--no-embedcharge`, `--embedcharge-cutoff FLOAT` | With `-b dft`, put the MM point charges into the DFT Hamiltonian, leaving out MM atoms one or two bonds from the ML region (ONIOM-EE; see [ML/MM Calculator](mlmm-calc.md)); the cutoff (Å) keeps only those within that distance of the ML region. | `--no-embedcharge`, no cutoff |
 | `--dft/--no-dft` | Add DFT single points on R, TS, and P (`all` only). | `--no-dft` |
 
 The other DFT options (`--dft-engine`, `--dft-low-memory/--no-dft-low-memory`, `--dft-nprocs`, `--dft-memory`, SCF checkpoints) are listed in the [`all` reference](reference/commands/all.md).

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/dft.md

@@ -60,7 +60,7 @@ mlmm dft -i enzyme.pdb --parm7 real.parm7 --model-pdb ml_region.pdb \
 1. **Building the ML region**:
 `dft` reads the full system from `-i`, the Amber topology from `--parm7`, and the ML region from `--model-pdb`, `--model-indices`, or the B-factors of the input. For an XYZ input, `--ref-pdb` gives the PDB/mmCIF topology. Link hydrogens cap the bonds of `--parm7` that the ML/MM boundary cuts, and the ML region is saved without and with them.
 2. **SCF**:
-`--func-basis` sets the functional and basis; a basis whose name begins with `def2` gets the matching def2 effective core potential (ECP). `--dft-engine` selects GPU4PySCF (`gpu`, the default) or PySCF (`cpu`). A closed shell runs RKS and an open shell UKS. Low-memory mode, on by default, builds J and K directly without density fitting; on the GPU, a closed shell then uses GPU4PySCF's low-memory RKS. `--no-dft-low-memory` uses density fitting instead. With `--embedcharge`, the MM point charges of `--parm7` within `--embedcharge-cutoff` of the ML region enter the DFT Hamiltonian.
+`--func-basis` sets the functional and basis; a basis whose name begins with `def2` gets the matching def2 effective core potential (ECP). `--dft-engine` selects GPU4PySCF (`gpu`, the default) or PySCF (`cpu`). A closed shell runs RKS and an open shell UKS. Low-memory mode, on by default, builds J and K directly without density fitting; on the GPU, a closed shell then uses GPU4PySCF's low-memory RKS. `--no-dft-low-memory` uses density fitting instead. With `--embedcharge`, the MM point charges of `--parm7` enter the DFT Hamiltonian; `--embedcharge-cutoff` keeps only those within that distance (Å) of the ML region. MM atoms one or two bonds from the ML region are left out, and the MODEL-low energy includes the Coulomb energy between the ML force-field charges and the point charges, so the ML–MM electrostatics are counted once (ONIOM-EE; see [ML/MM Calculator](mlmm-calc.md)).
 3. **ML(DFT)/MM energy**:
 The DFT energy of the ML region with link hydrogens takes the place of the ML energy in the ONIOM sum: `E_REAL_low` and `E_MODEL_low` are the MM energies of the full system and of the ML region.
 4. **Charges and the result file**:
@@ -111,7 +111,7 @@ The options shared by every ML/MM calculation command are explained once in {ref
 | `--dft-nprocs` | integer | auto | PySCF CPU threads (detected from the scheduler and the host) |
 | `--dft-memory` | text | auto | PySCF host RAM limit (e.g. `64GB`); this is not GPU memory |
 | `--embedcharge/--no-embedcharge` | flag | `False` | Put the MM point charges into the DFT Hamiltonian |
-| `--embedcharge-cutoff` | float | `12.0` | Distance (Å) from the ML region within which MM point charges are embedded |
+| `--embedcharge-cutoff` | float | none | Distance (Å) from the ML region within which MM point charges are embedded; without it, every MM atom except those one or two bonds from the ML region |
 | `--convert-files/--no-convert-files` | flag | `True` | Also write the ML region as PDB (PDB input only) |
 | `-o, --out-dir` | path | `./result_dft/` | Output directory |
 

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/getting-started.md

@@ -228,7 +228,7 @@ If you cloned the GitHub repository, you can give the local `skills/` path inste
 
 > Read *the paper*, build a model from the PDB structure *PDB ID*, and study the mechanism of *the reaction step* with the mlmm-toolkit skills.
 
-The skills cover the CLI subcommands, structure input and output, backend installation, TS search strategy, and HPC runs. Load `skills/` into an agent, and it can run and analyze calculations from plain-language instructions. For where to place the files and the full list of skills, see [`skills/README.md`](https://github.com/t-0hmura/mlmm_toolkit/blob/main/skills/README.md).
+The skills cover the CLI subcommands, structure input and output, backend installation, TS search strategy, and HPC runs. Load `skills/` into an agent, and it can run and analyze calculations from plain-language instructions. For where to place the files and the full list of skills, see [Skills for AI Agents](agent-skills.md).
 
 ---
 

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/index.md

@@ -45,6 +45,7 @@ model-setup
 mechanism-tips
 dft-backend
 troubleshooting
+agent-skills
 ```
 
 ```{toctree}
@@ -122,6 +123,7 @@ ja/model-setup
 ja/mechanism-tips
 ja/dft-backend
 ja/troubleshooting
+ja/agent-skills
 ```
 
 ```{toctree}
@@ -282,6 +284,8 @@ If you cloned the GitHub repository, you can give the local `skills/` path inste
 
 > Read *the paper*, build a model from the PDB structure *PDB ID*, and study the mechanism of *the reaction step* with the mlmm-toolkit skills.
 
+For details, see [Skills for AI Agents](agent-skills.md).
+
 ## Citation
 
 If you use mlmm-toolkit in your research, cite the ChemRxiv paper:
@@ -301,7 +305,7 @@ To cite the software or a specific release, use the Zenodo record:
   author       = {Ohmura, Takuto},
   title        = {mlmm-toolkit},
   year         = {2026},
-  version      = {0.4.0},
+  version      = {0.4.2},
   url          = {https://github.com/t-0hmura/mlmm_toolkit},
   license      = {GPL-3.0-or-later},
   doi          = {10.5281/zenodo.19197863}

mlmm_toolkit-0.4.2/docs/ja/agent-skills.md

@@ -0,0 +1,48 @@
+# AI エージェント向けスキル
+
+`mlmm-toolkit` には、AI エージェント（Claude Code、Codex、Cursor など）向けの手順書（スキル）が `skills/` ディレクトリに同梱されています。`skills/` をエージェントに読み込ませることで、自然言語による指示で計算の実行と解析を行えます。
+
+## 最初の例
+
+導入するときは、AI エージェントに次のように指示してください。
+
+> `https://github.com/t-0hmura/mlmm_toolkit/tree/main/skills` をスキルとして取り込み、`mlmm-install` の手順に従って mlmm-toolkit をインストールして
+
+GitHub のリポジトリを clone 済みなら、URL の代わりに手元の `skills/` の path を渡しても構いません。導入後は、たとえば次のように指示できます。
+
+> 〈論文〉を読んで、〈PDB ID〉の構造からモデルを作成し、〈反応段階〉の経路について、mlmm-toolkit のスキルを用いて反応機構解析を行ってください。
+
+## スキルの一覧
+
+`skills/` 内の各フォルダが 1 つのスキル（`<名前>/SKILL.md`）に対応します。
+
+| スキル | 内容 |
+| --- | --- |
+| `mlmm-overview`（最初に参照） | mlmm-toolkit の概要、構造に応じた `all` の 3 つの入力モードの選択、TS 探索の方針、出力の解釈 |
+| `mlmm-cli` | 各サブコマンドの用途、成否の判定、注意点と対処 |
+| `mlmm-model-setup` | 構造ファイルと Amber parm7・rst7 の取り扱い、電荷とスピン多重度の決定、ML 領域と層の設定、状態間・変異体間での原子の対応 |
+| `mlmm-install` | mlmm-toolkit 本体・MLIP バックエンド・DFT・xTB・AmberTools の導入、計算環境（スケジューラ・GPU・CUDA・conda）の確認 |
+| `mlmm-hpc` | PBS・SLURM のジョブスクリプト、walltime の目安、ジョブの監視、動的なジョブ割り当て |
+| `colab-local-gpu-runtime` | WSL2 と Docker Desktop を用いた、ローカルの NVIDIA GPU 上での Colab インターフェースの実行（Windows） |
+
+## 手動で導入する場合
+
+スキルのフォルダを、使用するエージェントのスキル用ディレクトリにコピーします。
+
+* Claude Code：プロジェクト単位では `.claude/skills/`、全プロジェクト共通では `~/.claude/skills/`
+* Codex：リポジトリ単位では `.agents/skills/`、全リポジトリ共通では `~/.agents/skills/`
+
+例として、リポジトリのルートで次のコマンドを実行します。
+
+```bash
+mkdir -p ~/.claude/skills
+cp -r skills/mlmm-* skills/colab-local-gpu-runtime ~/.claude/skills/
+```
+
+オプションの詳細と既定値は、インストールした CLI の `mlmm <subcommand> --help-advanced` と[コマンドリファレンス](../reference/commands/index.md)で確認してください。
+
+## 関連ドキュメント
+
+* [はじめに](getting-started.md) — 最短の実行と、次に読むページ
+* [インストール](installation.md) — 環境の準備
+* [`skills/README.md`](https://github.com/t-0hmura/mlmm_toolkit/blob/main/skills/README.md) — GitHub 上のスキルの一覧

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/ja/backends.md

@@ -102,9 +102,9 @@ UMA では次の 2 つのどちらかを選んでください。
 
 ## xTB 静電補正
 
-MLIP/MM の計算では、`--embedcharge/--no-embedcharge`（デフォルトはオフ）で `E_xTB(ML + MM point charges) - E_xTB(ML)` と、それに対応する力と Hessian の差を足し、ML 領域に MM の点電荷の影響を入れます。
+MLIP/MM の計算では、`--embedcharge/--no-embedcharge`（デフォルトはオフ）で `E_xTB(ML + link H + MM point charges) - E_xTB(ML + link H)` と、それに対応する力と Hessian の差を足し、ML 領域に MM の点電荷の影響を入れます。xTB には MLIP と同じ ML 領域とリンク水素を渡します。埋め込みは ONIOM-EE の形で、ML 領域から 1・2 結合の MM 原子は点電荷にせず、MODEL-low には ML 原子の力場の電荷と点電荷との Coulomb エネルギーを足します（[ML/MM 計算機](mlmm-calc.md)）。
 
-`-b dft` では、`--embedcharge` は xTB の補正を使わず、MM の点電荷を PySCF のハミルトニアンに直接入れます。
+`-b dft` では、`--embedcharge` は xTB の補正を使わず、同じ MM の点電荷を PySCF のハミルトニアンに直接入れます。
 
 ## DFT/MM バックエンド
 
@@ -181,7 +181,7 @@ ML/MM の段では、選んだ ML バックエンドと Hessian の途中の配
 - UMA で `--uma-workers` を 2 以上にすると、`--hessian-calc-mode Analytical` とは併用できず、エラーで止まります。並列の予測器は autograd のモデルを持たないためです。解析 Hessian には `--uma-workers 1` を、複数のワーカーには `FiniteDifference` を使ってください。
 - MACE は UMA と同じ環境には入れられません。専用の conda 環境に入れてください。
 - パッケージを入れていないバックエンドを選ぶと、``orb-models is required for the ORB backend. Install with `pip install orb-models`.`` のようなエラーで止まります。
-- `--embedcharge` はエネルギー、力、Hessian を求めるたびに、MM の点電荷あり・なしで xTB を実行します。ML 領域は 200〜300 原子くらいまでにし、実際の系で先に計算時間を測ってください。
+- `--embedcharge` はエネルギー、力、Hessian を求めるたびに、MM の点電荷あり・なしで xTB を実行します。ML 領域は 200〜300 原子くらいまでにし、実際の系で先に計算時間を測ってください。xTB の補正の Hessian は ML 原子と link H についての有限差分です。そのときの点電荷にかかる力から ML–MM の部分を、ML 領域の xTB の原子電荷から MM–MM の部分を求めるので、MM 原子が多くても重くなりません。
 
 ## 関連ドキュメント
 

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/ja/dft-backend.md

@@ -76,7 +76,7 @@ mlmm all -i result_all/segments/seg_01/ts.pdb \
 | `-b, --backend dft` | ML 領域を DFT で計算します（GPU4PySCF。`--dft-engine cpu` で CPU の PySCF）。 | `uma` |
 | `--parm7 FILE`、`--model-pdb FILE` | 前の計算の MM のトポロジーと ML 領域を使い回します。省くと、`all` が入力から作り直します。 | — |
 | `--func-basis TEXT` | 汎関数と基底を `FUNCTIONAL/BASIS` の形で指定します。`-b dft` と `--dft` の両方に効きます。 | `wb97m-v/def2-svp` |
-| `--embedcharge/--no-embedcharge`、`--embedcharge-cutoff FLOAT` | `-b dft` のとき、ML 領域から cutoff（Å）以内の MM の点電荷を DFT のハミルトニアンに入れます。 | `--no-embedcharge`、`12.0` |
+| `--embedcharge/--no-embedcharge`、`--embedcharge-cutoff FLOAT` | `-b dft` のとき、MM の点電荷を DFT のハミルトニアンに入れます。ML 領域から 1・2 結合の MM 原子は入れません（ONIOM-EE。[ML/MM 計算機](mlmm-calc.md) を参照）。cutoff（Å）を指定すると、ML 領域からその距離以内の点電荷だけを入れます。 | `--no-embedcharge`、cutoff なし |
 | `--dft/--no-dft` | R・TS・P に DFT の一点計算を足します（`all` だけ）。 | `--no-dft` |
 
 ほかの DFT のオプション（`--dft-engine`、`--dft-low-memory/--no-dft-low-memory`、`--dft-nprocs`、`--dft-memory`、SCF のチェックポイント）は [`all` のオプションの一覧（英語のみ）](../reference/commands/all.md)にあります。

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/ja/dft.md

@@ -60,7 +60,7 @@ mlmm dft -i enzyme.pdb --parm7 real.parm7 --model-pdb ml_region.pdb \
 1. **ML 領域を組む**:
 `-i` から全系を、`--parm7` から Amber トポロジーを、`--model-pdb`・`--model-indices`・入力の B-factor のどれかから ML 領域を読みます。XYZ 入力では、PDB/mmCIF のトポロジーを `--ref-pdb` で与えます。ML/MM の境界で切れる `--parm7` の結合をリンク水素でふさぎ、ML 領域をリンク水素なしとありの 2 通りで保存します。
 2. **SCF**:
-`--func-basis` で汎関数と基底を選びます。名前が `def2` で始まる基底には、対応する def2 の有効内殻ポテンシャル（ECP）を付けます。`--dft-engine` で GPU4PySCF（`gpu`、デフォルト）か PySCF（`cpu`）を選びます。閉殻は RKS、開殻は UKS で計算します。デフォルトで有効な低メモリモードでは、密度フィッティング（density fitting）を使わずに J と K を直接組み立てます。このとき、GPU で閉殻系を計算する場合は GPU4PySCF の低メモリ版 RKS を使います。`--no-dft-low-memory` では密度フィッティングを使います。`--embedcharge` を付けると、ML 領域から `--embedcharge-cutoff` 以内にある `--parm7` の MM 点電荷を DFT のハミルトニアンに入れます。
+`--func-basis` で汎関数と基底を選びます。名前が `def2` で始まる基底には、対応する def2 の有効内殻ポテンシャル（ECP）を付けます。`--dft-engine` で GPU4PySCF（`gpu`、デフォルト）か PySCF（`cpu`）を選びます。閉殻は RKS、開殻は UKS で計算します。デフォルトで有効な低メモリモードでは、密度フィッティング（density fitting）を使わずに J と K を直接組み立てます。このとき、GPU で閉殻系を計算する場合は GPU4PySCF の低メモリ版 RKS を使います。`--no-dft-low-memory` では密度フィッティングを使います。`--embedcharge` を付けると、`--parm7` の MM 点電荷を DFT のハミルトニアンに入れます。`--embedcharge-cutoff` を指定すると、ML 領域からその距離（Å）以内の点電荷だけを入れます。ML 領域から 1・2 結合の MM 原子は点電荷にせず、MODEL-low のエネルギーには ML 原子の力場の電荷と点電荷との Coulomb エネルギーを含めるので、ML–MM の静電相互作用は 1 回だけ数えます（ONIOM-EE。[ML/MM 計算機](mlmm-calc.md) を参照）。
 3. **ML(DFT)/MM のエネルギー**:
 リンク水素を含む ML 領域の DFT エネルギーを、ONIOM の和の ML のエネルギーの代わりに使います。`E_REAL_low` と `E_MODEL_low` は、全系と ML 領域の MM エネルギーです。
 4. **電荷と結果ファイル**:
@@ -111,7 +111,7 @@ ML/MM の計算コマンドに共通のオプションは {ref}`ML/MM の共通
 | `--dft-nprocs` | 整数 | auto | PySCF の CPU スレッド数（スケジューラとホストから自動検出） |
 | `--dft-memory` | 文字列 | auto | PySCF のホスト RAM の上限（例: `64GB`）。GPU メモリではない |
 | `--embedcharge/--no-embedcharge` | フラグ | `False` | MM の点電荷を DFT のハミルトニアンに入れる |
-| `--embedcharge-cutoff` | 浮動小数点数 | `12.0` | 点電荷を入れる MM 原子の、ML 領域からの距離（Å） |
+| `--embedcharge-cutoff` | 浮動小数点数 | なし | 点電荷を入れる MM 原子の、ML 領域からの距離（Å）。指定しないと、ML 領域から 1・2 結合の MM 原子を除くすべての MM 原子 |
 | `--convert-files/--no-convert-files` | フラグ | `True` | ML 領域を PDB でも書き出す（PDB 入力のときだけ） |
 | `-o, --out-dir` | パス | `./result_dft/` | 出力先ディレクトリ |
 

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/ja/getting-started.md

@@ -224,11 +224,11 @@ AI エージェント（Claude Code、Codex、Cursor など）向けの手順書
 
 > `https://github.com/t-0hmura/mlmm_toolkit/tree/main/skills` をスキルとして取り込み、`mlmm-install` の手順に従って mlmm-toolkit をインストールして
 
-GitHub のリポジトリを clone 済みなら、URL の代わりに手元の `skills/` の path を渡しても構いません。導入した後は、たとえば次のように頼めます。
+GitHub のリポジトリを clone 済みなら、URL の代わりに手元の `skills/` の path を渡しても構いません。導入後は、たとえば次のように指示できます。
 
 > 〈論文〉を読んで、〈PDB ID〉の構造からモデルを作成し、〈反応段階〉の経路について、mlmm-toolkit のスキルを用いて反応機構解析を行ってください。
 
-CLI サブコマンド、構造の入出力、バックエンドの導入、TS 探索の方針、HPC での実行が書かれています。`skills/` をエージェントに読み込ませることで、エージェントを通じた自然言語指示による計算実行・解析が可能になります。配置場所とスキルの一覧は [`skills/README.md`](https://github.com/t-0hmura/mlmm_toolkit/blob/main/skills/README.md) を参照してください。
+CLI サブコマンド、構造の入出力、バックエンドの導入、TS 探索の方針、HPC での実行が書かれています。`skills/` をエージェントに読み込ませることで、エージェントを通じた自然言語指示による計算実行・解析が可能になります。配置場所とスキルの一覧は [AI エージェント向けスキル](agent-skills.md) を参照してください。
 
 ---
 

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/ja/index.md

@@ -127,10 +127,12 @@ orphan: true
 
 > `https://github.com/t-0hmura/mlmm_toolkit/tree/main/skills` をスキルとして取り込み、`mlmm-install` の手順に従って mlmm-toolkit をインストールして
 
-GitHub のリポジトリを clone 済みなら、URL の代わりに手元の `skills/` の path を渡しても構いません。導入した後は、たとえば次のように頼めます。
+GitHub のリポジトリを clone 済みなら、URL の代わりに手元の `skills/` の path を渡しても構いません。導入後は、たとえば次のように指示できます。
 
 > 〈論文〉を読んで、〈PDB ID〉の構造からモデルを作成し、〈反応段階〉の経路について、mlmm-toolkit のスキルを用いて反応機構解析を行ってください。
 
+詳しくは [AI エージェント向けスキル](agent-skills.md) を参照してください。
+
 ## 引用
 
 `mlmm-toolkit` を研究で利用する場合は、ChemRxiv の論文を引用してください:
@@ -152,7 +154,7 @@ GitHub のリポジトリを clone 済みなら、URL の代わりに手元の `
   author       = {Ohmura, Takuto},
   title        = {mlmm-toolkit},
   year         = {2026},
-  version      = {0.4.0},
+  version      = {0.4.2},
   url          = {https://github.com/t-0hmura/mlmm_toolkit},
   license      = {GPL-3.0-or-later},
   doi          = {10.5281/zenodo.19197863}

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/ja/mlmm-calc.md

@@ -22,6 +22,8 @@ E_ONIOM = E(REAL-low) - E(MODEL-low) + E(MODEL-high)
 
 全系を MM で評価し、ML 領域を高レベルと MM の両方で評価して、ML 領域の MM エネルギーを差し引くことで二重に数えないようにします。力と Hessian も同じ差し引きで合わせます。
 
+`--embedcharge` を付けると、ONIOM-EE の形の静電埋め込み（[Vreven et al., *J. Chem. Theory Comput.* 2006, 2, 815](https://doi.org/10.1021/ct050289g)）を使います。MM の点電荷を MODEL-high に入れ、MODEL-low には ML 原子の力場の電荷と同じ点電荷との Coulomb エネルギーを足します。この項が、REAL-low に含まれるそれらの点電荷と ML 領域の Coulomb エネルギーを打ち消すので、この相互作用は高レベルで 1 回だけ数えます。ML 領域から 1・2 結合の MM 原子は点電荷にせず、ML 領域との相互作用は REAL-low の力場の項に残ります。それ以外の MM 原子はすべて点電荷にし、Gaussian と同じく距離の cutoff は設けません。`--embedcharge-cutoff` を指定すると、ML 領域からその距離（Å）以内の原子だけを点電荷にし、`--ref-pdb` の構造（無ければ `-i` の PDB）で一度選んだあとは変えません。R・TS・P に同じ `--ref-pdb` を渡せば同じ点電荷になり、`all` は全段で同じ構造を使います。
+
 ### 一般的な QM/MM との比較
 
 | 側面 | 一般的な QM/MM | mlmm-toolkit の ML/MM |
@@ -29,7 +31,7 @@ E_ONIOM = E(REAL-low) - E(MODEL-low) + E(MODEL-high)
 | 高レベル手法 | DFT、HF、post-HF | MLIP（UMA、ORB、MACE、AIMNet2）または DFT（`-b dft`） |
 | 低レベル手法 | OpenMM / Amber | `hessian_ff`（デフォルト）/ OpenMM |
 | リンク原子 | 通常は必要 | parm7 の結合のうち ML/MM 境界をまたぐものすべてに自動で付く |
-| 埋め込み | 静電埋め込みが一般的 | デフォルトは機械的埋め込み。`--embedcharge` で MM の点電荷を入れる（MLIP では xTB の補正、DFT では PySCF の Hamiltonian） |
+| 埋め込み | 静電埋め込みが一般的 | デフォルトは機械的埋め込み。`--embedcharge` で MM の点電荷を ONIOM-EE の形で入れる（MLIP では xTB の補正、DFT では PySCF の Hamiltonian） |
 | 速度 | 遅い（QM が律速） | MLIP なら速い（GPU で推論）。`-b dft` は DFT と同じコスト |
 
 ## Hessian / 最適化用の層設定
@@ -47,7 +49,7 @@ ML/MM 境界が共有結合を切るとき、MODEL-high の計算では、切れ
 
 | 方式 | 配置 | 推奨 |
 | --- | --- | --- |
-| **scaled**（g-factor、デフォルト） | `r_L = r_QM + g·(r_MM − r_QM)`、`g = (CR_QM + CR_H)/(CR_QM + CR_MM)`（共有結合半径） | 推奨（デフォルト。Gaussian ONIOM と同じ方式） |
+| **scaled**（g-factor、デフォルト） | `r_L = r_QM + g·(r_MM − r_QM)`、`g = (CR_QM + CR_H)/(CR_QM + CR_MM)`（[Cordero et al. 2008](https://doi.org/10.1039/b801115j) の共有結合半径。`CR_H` = 0.31 Å で、1.53 Å の C–C を切ると C–H は 1.077 Å） | 推奨（デフォルト。Gaussian ONIOM と同じ方式） |
 | **fixed** | `r_L = r_QM + d·û`、`d` = 1.09 Å（親が C）/ 1.01 Å（親が N）、`û` は MM 原子へ向かう単位ベクトル | 代替（ML 側の親原子が C か N のときだけ） |
 
 scaled は Gaussian ONIOM と同じ Morokuma–Dapprich の g-factor 法で、リンク水素は QM–MM 距離に比例して動きます。fixed は、リンク水素を結合軸に沿って一定の距離に置きます。

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/ja/yaml-reference.md

@@ -196,7 +196,8 @@ calc:
 
  # --- 静電埋め込み（任意） ---
  embedcharge: false # MLIP は高コストな xTB 補正、dft は PySCF への直接静電埋込み
- embedcharge_cutoff: 12.0 # ML 領域からの MM 点電荷カットオフ (Å)
+ embedcharge_cutoff: null # ML 領域からの MM 点電荷カットオフ (Å)。null は ML 領域から 1・2 結合の MM 原子を除く全 MM 原子
+ embedcharge_reference: null # embedcharge_cutoff を測る構造。null は入力の PDB
  embedcharge_step: 0.001 # MLIP/xTB 補正用の数値 Hessian ステップ（dft では未使用）
  xtb_cmd: xtb # xTB 実行コマンド
  xtb_acc: 0.2 # xTB 精度パラメータ

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/mlmm-calc.md

@@ -22,6 +22,8 @@ E_ONIOM = E(REAL-low) - E(MODEL-low) + E(MODEL-high)
 
 The full system is evaluated with MM, the ML region is evaluated at both the high level and the MM level, and the MM energy of the ML region is subtracted so that it is not counted twice. Forces and Hessians follow the same subtraction.
 
+With `--embedcharge`, the calculator uses electrostatic embedding in the ONIOM-EE form ([Vreven et al., *J. Chem. Theory Comput.* 2006, 2, 815](https://doi.org/10.1021/ct050289g)). The MM point charges enter MODEL-high, and MODEL-low adds the Coulomb energy between the force-field charges of the ML atoms and the same point charges. That term cancels the ML–MM Coulomb energy that REAL-low holds for those charges, so the interaction is counted once, at the high level. MM atoms one or two bonds from the ML region are not point charges; their interaction with the ML region stays in REAL-low at the force-field level. All other MM atoms are point charges, with no distance cutoff as in Gaussian; `--embedcharge-cutoff` keeps only those within that distance (Å) of the ML region, chosen once on the `--ref-pdb` structure (else the `-i` PDB) and then kept fixed; the same `--ref-pdb` for R, TS and P gives them the same point charges, and `all` uses one structure for all its stages.
+
 ### Comparison with conventional QM/MM
 
 | Aspect | Conventional QM/MM | mlmm-toolkit ML/MM |
@@ -29,7 +31,7 @@ The full system is evaluated with MM, the ML region is evaluated at both the hig
 | High-level method | DFT, HF, post-HF | MLIP (UMA, ORB, MACE, AIMNet2) or DFT (`-b dft`) |
 | Low-level method | OpenMM / Amber | `hessian_ff` (default) / OpenMM |
 | Link atoms | Usually required | Added automatically for every parm7 bond that crosses the ML/MM boundary |
-| Embedding | Electrostatic embedding is common | Mechanical by default; `--embedcharge` adds the MM point charges (an xTB correction for MLIP backends, the PySCF Hamiltonian for DFT) |
+| Embedding | Electrostatic embedding is common | Mechanical by default; `--embedcharge` adds the MM point charges in the ONIOM-EE form (an xTB correction for MLIP backends, the PySCF Hamiltonian for DFT) |
 | Speed | Slow (QM is the bottleneck) | Fast with an MLIP (GPU inference); `-b dft` runs at DFT cost |
 
 ## Layering for Hessian / optimization
@@ -47,7 +49,7 @@ When the ML/MM boundary cuts a covalent bond, a link hydrogen caps the ML side o
 
 | Method | Placement | Recommended |
 | --- | --- | --- |
-| **scaled** (g-factor, default) | `r_L = r_QM + g·(r_MM − r_QM)` with `g = (CR_QM + CR_H)/(CR_QM + CR_MM)` (covalent radii) | Yes (default; the method of Gaussian ONIOM) |
+| **scaled** (g-factor, default) | `r_L = r_QM + g·(r_MM − r_QM)` with `g = (CR_QM + CR_H)/(CR_QM + CR_MM)` (covalent radii of [Cordero et al. 2008](https://doi.org/10.1039/b801115j), `CR_H` = 0.31 Å; a cut C–C bond of 1.53 Å gives C–H 1.077 Å) | Yes (default; the method of Gaussian ONIOM) |
 | **fixed** | `r_L = r_QM + d·û` with `d` = 1.09 Å (C parent) / 1.01 Å (N parent) and `û` the unit vector toward the MM atom | Alternative (ML-side parent C or N only) |
 
 The scaled placement is the Morokuma–Dapprich g-factor method used in Gaussian ONIOM: the link hydrogen moves linearly with the QM–MM distance. The fixed placement keeps the link hydrogen at a constant distance along the bond axis.

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/reference/commands/all.md

@@ -343,8 +343,15 @@ Options:
                                   correction; DFT/MM stages embed MM charges in
                                   the PySCF Hamiltonian.  [default: no-
                                   embedcharge]
-  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for
-                                  embedded MM point charges.  [default: (12.0)]
+  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for the
+                                  embedded MM point charges, measured on the -i
+                                  PDB (or the --ref-pdb structure when given) so
+                                  that all states share one point-charge set. A
+                                  cutoff lowers the cost, but the default (none:
+                                  every MM atom except those one or two bonds
+                                  from the ML region) is the correct
+                                  electrostatic embedding and is recommended.
+                                  [default: (none)]
   --link-atom-method [scaled|fixed]
                                   Link-atom position mode: scaled (g-factor) or
                                   fixed (1.09/1.01 Å).  [default: (scaled)]

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/reference/commands/dft.md

@@ -15,9 +15,9 @@ Options:
                                   and exit.
   -i, --input FILE                Full enzyme structure (PDB/mmCIF, or XYZ with
                                   --ref-pdb topology).  [required]
-  --ref-pdb FILE                  Reference PDB topology when input is XYZ. XYZ
-                                  coordinates are used (higher precision) while
-                                  PDB provides atom ordering and residue
+  --ref-pdb FILE                  Reference PDB topology, required when input is
+                                  XYZ. The coordinates come from --input, while
+                                  the PDB provides atom ordering and residue
                                   information.
   --parm7, --parm FILE            Amber parm7 topology for the full system.
                                   [required]
@@ -83,10 +83,16 @@ Options:
                                   QM Hamiltonian. The DFT workflow does not use
                                   the optional xTB correction.  [default: no-
                                   embedcharge]
-  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from ML region for MM
-                                  point charges embedded in the PySCF QM
-                                  Hamiltonian. Only used when --embedcharge is
-                                  enabled.  [default: (12.0)]
+  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for the
+                                  embedded MM point charges, measured on the -i
+                                  PDB (or the --ref-pdb structure when given) so
+                                  that all states share one point-charge set. A
+                                  cutoff lowers the cost, but the default (none:
+                                  every MM atom except those one or two bonds
+                                  from the ML region) is the correct
+                                  electrostatic embedding and is recommended.
+                                  Only used when --embedcharge is enabled.
+                                  [default: (none)]
   --link-atom-method [scaled|fixed]
                                   Link-atom placement: 'scaled' (g-factor,
                                   Gaussian ONIOM standard) or 'fixed' (1.09 Å

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/reference/commands/freq.md

@@ -92,9 +92,15 @@ Options:
                                   use the computationally expensive xTB point-
                                   charge delta correction; dft uses native PySCF
                                   MM point charges.  [default: no-embedcharge]
-  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for MM
-                                  point charges used by embedding.  [default:
-                                  (12.0)]
+  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for the
+                                  embedded MM point charges, measured on the -i
+                                  PDB (or the --ref-pdb structure when given) so
+                                  that all states share one point-charge set. A
+                                  cutoff lowers the cost, but the default (none:
+                                  every MM atom except those one or two bonds
+                                  from the ML region) is the correct
+                                  electrostatic embedding and is recommended.
+                                  [default: (none)]
   --link-atom-method [scaled|fixed]
                                   Link-atom position mode: scaled (g-factor) or
                                   fixed (1.09/1.01 Å).  [default: (scaled)]

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/reference/commands/irc.md

@@ -88,9 +88,15 @@ Options:
                                   use the computationally expensive xTB point-
                                   charge delta correction; dft uses native PySCF
                                   MM point charges.  [default: no-embedcharge]
-  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for MM
-                                  point charges used by embedding.  [default:
-                                  (12.0)]
+  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for the
+                                  embedded MM point charges, measured on the -i
+                                  PDB (or the --ref-pdb structure when given) so
+                                  that all states share one point-charge set. A
+                                  cutoff lowers the cost, but the default (none:
+                                  every MM atom except those one or two bonds
+                                  from the ML region) is the correct
+                                  electrostatic embedding and is recommended.
+                                  [default: (none)]
   --link-atom-method [scaled|fixed]
                                   Link-atom position mode: scaled (g-factor) or
                                   fixed (1.09/1.01 Å).  [default: (scaled)]

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/reference/commands/opt.md

@@ -97,9 +97,15 @@ Options:
                                   use the computationally expensive xTB point-
                                   charge delta correction; dft uses native PySCF
                                   MM point charges.  [default: no-embedcharge]
-  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for MM
-                                  point charges used by embedding.  [default:
-                                  (12.0)]
+  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for the
+                                  embedded MM point charges, measured on the -i
+                                  PDB (or the --ref-pdb structure when given) so
+                                  that all states share one point-charge set. A
+                                  cutoff lowers the cost, but the default (none:
+                                  every MM atom except those one or two bonds
+                                  from the ML region) is the correct
+                                  electrostatic embedding and is recommended.
+                                  [default: (none)]
   --link-atom-method [scaled|fixed]
                                   Link-atom position mode: scaled (g-factor) or
                                   fixed (1.09/1.01 Å).  [default: (scaled)]

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/reference/commands/path_opt.md

@@ -113,9 +113,15 @@ Options:
                                   use the computationally expensive xTB point-
                                   charge delta correction; dft uses native PySCF
                                   MM point charges.  [default: no-embedcharge]
-  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for MM
-                                  point charges used by embedding.  [default:
-                                  (12.0)]
+  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for the
+                                  embedded MM point charges, measured on the -i
+                                  PDB (or the --ref-pdb structure when given) so
+                                  that all states share one point-charge set. A
+                                  cutoff lowers the cost, but the default (none:
+                                  every MM atom except those one or two bonds
+                                  from the ML region) is the correct
+                                  electrostatic embedding and is recommended.
+                                  [default: (none)]
   --link-atom-method [scaled|fixed]
                                   Link-atom position mode: scaled (g-factor) or
                                   fixed (1.09/1.01 Å).  [default: (scaled)]

{mlmm_toolkit-0.4.0 → mlmm_toolkit-0.4.2}/docs/reference/commands/path_search.md

@@ -129,9 +129,15 @@ Options:
                                   use the computationally expensive xTB point-
                                   charge delta correction; dft uses native PySCF
                                   MM point charges.  [default: no-embedcharge]
-  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for MM
-                                  point charges used by embedding.  [default:
-                                  (12.0)]
+  --embedcharge-cutoff FLOAT      Distance cutoff (Å) from the ML region for the
+                                  embedded MM point charges, measured on the -i
+                                  PDB (or the --ref-pdb structure when given) so
+                                  that all states share one point-charge set. A
+                                  cutoff lowers the cost, but the default (none:
+                                  every MM atom except those one or two bonds
+                                  from the ML region) is the correct
+                                  electrostatic embedding and is recommended.
+                                  [default: (none)]
   --link-atom-method [scaled|fixed]
                                   Link-atom position mode: scaled (g-factor) or
                                   fixed (1.09/1.01 Å).  [default: (scaled)]