mlmm-toolkit ドキュメント¶

mlmm-toolkit は、酵素複合体を対象として、機械学習原子間ポテンシャル（MLIP）と分子力学（MM）を ONIOM で結合した ML/MM 法を用いて PDB/mmCIF の構造から反応機構を解析する Python 製 CLI ツールキットです。

初めての方ははじめにからお読みください。

はじめにインストール Google Colabで実行

クイックスタート¶

反応の前後の構造から反応機構解析を一気通貫で行う

クイックスタート: all の Endpoint モード

1 つの構造から一気通貫で反応機構解析を行う

クイックスタート: all の Scan-list モード

TS 構造から一気通貫で反応機構解析を行う

クイックスタート: TS-only モード

目的	ページ
ML 領域と層を決める・計算を軽くする	ML 領域と層の組み方
反応機構を調べる・TS が取れない	反応機構を調べるコツ
求めた TS 構造を DFT で構造最適化する	MLIP の TS を DFT で確かめる
計算が失敗した	トラブルシューティング

サブコマンド¶

サブコマンド	説明
`all`	ML/MM モデルの構築と MEP 探索。TS・IRC・熱化学・DFT は任意
`fix-altloc`	PDB の代替位置指示子を解決
`add-elem-info`	PDB の元素列（77–78）を修復
`mm-parm`	Amber のトポロジー・座標（parm7/rst7）を構築
`extract`	タンパク質–リガンド複合体から ML 領域を定義
`define-layer`	ML・可動 MM・固定 MM の層を B-factor で指定
`opt`	単一構造の構造最適化（L-BFGS または RFO。任意の `--flatten` で残った虚振動を除く）
`scan`	拘束付き距離スキャン（複数距離の協奏スキャン・多段階スキャンに対応）
`scan2d`	2 次元のエネルギー地形の探索・PES マッピング
`scan3d`	3 次元のエネルギー地形の探索・PES マッピング
`path-opt`	GSM または DMF による 1 段階の MEP 最適化（2 構造から）
`path-search`	自動精密化を伴う多段階の再帰的 MEP 探索（2 構造以上）
`tsopt`	遷移状態最適化（Dimer または RS-P-RFO。任意の `--flatten` で余分な虚振動を除く）
`irc`	固有反応座標（IRC: Intrinsic Reaction Coordinate）計算
`freq`	振動解析と熱化学
`dft`	DFT 一点計算（GPU4PySCF / PySCF）
`sp`	ML/MM ONIOM のエネルギー・力。任意で Hessian
`bond-summary`	連続構造間の共有結合変化を検出・レポート
`trj2fig`	XYZ 軌跡からエネルギープロファイルをプロット
`energy-diagram`	数値入力からエネルギーダイアグラムを作成
`oniom-export`	Gaussian ONIOM または ORCA QM/MM の入力を生成
`oniom-import`	ONIOM の入力から XYZ・層付き PDB を再構築

設定・参照資料¶

トピック	ページ
共通オプションと入力要件	共通オプションと残基・原子の指定
原子の固定と距離の拘束（`--freeze-atoms`・`--distance-restraint`）	原子の固定と距離の拘束
よくあるエラーと対処	トラブルシューティング
CLI コマンドの一覧（英語のみ、自動生成）	コマンドの一覧（英語のみ）
YAML 設定オプション	YAML 設定の一覧 · YAML の抜粋（英語のみ）
MLIP バックエンド設定	MLIP バックエンド
各コマンドが書き出すファイル	出力ディレクトリのレイアウト
`result.json` と `summary.json` の欄	JSON 出力の一覧
GPU・CPU の割り当てと HPC	デバイス設定 & HPC セットアップ
Python から ML/MM 計算機を使う	ML/MM 計算機
AI エージェントから使う	エージェントスキル
コードの構成（開発者向け）	アーキテクチャ
用語	用語集

システム要件¶

ハードウェア¶

OS: Linux（Windows では WSL2 上の Linux に導入してください）
GPU: 使用するバックエンドと PyTorch wheel に対応する NVIDIA ドライバー。CPU のみでも実行可能ですが低速です
VRAM / RAM: モデル、系の大きさ、Hessian の計算方式で変わります。代表的な計算で最大使用量を測ってください

ソフトウェア¶

Python >= 3.11
CPU 版または CUDA 対応の PyTorch。ビルド済みの wheel は CUDA ランタイムを含むので、手元の CUDA toolkit は通常いりません（ソースからビルドするときだけ必要です）
AmberTools（mm-parm が Amber のトポロジーを作るのに使います）

セットアップはインストールを参照してください。

重要な概念¶

3 つの層（ML・可動 MM・固定 MM）と ONIOM での組み合わせ方ははじめに、ML 領域と層の決め方は ML 領域と層の組み方を参照してください。

エージェントスキル¶

mlmm-toolkit は、CLI サブコマンド・構造 I/O・バックエンドインストール・ワークフロー・出力解析・HPC 運用をカバーする AI エージェント向けの手順書を 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 のスキルを用いて反応機構解析を行ってください。

詳しくは AI エージェント向けスキルを参照してください。

引用¶

mlmm-toolkit を研究で利用する場合は、ChemRxiv の論文を引用してください:

@article{ohmura2025mlmm,
  author       = {Ohmura, Takuto and Inoue, Sei and Terada, Tohru},
  title        = {ML/MM toolkit -- Towards Accelerated Mechanistic Investigation of Enzymatic Reactions},
  journal      = {ChemRxiv},
  year         = {2025},
  doi          = {10.26434/chemrxiv-2025-jft1k}
}

ソフトウェアまたは特定のリリースを引用する場合は、Zenodo レコードを使用してください:

@software{ohmura2026mlmm_software,
  author       = {Ohmura, Takuto},
  title        = {mlmm-toolkit},
  year         = {2026},
  version      = {0.4.0},
  url          = {https://github.com/t-0hmura/mlmm_toolkit},
  license      = {GPL-3.0-or-later},
  doi          = {10.5281/zenodo.19197863}
}

ライセンス¶

mlmm-toolkit は GNU General Public License version 3 or later (GPL-3.0-or-later) の下で配布されています。

ヘルプ¶

# 一般的なヘルプ
mlmm --help

# コマンドのヘルプ
mlmm <subcommand> --help

# 詳細オプション（内部チューニング用）
mlmm <subcommand> --help-advanced

問題や機能リクエストは GitHub Issues に報告してください。