scan2d¶
調和拘束と ML/MM 緩和による 2 距離（d1, d2）グリッドスキャンを実行します。2 つの反応距離（例: 結合形成 + 結合切断）に対する 2D ポテンシャル面をマッピングし、1D スキャンでは見落とすサドル点や分岐構造を特定したいときに使用します。mlmm scan2d は --max-step-size を使用して 2 つの結合距離の線形グリッドを構築し、適切な拘束を適用して各グリッド点を緩和し、バイアスなしの ML/MM エネルギーを可視化用に記録します。-s/--scan-lists で YAML/JSON スペックファイル（推奨）またはインライン Python リテラルを使用します。どちらの形式も正確に 2 つのスキャン軸を受け付けます。3D の scan2d_landscape.html には底面に投影した等高線が含まれます。
実行例¶
コマンド形式:
mlmm scan2d -i INPUT.pdb --parm real.parm7 --model-pdb ml_region.pdb \
-q CHARGE [-m MULT] \
[-s scan2d.yaml | -s "[(I1,J1,LOW1,HIGH1),(I2,J2,LOW2,HIGH2)]"] \
[--one-based|--zero-based] [--max-step-size FLOAT] [--bias-k FLOAT] \
[--freeze-atoms "1,3,5"] [--relax-max-cycles INT] [--thresh PRESET] \
[--dump/--no-dump] [--out-dir DIR] \
[--preopt/--no-preopt] [--baseline {min|first}] [--zmin FLOAT] [--zmax FLOAT]
推奨: YAML/JSON spec。
# 推奨: YAML/JSON spec
cat > scan2d.yaml << 'YAML'
one_based: true
pairs:
- [12, 45, 1.30, 3.10]
- [10, 55, 1.20, 3.20]
YAML
mlmm scan2d -i input.pdb --parm real.parm7 --model-pdb ml_region.pdb \
-q 0 -s scan2d.yaml --print-parsed
代替: インライン Python リテラル。
# 代替: インライン Python リテラル
mlmm scan2d -i input.pdb --parm real.parm7 --model-pdb ml_region.pdb \
-q 0 -s "[(12,45,1.30,3.10),(10,55,1.20,3.20)]"
TRJ ダンプ付き LBFGS スキャン、コンタープロットの固定カラースケール。
# TRJ ダンプ付き LBFGS スキャン、コンタープロットの固定カラースケール
mlmm scan2d -i input.pdb --parm real.parm7 --model-pdb ml_region.pdb \
-q 0 -s "[(12,45,1.30,3.10),(10,55,1.20,3.20)]" \
--max-step-size 0.20 --dump -o ./result_scan2d/ --preopt --baseline min \
--zmin 0.0 --zmax 40.0
-s/--scan-lists の解釈結果を確認したい場合は --print-parsed を追加してください。GPU 計算を実行せずに解析されたスキャンスペックを検証して終了します。
処理の流れ¶
入力と事前最適化 – 酵素 PDB を読み込み、電荷/スピンを解決し、ML/MM calculator（MLIP バックエンド + hessian_ff）を構築し、
--preoptの場合は任意でバイアスなし事前最適化を実行。-b/--backendで ML バックエンドを選択（デフォルト:uma）、--embedchargeで xTB 点電荷埋め込み補正を有効化可能。グリッド構築 –
-s/--scan-lists（YAML/JSON スペックファイルまたはインラインリテラル）からターゲットを 2 つの 4 要素タプルに解析し、インデックスを正規化（デフォルト 1 始まりまたは"TYR,285,CA"のような PDB 原子セレクター）。ceil(|high - low| / h) + 1点の線形グリッドを構築（h = --max-step-size）。外側ループ（d1） – 各 d1 値について、d1 拘束のみで系を緩和。
内側ループ（d2） – 現在の d1 での各 d2 値について、最も近い収束済み構造から開始し両方の拘束で緩和。
エネルギー評価 – 各 (i, j) ペアで ML/MM エネルギーをバイアスなしで評価し
surface.csvに記録。可視化 –
scan2d_map.png（2D コンター）とscan2d_landscape.html（3D サーフェス）を書き出し。--zmin/--zmaxでカラースケールをクランプ。ベースライン:--baseline minは最小エネルギーをゼロに;--baseline firstは (i=0, j=0) グリッド点をゼロに。
出力¶
まず surface.csv（PES グリッド）、scan2d_map.png（2D コンター）、scan2d_landscape.html（3D ランドスケープ）を確認してください。グリッド点ごとのジオメトリは grid/ 配下に出力されます（ファイル名タグ i### / j### は Å の 100 分の 1 の整数で、ステップ番号ではありません）。
out_dir/ (デフォルト:./result_scan2d/)
├── surface.csv # PES グリッド: i, j, d1_A, d2_A, energy_hartree, bias_converged, is_preopt, energy_kcal, d1_label, d2_label
├── scan2d_map.png # 2D コンターマップ
├── scan2d_landscape.html # 3D サーフェス可視化（Plotly）
├── grid/
│ ├── point_i###_j###.xyz # 各 (i, j) ペアの緩和ジオメトリ
│ ├── point_i###_j###.pdb # 対応する PDB（入力が PDB の場合）
│ ├── preopt_i###_j###.xyz # 基準/事前最適化構造（基準距離が有限なら常に出力）
│ └── inner_path_d1_###_trj.xyz # d1 スライスごとの内側 d2 軌跡（--dump 時）
└── (stdout) # 進捗とエネルギーサマリー
CLI オプション¶
フラグの全リストは生成されたコマンドリファレンスにあります。手作業で重複させないでください。以下の表は説明が必要なオプションを扱います。
オプション |
説明 |
デフォルト |
|---|---|---|
|
入力酵素複合体 PDB（必須）。 |
必須 |
|
酵素の Amber parm7 トポロジー（必須）。 |
必須 |
|
ML 領域を定義する PDB。 |
None |
|
ML 領域のカンマ区切り原子インデックス（範囲指定可）。 |
None |
|
|
|
|
入力 PDB の B 因子から ML/MM レイヤーを検出。 |
|
|
ML 領域の総電荷。 |
None（ |
|
残基ごとの電荷マッピング（例: |
None |
|
スピン多重度 (2S+1)。 |
|
|
凍結する 1 始まりカンマ区切りインデックス。 |
None |
|
ML 領域からの距離カットオフ (Å) — Hessian計算に含める MM 原子を指定。 |
None |
|
ML 領域からの可動 MM 原子の距離カットオフ (Å)。指定すると |
None |
|
スキャンターゲット: YAML/JSON スペックファイルパス（自動検出、 |
必須 |
|
|
|
|
|
|
|
ステップごとの最大距離増分 (Å)。グリッド密度を決定。 |
|
|
調和拘束ポテンシャル強度 k (eV/Ų)。 |
|
|
バイアス緩和ごとの最大 LBFGS サイクル。 |
|
|
d1 スライスごとの内側 d2 スキャン TRJ を書き出し。 |
|
|
基本出力ディレクトリ。 |
|
|
収束プリセット（ |
|
|
ベース YAML 設定ファイル（最初に適用）。 |
None |
|
|
None |
|
スキャン前にバイアスなし事前最適化を実行。 |
|
|
相対エネルギーの基準（kcal/mol）。 |
|
|
コンターカラースケールの下限（kcal/mol）。 |
自動スケール |
|
コンターカラースケールの上限（kcal/mol）。 |
自動スケール |
|
ML 領域の MLIP バックエンド: |
|
|
xTB 点電荷埋め込み補正（実験的機能）の有効化。MM 環境から ML 領域への静電的影響を考慮。 |
|
|
xTB 埋め込み用 MM 原子のカットオフ半径（Å）。 |
|
|
model parm7 に CMAP（骨格クロスマップ二面角補正）を含めるかどうか。デフォルト: 無効（Gaussian ONIOM と同一）。 |
|
|
MM バックエンド（解析的Hessian vs OpenMM 有限差分）。 |
|
|
リンク原子の配置: scaled（$g$ ファクター）または fixed（固定 1.09/1.01 Å）。 |
|
|
機械可読な |
|
|
PDB テンプレート利用可能時の XYZ/TRJ から対応する PDB の生成を切り替え。 |
|
スキャンスペックフォーマット¶
YAML/JSON スペックフォーマット（推奨）¶
-s/--scan-lists は YAML/JSON ファイルを自動検出します。ファイルパスを渡すとスペックモードになります:
one_based: true # 任意; デフォルトは CLI の --one-based/--zero-based
pairs:
- [12, 45, 1.30, 3.10]
- [10, 55, 1.20, 3.20]
pairsは必須で、ちょうど 2 つの 4 要素タプルを含む必要があります。各 4 要素タプルは
(i, j, low_A, high_A)です。インデックスは整数または PDB セレクター（インラインリテラルと同じ）が使用可能です。
インラインリテラルフォーマット¶
-s/--scan-lists がファイルパスでない値を受け取ると、単一の Python リテラル文字列として評価されます。シェルクォートに注意してください。
リテラルは正確に 2 つの 4 要素タプル (atom1, atom2, low_A, high_A) の Python リストです:
-s '[(atom1, atom2, low_A, high_A), (atom3, atom4, low_A, high_A)]'
シェルが括弧やスペースを解釈しないよう、リテラル全体をシングルクォートで囲んでください。
各 4 要素タプルは 1 つのスキャン軸を定義します:
atom1–atom2間の距離をlow_Aからhigh_Aまでスキャンします。scanと異なり、1 つのリテラルのみ受け付けます（マルチステージ非対応）。
原子は整数インデックスまたは PDB セレクター文字列で指定できます:
方法 |
例 |
備考 |
|---|---|---|
整数インデックス |
|
デフォルトは 1 始まり（ |
PDB セレクター |
|
残基名、残基番号、原子名 |
PDB セレクターのトークンは、カンマ ,、スペース、スラッシュ /、バッククォート `、バックスラッシュ \ のいずれかで区切れます。トークンの順序は自由です。
# 以下はすべて同じ原子を指定:
"TYR,285,CA"
"TYR 285 CA"
"TYR/285/CA"
"285,TYR,CA" # 順序は自由
クォート規則:
# 正しい: リスト全体をシングルクォート、内側のセレクター文字列をダブルクォート
-s '[("TYR,285,CA","MMT,309,C10",1.30,3.10),("TYR,285,CB","MMT,309,C11",1.20,3.20)]'
# 正しい: 整数インデックスは内側のクォート不要
-s '[(1, 5, 1.30, 3.10), (2, 8, 1.20, 3.20)]'
# 非推奨: 外側をダブルクォートにすると内側のクォートをエスケープする必要あり
-s "[(\"TYR,285,CA\",\"MMT,309,C10\",1.30,3.10),...]"
YAML 設定¶
geom:
coord_type: cart
freeze_atoms: []
calc:
charge: 0
spin: 1
mlmm:
real_parm7: real.parm7
model_pdb: ml_region.pdb
opt:
thresh: baker
max_cycles: 10000
dump: false
out_dir: ./result_scan2d/
lbfgs:
max_step: 0.3
out_dir: ./result_scan2d/
bias:
k: 300.0
全スキーマ（すべてのキーとデフォルト）: YAML リファレンス。