mlmm-toolkit ドキュメント¶

バージョン: v0.2.4

mlmm-toolkit は、機械学習原子間ポテンシャル（Machine Learning Interatomic Potential）と分子力学（Molecular Mechanics）を ONIOM 的に結合した ML/MM 法 を用いて、PDB 構造から酵素反応経路を自動モデリングする Python 製 CLI ツールキットです。

目的別クイックスタート¶

ユースケース	推奨コマンド	ガイド
最初の 1 回を実行（end-to-end）	`mlmm all`	クイックスタート: all
単一構造スキャン（`-s`）	`mlmm scan`	クイックスタート: scan + spec
TS 検証（`tsopt` -> `freq`）	`mlmm tsopt`, `mlmm freq`	クイックスタート: tsopt -> freq
PDB から反応経路探索を一通り実行	`mlmm all`	all.md
現在の設定を確認	`mlmm opt --show-config`	YAML リファレンス
タンパク質-リガンド複合体からQM領域を抽出	`mlmm extract`	extract.md
MM トポロジー（parm7/rst7）を構築	`mlmm mm-parm`	mm_parm.md
ML/MM 3層領域を定義	`mlmm define-layer`	define_layer.md
単一構造を最適化	`mlmm opt`	opt.md
遷移状態を探索・最適化	`mlmm tsopt`	tsopt.md
最小エネルギー経路を探索	`mlmm path-search`	path_search.md
遷移状態からIRCを実行	`mlmm irc`	irc.md
エネルギープロファイルを可視化	`mlmm trj2fig`	trj2fig.md
Gaussian ONIOM / ORCA QM/MM 入力を生成	`mlmm oniom-export --mode g16\|orca`	oniom_export.md
ONIOM 入力から XYZ/層付き PDB を再構築	`mlmm oniom-import`	oniom_import.md
数値から状態エネルギーダイアグラムを描画	`mlmm energy-diagram`	energy_diagram.md
チュートリアルに従う	–	はじめに
症状からエラー対処を探す	–	典型エラー別レシピ
全体像（概念・用語）の把握	–	概念とワークフロー
よくあるエラーの解決	–	トラブルシューティング
略語や用語を調べる	–	用語集

ドキュメントガイド¶

トピック	ページ
インストールと初回実行	はじめに
主要概念とワークフロー概要	概念とワークフロー
症状起点の切り分け	典型エラー別レシピ
よくあるエラーと対処	トラブルシューティング
CLI 規約と入力要件	CLI 規約

CLI サブコマンド¶

メインワークフロー¶

サブコマンド	説明
`all`	end-to-endワークフロー: 抽出 -> MM parm -> MEP -> TS 最適化 -> IRC -> freq -> DFT
`init`	（削除済）以前は YAML テンプレートを生成

構造準備¶

サブコマンド	説明
`extract`	タンパク質-リガンド複合体から活性部位ポケット（クラスターモデル）を抽出
`add-elem-info`	PDB の元素カラム（77-78）を修復
`mm-parm`	AmberTools (tleap + GAFF2) を使用して Amber トポロジー（parm7/rst7）を構築
`define-layer`	ML 領域からの距離に基づき 3 層 ML/MM 領域を定義し、B-factor でエンコード

構造最適化¶

サブコマンド	説明
`opt`	単一構造の構造最適化（L-BFGS / RFO）
`tsopt`	遷移状態最適化（Dimer / RS-I-RFO）

経路探索・最適化¶

サブコマンド	説明
`path-opt`	GSM または DMF による MEP 最適化
`path-search`	自動精密化を伴う再帰的 MEP 探索

スキャン¶

サブコマンド	説明
`scan`	拘束条件付き 1D 結合長スキャン
`scan2d`	2D 距離グリッドスキャン
`scan3d`	3D 距離グリッドスキャン

解析・後処理¶

サブコマンド	説明
`irc`	固有反応座標（IRC）計算
`freq`	振動解析と熱化学
`dft`	DFT 一点計算（GPU4PySCF / PySCF）
`trj2fig`	XYZ 軌跡からエネルギープロファイルをプロット
`energy-diagram`	数値入力からエネルギーダイアグラムを作成

