scan2d¶
calculator は選択した MM backend（デフォルト hessian_ff、または OpenMM）を使います。
調和拘束と ML/MM 緩和による 2 距離（d1, d2）グリッドスキャンを実行します。2 つの反応距離（例: 結合形成 + 結合切断）に対する 2D ポテンシャル面をマッピングし、後続のTS最適化に用いる鞍点候補領域や分岐構造を調べます。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 ダンプ付き L-BFGS スキャン、コンタープロットの固定カラースケール。
# TRJ ダンプ付き L-BFGS スキャン、コンタープロットの固定カラースケール
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/mmCIF、または
--ref-pdbを伴う XYZ を読み込み、電荷/スピンを解決し、ML/MM calculator（MLIP バックエンド + hessian_ff）を構築し、--preoptの場合は任意でバイアスなし事前最適化を実行。-b/--backendで ML バックエンドを選択します（デフォルト:uma）。グリッド構築 –
-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に記録。開始／事前最適化構造は常にi = j = -1、is_preopt = trueの参照行として表に残す。可視化 –
-1の参照行を基準エネルギー、補間、plot から除外し、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 ランドスケープ）は、有限かつ収束した一意な非共線点が 3 点以上ある場合だけ生成されます。条件を満たさない場合は surface.csv を保持して診断付きで終了します。グリッド点ごとのジオメトリは 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 # --convert-files と PDB テンプレートがある場合
│ ├── preopt_i###_j###.xyz # 基準/事前最適化構造（基準距離が有限なら常に出力）
│ └── inner_path_d1_###_trj.xyz # d1 スライスごとの内側 d2 軌跡（--dump 時）
└── (stdout) # 進捗とエネルギーサマリー
CLI オプション¶
フラグの全リストは生成されたコマンドリファレンスにあります。手作業で重複させないでください。以下の表は説明が必要なオプションを扱います。
オプション |
説明 |
デフォルト |
|---|---|---|
|
入力 PDB/mmCIF、または |
必須 |
|
酵素の Amber parm7 トポロジー（必須）。 |
必須 |
|
ML 領域を定義する PDB。 |
None |
|
ML 領域のカンマ区切り原子インデックス（範囲指定可）。 |
None |
|
|
|
|
入力 PDB の B 因子から ML/MM レイヤーを自動検出。 |
有効 |
|
ML 領域の総電荷。 |
None（ |
|
残基ごとの電荷マッピング（例: |
None |
|
スピン多重度 (2S+1)。 |
|
|
凍結する 1 始まりカンマ区切りインデックス。 |
None |
|
ML 領域からの可動 MM 原子の距離カットオフ (Å)。指定すると |
None |
|
スキャンターゲット: YAML/JSON スペックファイルパス（自動検出、 |
必須 |
|
|
|
|
|
|
|
ステップごとの最大距離増分 (Å)。グリッド密度を決定。 |
|
|
調和拘束ポテンシャル強度 k (eV/Ų)。 |
|
|
バイアス緩和ごとの L-BFGS サイクル上限。 |
|
|
d1 スライスごとの内側 d2 スキャン TRJ を書き出し。 |
|
|
基本出力ディレクトリ。 |
|
|
収束プリセット（ |
|
|
ベース YAML 設定ファイル（最初に適用）。 |
None |
|
|
None |
|
スキャン前にバイアスなし事前最適化を実行。 |
|
|
相対エネルギーの基準（kcal/mol）。 |
|
|
コンターカラースケールの下限（kcal/mol）。 |
自動スケール |
|
コンターカラースケールの上限（kcal/mol）。 |
自動スケール |
|
ML 領域の MLIP バックエンド: |
|
|
REAL と MODEL の両 MM 層で CMAP を保持します。 |
|
|
MM バックエンド。Hessian 構築法は |
|
|
リンク原子の配置: 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:
model_charge: 0
model_mult: 1
real_parm7: real.parm7
model_pdb: ml_region.pdb
opt:
thresh: baker
# max_cycles: 100000 # 任意の有限上限
lbfgs:
max_step: 0.3
bias:
k: 300.0
軌跡保存と出力先は CLI が所有する --dump と --out-dir を使います。
全スキーマ（すべてのキーとデフォルト）: YAML リファレンス。