CLI 規約¶
このページでは、mlmm-toolkit の全コマンドで使用される規約を説明します。
ブール値オプション¶
すべての on/off CLI トグルは 4 つの記法を受け付けます。
記法 |
例 |
|---|---|
肯定フラグ |
|
否定フラグ |
|
肯定の値指定 |
|
否定の値指定 |
|
--tsopt --thermo --no-dft # トグル記法
--tsopt True --thermo yes --dft 0 # 値指定記法
--tsopt true --thermo on --dft off # 混在も可
4 記法はすべて root CLI の bool_compat シンセサイザを経由します。トグル記法（--tsopt / --no-tsopt）が正規形で、値指定記法（--tsopt True）は後方互換のためのレガシー別名として受け付けられます。tests/test_bool_compat_cli.py がリリースごとに登録済みの全ブールオプション × 全記法を走査するため、登録漏れは CI で検出されます。
--detect-layer は例外です。レイヤー検出は既定で自動実行されるため、
on/off トグルではなく肯定フラグだけを公開します。
新しいブールフラグの追加¶
正規 interface は @click.option("--foo/--no-foo", ...) または共通 add_*_option() factory で定義します。通常の Click toggle は runtime の parameter introspection が検出します。lazy command の import 前に正規化する必要がある場合、または parser wrapper により introspection できない場合だけ mlmm/cli/app.py に手動 hint を追加し、どちらの経路も tests/test_bool_compat_cli.py へ追加してください。
よく使うブール値オプション:
--tsopt,--thermo,--dft– 後処理ステージの有効化--dump– 軌跡ファイルの出力--preopt,--endopt– 前処理/後処理最適化の切り替え--climb– MEP 探索でクライミングイメージを有効化
段階的ヘルプ (progressive help)¶
計算系サブコマンドと all は 2 段階ヘルプです:
mlmm all --help # 主要オプションのみ
mlmm all --help-advanced # 全オプション
scan / scan2d / scan3d と計算系サブコマンド（opt / sp / path-opt / path-search / tsopt / freq / irc / dft）に加え、ユーティリティ系（mm-parm / define-layer / add-elem-info / trj2fig / energy-diagram / oniom-export）も同様に段階的 help に対応します。いずれも --help は主要オプションのみ、--help-advanced で全オプションを表示します。extract と fix-altloc も段階的 help に対応し、--help-advanced で parser の全オプションを示します。
設定の確認¶
現在の設定を確認できます（YAML オーバーライドの検証に便利）：
mlmm opt -i input.pdb --parm real.parm7 -q -1 --show-config --dry-run
ML/MM 必須オプション¶
ML/MM 計算を行う大半のサブコマンド（all、extract、mm-parm、define-layer を除く）では、以下のトポロジー指定が常に必要です:
--parm real.parm7 # 全系（real system）の Amber parm7 トポロジーファイル
all ワークフローでは、--parm を省略するとトポロジーを自動生成します。
個別サブコマンドの ML 原子集合は、次の順で決まります。
--model-pdbを指定した場合はその原子集合--model-pdbを省略し、--model-indicesを指定した場合はその原子番号どちらも指定せず、デフォルトの
--detect-layerが有効な場合は入力 PDB の B-factor が示す ML 原子
明示的な ML 原子集合を指定した場合も、有効な B-factor は自動的に Movable-MM/Frozen-MM の割り当てに引き続き使われますが、明示した ML 原子集合を 置き換えません。B-factor の分割には ML 原子と MM 原子がそれぞれ 1 個以上必要で、 全原子が B=0 の PDB は layer 指定として扱いません。
# 個別サブコマンドの例
mlmm path-search -i R.pdb P.pdb --parm real.parm7 --model-pdb model.pdb -q 0 -m 1
B-factor 層エンコーディング¶
mlmm-toolkit は PDB の B-factor 列（列 61-66）を使用して、3 層 ML/MM 分割をエンコードします:
層 |
B-factor |
説明 |
|---|---|---|
ML |
0.0 |
MLIP によるエネルギー・力・Hessian 計算（デフォルトバックエンド: UMA） |
Movable-MM |
10.0 |
最適化時に移動可能な MM 原子 |
Frozen |
20.0 |
座標固定 |
define-layer サブコマンドがこれらの B-factor を PDB に書き込みます。B-factor カラーリングに対応した分子ビューアで層割り当てを確認できます。
B-factor の読み取り時には許容差 1.0 が使用され、0/10/20 に近い値はそれぞれ ML/Movable/Frozen にマッピングされます。
層の定義方法¶
define-layerサブコマンド（推奨）:mlmm define-layer -i system.pdb --model-pdb ml_region.pdb -o labeled.pdb
距離カットオフ（YAML/CLI）:
calc: hess_cutoff: 3.6 # Hessian 対象 MM の距離カットオフ movable_cutoff: 8.0 # Movable-MM の距離カットオフ（それ以外は Frozen）
B-factor からの読み取り:
calc: use_bfactor_layers: true # 入力 PDB の B-factor から層を読み取り
明示的インデックス指定（YAML）:
calc: hess_mm_atoms: [100, 101, 102, ...] movable_mm_atoms: [200, 201, 202, ...] frozen_mm_atoms: [300, 301, 302, ...]
ログ詳細度 (verbosity)¶
-v/--verbose LEVEL は 0〜3 の整数 (デフォルト 2) で、各コマンドのコンソール出力量を決めます。コマンドごとのオプションなので、サブコマンドと一緒に指定します (例: mlmm opt -v 1 ...)。4 段階は全コマンド共通で、各コマンドページはそのコマンド固有の出力だけを説明します。
レベル |
表示内容 |
|---|---|
|
無出力。成功は終了コードと出力成果物で確認します。 |
|
マイルストーンのみ: バージョン、入力要約、主要設定、出力先、dry-run / 最終ステータス。banner・ |
|
デフォルト。banner、 |
|
デバッグ: resolved config / dry-run plan、backend DEBUG、raw optimizer・内部座標の詳細、 |
意味的な失敗はどのレベルでも失敗です。-v 3 でのみ現れる Traceback も実行失敗を意味します。
残基セレクタ¶
残基セレクタは、基質や抽出中心として使用する残基を指定します。
残基名による指定¶
-c 'SAM,GPP' # SAM または GPP という名前の残基をすべて選択
-c 'LIG' # LIG という名前の残基をすべて選択
残基IDによる指定¶
-c '123,456' # 残基 123 と 456
-c 'A:123,B:456' # チェーン A の残基 123、チェーン B の残基 456
-c '123A' # 挿入コード A を持つ残基 123
-c 'A:123A' # チェーン A、残基 123、挿入コード A
PDB ファイルによる指定¶
-c substrate.pdb # 別の PDB から座標を使用して基質を特定
Note
残基名で選択する場合、同名の残基が複数あればすべてが含まれ、警告がログに出力されます。
電荷の指定¶
PDB 入力の場合、--ligand-charge で非標準残基（基質、補因子、金属イオン）の電荷のみを指定します。選択した ML 領域/model system の正味電荷は、標準アミノ酸の電荷、イオン電荷、指定したリガンド電荷を合計して自動算出されるため、ML 領域内の原子を手動で数える必要がありません。
残基別マッピング（推奨）¶
--ligand-charge はコロン（:）区切りを使います（mm-parm は = も受け付けますが、extract/all の ML 領域抽出経路は : のみ対応するため、: を推奨します）:
-l 'SAM:1,GPP:-3' # SAM は +1、GPP は -3
-l 'LIG:-2' # LIG は -2
整数形式（全未知残基へ合計電荷をまとめて割り当て）も使えます:
-l -3 # 全未知残基の合計電荷
残基名の大文字小文字は区別しません。マッピングされていない非標準残基はデフォルトで電荷 0 となります。
ML 領域電荷の明示的上書き¶
-q 0 # ML 領域/model system の正味電荷を 0 に強制
-q -1 # ML 領域/model system の正味電荷を -1 に強制
電荷の解決順序¶
-q/--charge（明示的な CLI 上書き）– 最優先。ML 領域決定の電荷サマリー（アミノ酸、イオン、
--ligand-chargeの合計。-c指定かつ抽出が走る場合のみ）。抽出をスキップした場合の
--ligand-chargeフォールバック（PDB 入力または--ref-pdbが必要）。.gjfの電荷/スピンヘッダ（Gaussian 形式）。このヘッダを読むのはoniom-importのみです（bond-summaryも.gjfのジオメトリを読みますが、最適化/MEP パイプラインは PDB/XYZ を入力とします）。デフォルト: なし（未解決なら中断）。
計算系サブコマンド（scan / scan2d / scan3d / opt / sp / path-opt / path-search / tsopt / freq / irc / dft / oniom-export）では、引き続き -q/--charge の明示指定が必要です。
Tip
非標準の残基（基質、補因子、特殊なリガンド）には必ず --ligand-charge を指定し、正しい電荷伝播を確保してください。
スピン多重度¶
-m 1 # 一重項（デフォルト）
-m 2 # 二重項
-m 3 # 三重項
Note
all と計算系サブコマンドでは -m/--multiplicity を使います。mm-parm の --ligand-mult は残基メタデータ用の別オプションです。
原子セレクタ¶
原子セレクタは、スキャンや拘束に使用する特定の原子を指定します。
整数インデックス（デフォルトは1始まり）¶
--scan-lists '[(1, 5, 2.0)]' # 原子 1 と 5、ターゲット距離 2.0 Å
PDB形式のセレクタ文字列¶
--scan-lists '[("TYR,285,CA", "MMT,309,C10", 2.20)]'
--scan-lists '[("A:TYR:285:CA", "B:MMT:309A:C10", 2.20)]' # chain を含む一意形式
識別子が繰り返される系や mmCIF では、厳密な
CHAIN:RESNAME:RESSEQ[ICODE]:ATOM 形式を優先してください。複数文字 chain
と 10,000 以上の残基番号にも対応し、heuristic matching を避けられます。
セレクタのフィールドは以下で区切れます:
空白:
'TYR 285 CA'カンマ:
'TYR,285,CA'スラッシュ:
'TYR/285/CA'バッククォート:
'TYR`285`CA'バックスラッシュ:
'TYR\285\CA'
3 つのトークン（残基名、残基番号、原子名）は任意の順序で指定できます。パーサーは非標準の順序でもフォールバックヒューリスティックで解釈します。
入力ファイル要件¶
PDB ファイル¶
水素原子を含む必要があります（
reduce、pdb2pqr、mm-parm --add-h等で追加）列 77-78 に元素記号が必要（欠けている場合は
mlmm add-elem-infoを使用）複数の PDB は同じ原子を同じ順序で持つ必要があります（座標のみ異なる）
XYZ ファイル¶
ML 領域決定をスキップする場合（
-c/--centerを省略）に使用可能
Amber トポロジー¶
--parm: 全系の力場トポロジー（mm-parmで自動生成可能）parm7 は入力 PDB の原子順序と正確に一致する必要があります
バックエンド選択¶
ML/MM calculator を使うサブコマンド（opt、sp、tsopt、freq、
irc、scan、scan2d、scan3d、path-opt、path-search、all）で
以下を指定できます:
オプション |
説明 |
デフォルト |
|---|---|---|
|
ML 領域の MLIP バックエンド: |
|
代替バックエンドはオプション依存グループでインストールします:
pip install "mlmm-toolkit[orb]" # ORB バックエンド
pip install "mlmm-toolkit[aimnet]" # AIMNet2 バックエンド
pip uninstall -y fairchem-core && pip install mace-torch # MACE は別 env で（e3nn ピンが UMA と競合）
精度、workers、解析 Hessian¶
--precision を省略した場合、UMA と AIMNet2 は fp32、ORB と MACE は
fp64 を使用します。AIMNet2 は fp64 を受け付けません。ORB/MACE の fp32
明示指定は、曲率の低ノイズ性よりスクリーニング速度を優先する場合に限ります。
--workers は一般的な CPU スレッド数ではなく、UMA の並列 predictor
（fairchem-core[extras]）を制御します。デフォルトは 1 です。
--workers > 1 は解析 Hessian に必要な autograd model を公開しないため、
--hessian-calc-mode Analytical との併用はエラーになります。
--workers 1 --hessian-calc-mode Analytical # 解析 Hessian
--workers 4 --hessian-calc-mode FiniteDifference # UMA 並列 predictor + FD
ORB、MACE、AIMNet2 はこの UMA worker pool を使用しません。互換性のある バックエンド版では 4 種すべてが解析/native Hessian に対応し、必要な API が 無い場合は有限差分へ暗黙に切り替えずエラーになります。
--opt-mode（サブコマンド依存）¶
Warning
選択肢とデフォルトはサブコマンドごとに異なります。
サブコマンド |
勾配のみ別名 |
Hessian ベース別名 |
デフォルト |
エンジン |
|---|---|---|---|---|
|
|
|
|
L-BFGS / RFO（任意で |
|
|
|
|
Dimer / RS-P-RFO（RS-I-RFO / TRIM も明示選択可）。 |
|
|
|
|
TSOPT と IRC 後の端点最適化の fallback。 |
スキャンと path-search は固定の L-BFGS を使い、--opt-mode を受け付けません。
YAML 設定¶
詳細設定は多層 YAML で渡せます。適用順序:
デフォルト < config < CLI オプション
利用可能なすべてのオプションは YAML リファレンス を参照してください。
出力ディレクトリ¶
--out-dir で結果の保存先を指定します:
--out-dir ./my_results/ # カスタム出力ディレクトリ
デフォルトの出力ディレクトリ:
all:./result_all/extract: カレントディレクトリまたは-oで指定mm-parm: カレントディレクトリまたは--out-prefixで指定define-layer: カレントディレクトリまたは-oで指定opt:./result_opt/tsopt:./result_tsopt/path-opt:./result_path_opt/path-search:./result_path_search/scan:./result_scan/scan2d:./result_scan2d/scan3d:./result_scan3d/freq:./result_freq/irc:./result_irc/dft:./result_dft/
関連項目¶
はじめに – インストールと初回実行
概念とワークフロー – ML/MM 3層システム、ONIOM 分解の全体像
典型エラー別レシピ – 症状起点の切り分け
トラブルシューティング – よくあるエラーと対処法
YAML リファレンス – 全設定オプション