ユーティリティ¶

サブコマンド	説明
`fix-altloc`	PDB の代替コンフォメーション（altloc）を解決
`device-hpc`	HPC 環境での GPU デバイス情報の確認

エクスポート¶

サブコマンド	説明
`oniom-export`	Amber parm7 から Gaussian ONIOM / ORCA QM/MM 入力を生成（`–mode g16
`oniom-import`	Gaussian/ORCA ONIOM 入力を読み込み、XYZ と層付き PDB を再構築

設定・リファレンス¶

トピック	ページ
CLI コマンドリファレンス	コマンドリファレンス
YAML スキーマ	YAML スキーマ
YAML 設定オプション	YAML リファレンス
ML/MM 計算機アーキテクチャ	ML/MM 計算機
用語集	用語集

システム要件¶

ハードウェア¶

OS: Linux（Ubuntu 20.04+、CentOS 8+ で動作確認）
GPU: CUDA 12.x 互換
VRAM: 最小 8 GB（1000 原子以上には 16 GB 以上推奨）
RAM: 16 GB 以上推奨

ソフトウェア¶

Python 3.11
CUDA サポート付き PyTorch
CUDA 12.x ツールキット
AmberTools（mm-parm サブコマンドに必要）

クイック例¶

基本的な ML/MM MEP 探索¶

mlmm -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3'

TS 最適化を含む完全ワークフロー¶

mlmm -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' \
 --tsopt --thermo --dft

単一構造スキャンモード¶

mlmm scan -i pocket.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -s scan.yaml --print-parsed

TS 最適化のみ¶

mlmm -i TS_candidate.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' \
 --tsopt

重要な概念¶

ML/MM 3 層システム¶

mlmm は PDB の B-factor を用いた 3 層分割スキームを使用します:

ML 領域（B=0.0）: UMA 機械学習ポテンシャルで計算
Movable-MM（B=10.0）: 最適化時に移動可能な MM 原子
Frozen（B=20.0）: 座標固定の MM 原子

Hessian 計算に含める MM 原子は、B-factor 専用層ではなく hess_cutoff や hess_mm_atoms で制御します。

電荷とスピン¶

未知残基の電荷を指定するには --ligand-charge を使用: 'SAM:1,GPP:-3'
ML 領域の総電荷を上書きするには -q/--charge を使用
スピン多重度は -m/--multiplicity（デフォルト: 1）で設定

ブール値オプション¶

ブール値 CLI オプションはトグル形式（--flag / --no-flag）を使用します:

--tsopt --thermo --no-dft

YAML 設定¶

すべてのオプションについては YAML リファレンスを参照してください。

出力構造¶

典型的な mlmm all 実行の出力:

result_all/
├── ml_region.pdb # ML 領域定義
├── summary.log # 人間が読めるサマリー
├── summary.yaml # 機械可読サマリー
├── pockets/ # 抽出されたクラスターモデル
├── mm_parm/ # AMBER トポロジーファイル
├── scan/ # （オプション）スキャン結果
├── path_search/ # MEP 軌跡とダイアグラム
│ ├── mep_trj.xyz # MEP 軌跡
│ ├── mep.pdb # PDB 形式の MEP
│ └── seg_*/ # セグメントごとの詳細
└── path_search/post_seg_*/ # 後処理出力
 ├── tsopt/ # TS 最適化結果
 ├── irc/ # IRC 軌跡
 ├── freq/ # 振動モード
 └── dft/ # DFT 結果

引用¶

本ソフトウェアを研究に使用した場合は、以下を引用してください:

[1] Ohmura, T., Inoue, S., Terada, T. (2025). ML/MM toolkit – Towards Accelerated Mechanistic Investigation of Enzymatic Reactions. ChemRxiv. https://doi.org/10.26434/chemrxiv-2025-jft1k

ライセンス¶

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

ヘルプ¶

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

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

Note: 本ドキュメントは現在整備中のため、一部未完成の箇所や今後変更される箇所がある可能性があります。