CLI 規約

このページでは、mlmm-toolkit の全コマンドで使用される規約を説明します。

ブール値オプション

すべてのブール値 CLI フラグは 4 つの記法を受け付けます。

記法

例

肯定フラグ

--tsopt

否定フラグ

--no-tsopt

肯定の値指定

--tsopt True、--tsopt yes、--tsopt 1、--tsopt on

否定の値指定

--tsopt False、--tsopt no、--tsopt 0、--tsopt off

 
--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 で検出されます。

新しいブールフラグの追加

サブコマンドにブールフラグを追加する際は、必ず mlmm/cli/common_options.py の add_*_option() ファクトリ経由とし、長い名前を mlmm/cli/app.py の対応する _COMMAND_BOOL_*_OPTIONS テーブルに登録してください。サブコマンド本体に @click.option("--foo/--no-foo", ...) や type=click.BOOL を直接書くと、レジストリを迂回してテスト対象から外れ、値指定記法が警告なく失われます。

よく使うブール値オプション:

  • --tsopt, --thermo, --dft – 後処理ステージの有効化

  • --dump – 軌跡ファイルの出力

  • --preopt, --endopt – 前処理/後処理最適化の切り替え

  • --climb – MEP 探索でクライミングイメージを有効化

Progressive Help (all)

mlmm 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 を除く）では、以下の 2 つのオプションが必要です:

--parm real.parm7      # 全系（real system）の Amber parm7 トポロジーファイル
--model-pdb model.pdb  # ML 領域（model system）を定義する PDB ファイル

all ワークフローでは、mm-parm と define-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 にマッピングされます。

層の定義方法

  1. define-layer サブコマンド（推奨）:

    mlmm define-layer -i system.pdb --model-pdb ml_region.pdb -o labeled.pdb

  2. 距離カットオフ（YAML/CLI）:

    calc:
 hess_cutoff: 3.6       # Hessian 対象 MM の距離カットオフ
 movable_cutoff: 8.0    # Movable-MM の距離カットオフ（それ以外は Frozen）

  3. B-factor からの読み取り:

    calc:
 use_bfactor_layers: true   # 入力 PDB の B-factor から層を読み取り

  4. 明示的インデックス指定（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 段階は全コマンド共通で、各コマンドページはそのコマンド固有の出力だけを説明します。

レベル

表示内容

-v 0

無出力。成功は終了コードと出力成果物で確認します。

-v 1

マイルストーンのみ: バージョン、入力要約、主要設定、出力先、dry-run / 最終ステータス。banner・[command]・[mode]・config dump は出ません。

-v 2

デフォルト。banner、[command]、[mode]、ステージ進捗、主要な optimizer サイクル表、終了ステータス、Hessian 1 行要約、thermo / DFT 要約、経過時間を追加します。

-v 3

デバッグ: resolved config / dry-run plan、backend DEBUG、raw optimizer・内部座標の詳細、[HessianTiming]、[HessianVRAM]。

意味的な失敗はどのレベルでも失敗です。-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 で非標準残基（基質、補因子、金属イオン）の電荷のみを指定します。総系電荷は、標準アミノ酸の電荷、イオン電荷、指定したリガンド電荷を合計して自動算出されるため、複合体全体の原子を手動で数える必要がありません。これは、総電荷が一目でわからない大規模な酵素-基質系で特に有用です。

残基別マッピング（推奨）

--ligand-charge はコロン（:）またはイコール（=）の両方をサポートします:

-l 'SAM:1,GPP:-3'   # SAM は +1、GPP は -3
-l 'SAM=1,GPP=-3'   # 同じ意味（= 区切り）
-l 'LIG:-2'         # LIG は -2

整数形式（全未知残基へ合計電荷をまとめて割り当て）も使えます:

-l -3   # 全未知残基の合計電荷

残基名の大文字小文字は区別しません。マッピングされていない非標準残基はデフォルトで電荷 0 となります。

総電荷の明示的上書き

-q 0    # 総系電荷を 0 に強制
-q -1   # 総系電荷を -1 に強制

電荷の解決順序

  1. -q/--charge（明示的な CLI 上書き）– 最優先。

  2. ML 領域決定の電荷サマリー（アミノ酸、イオン、--ligand-charge の合計。-c 指定かつ抽出が走る場合のみ）。

  3. 抽出をスキップした場合の --ligand-charge フォールバック（PDB 入力または --ref-pdb が必要）。

  4. .gjf の電荷/スピンヘッダ（Gaussian 形式）。このヘッダを読むのは oniom-import のみです（bond-summary も .gjf のジオメトリを読みますが、最適化/MEP パイプラインは PDB/XYZ を入力とします）。

  5. デフォルト: なし（未解決なら中断）。

計算系サブコマンド（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)]'

セレクタのフィールドは以下で区切れます:

  • 空白: '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 の原子順序と正確に一致する必要があります

バックエンド選択

すべての計算系サブコマンド（opt、sp、tsopt、freq、irc、dft、scan、scan2d、scan3d、path-opt、path-search、all）で以下を指定できます:

オプション

説明

デフォルト

-b, --backend

ML 領域の MLIP バックエンド: uma、orb、mace、aimnet2

uma

--embedcharge/--no-embedcharge

xTB 点電荷埋め込み補正の有効化

--no-embedcharge

代替バックエンドはオプション依存グループでインストールします:

pip install "mlmm-toolkit[orb]"       # ORB バックエンド
pip install "mlmm-toolkit[aimnet]"   # AIMNet2 バックエンド
pip install --no-deps mace-torch      # MACE バックエンド

--opt-mode（サブコマンド依存）

Warning

選択肢とデフォルトはサブコマンドごとに異なります。

サブコマンド

勾配のみ別名

Hessian ベース別名

デフォルト

エンジン

opt

grad（light, lbfgs）

hess（heavy, rfo）

grad

L-BFGS / RFO（任意で --microiter）。

tsopt

grad（light, dimer）

hess（heavy, rsirfo）

hess

Dimer / RS-I-RFO。

path-search

grad（= L-BFGS）

—（hess / rfo は未配線で Click エラー）

grad

GSM / DMF ノードの内部ストリングオプティマイザ。path-opt には --opt-mode がなく、--mep-mode gsm/dmf を使います。

scan

grad（lbfgs/light）

—

—

--opt-mode は L-BFGS の互換別名としてのみ受理され、それ以外のグリッド緩和は YAML の内部オプティマイザに従う。

scan2d / scan3d

—

—

—

--opt-mode なし。緩和は YAML の内部オプティマイザを使用。

light / heavy は grad / hess の別名として受理されますが、新しいスクリプトでは grad / hess を推奨します。

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/

関連項目