scan2d¶
調和拘束と MLIP 緩和により、2 距離 (d₁, d₂) のグリッドスキャンを行い、(d₁, d₂) 上の 2D ポテンシャル面を得ます。TS 領域の特定や、MEP 精密化前の反応ランドスケープの可視化に使います。scan2d は --max-step-size に基づいて両軸の線形グリッドを作成し、各格子点を対応する拘束付きで緩和して、可視化用にバイアスなしの MLIP エネルギーを記録します。入力は 1 つの構造 + -s/--scan-lists scan2d.yaml（推奨）、またはちょうど 2 つの 4 要素タプルを含む -s/--scan-lists の 単一 インラインリテラルです。デフォルトのバックエンドは UMA で、-b/--backend で他のバックエンドも選択できます。L-BFGS の代わりに RFOptimizer を使う場合は --opt-mode hess を指定してください。
XYZ/GJF 入力では、--ref-pdb で参照 PDB/mmCIF トポロジーを指定すると、XYZ 座標を保持したまま PDB/CIF/GJF companion を生成できます。
実行例¶
YAML スペックファイルを使った最小実行:
pdb2reaction scan2d -i input.pdb -q 0 -s scan2d.yaml -o ./result_scan2d/
コマンド形式:
pdb2reaction scan2d -i INPUT.{pdb|xyz|trj|...} [-q CHARGE] [-l, --ligand-charge <number|'RES:Q,...'>] [-m MULT] \
[-b/--backend uma|orb|mace|aimnet2] \
[-s/--scan-lists scan2d.yaml | '[(i,j,lowÅ,highÅ), (i,j,lowÅ,highÅ)]'] [options] \
[--convert-files/--no-convert-files] [--ref-pdb FILE]
推奨: YAML/JSON スペックファイル:
cat > scan2d.yaml << 'YAML'
one_based: true
pairs:
- ["TYR,285,CA", "SAM,309,C10", 1.30, 3.10]
- ["TYR,285,CB", "SAM,309,C11", 1.20, 3.20]
YAML
pdb2reaction scan2d -i input.pdb -q 0 -s scan2d.yaml
代替: インライン Python リテラル:
pdb2reaction scan2d -i input.pdb -q 0 \
-s '[("TYR,285,CA","SAM,309,C10",1.30,3.10),("TYR,285,CB","SAM,309,C11",1.20,3.20)]'
L-BFGS、内側軌跡ダンプ、Plotly 出力:
pdb2reaction scan2d -i input.pdb -q 0 \
-s '[("TYR,285,CA","SAM,309,C10",1.30,3.10),("TYR,285,CB","SAM,309,C11",1.20,3.20)]' \
--max-step-size 0.20 --dump -o ./result_scan2d/ --opt-mode grad \
--preopt --baseline min
スキャンリスト仕様¶
scan2d はちょうど 2 つの4 要素タプル (i, j, low_Å, high_Å) を受け付けます（YAML/JSON では pairs キー、インラインでは単一リテラル）。scan と異なり、リテラルは 1 つだけを受け付けます（複数ステージは非対応）。
YAML/JSON ファイル書式、インライン Python リテラル構文、原子セレクタ、クォート規則については CLI 規約: スキャンリスト仕様 を参照してください。
処理の流れ¶
geom_loaderで入力構造をロードし、電荷とスピンを解決します。--preoptの場合は無バイアスの事前最適化を実行します。-qが省略され--ligand-chargeがある場合、構造は酵素–基質複合体として扱われ、PDB/mmCIF 入力（または--ref-pdb付き XYZ/GJF）ではextract.pyの電荷サマリーから総電荷を導出します。開始構造（有効時は事前最適化後）はgrid/preopt_iDDD_jDDD.*（DDD = round(d × 100)Å）に保存され、surface.csvには常にi = j = -1のエントリとしてバイアスなしエネルギーが記録されます。-s/--scan-listsを2つの4要素tupleへ解析します。3-field selectorは順不同で、重複する残基名／番号には位置固定CHAIN:RESNAME:RESSEQ[ICODE]:ATOMを使います。線形gridはceil(|high − low| / h) + 1点（両端を含む）です。外側ループで
d1[i]（近い順）を走査します。各値で d₁ 拘束のみを適用して緩和し、その構造をスナップショットとして保存します。次に内側ループでd2[j]を走査し、d₁ と d₂ の両拘束を適用して、最も近い既収束構造から緩和を開始します。各
(i, j)について、<out-dir>/grid/point_iDDD_jDDD.xyz（DDD = round(d × 100)Å。例d1=1.30 Å, d2=3.10 Å→point_i130_j310.xyz）に構造を保存し、バイアス収束の可否を記録し、バイアスを除去した MLIP エネルギーを評価します。丸め後のタグが別の点と重なる場合、後のファイル名には 0 始まりの格子 index_grid_III_JJJが付きます。--dumpの場合、外側ループごとの内側軌跡がinner_path_d1_###_trj.xyz（###は外側ステップ index）として保存されます。すべての点を走査したら、
i,j,d1_A,d2_A,energy_hartree,bias_converged,is_preopt,energy_kcal,d1_label,d2_labelの列を持つ<out-dir>/surface.csvを作成します。参照行は常にi = j = -1、is_preopt = trueとして表に残しますが、基準エネルギー、補間、plot からは除外します。--baseline {min|first}で kcal/mol の基準をシフトします。--baseline firstは再並べ替え後の最初の eligible 格子点（i = j = 0）を使い、その点が対象外なら eligible point の最小値へ fallback します。eligible point が少なくとも 3 つあり、重複せず非共線の場合だけ、scan2d_map.png（2D contour）とscan2d_landscape.html（3D surface）を生成します。条件を満たさない場合もsurface.csvは残り、plot は生成せず正常に扱います。--zmin/--zmaxでカラースケールを固定できます。
出力¶
実行後は surface.csv、grid/ 配下の各点の構造、scan2d_map.png / scan2d_landscape.html のプロットを確認してください。
result_scan2d/surface.csvresult_scan2d/grid/point_iDDD_jDDD.xyz(DDD = round(d × 100)Å。例:d1=1.30 Å, d2=3.10 Å→point_i130_j310.xyz)result_scan2d/scan2d_map.pngとresult_scan2d/scan2d_landscape.html
out_dir/ (デフォルト:./result_scan2d/)
├─ surface.csv # 構造化グリッド表
├─ scan2d_map.png # 2D コンター（Kaleido 必須; PNG 出力に失敗すると実行が停止）
├─ scan2d_landscape.html # 3D サーフェス可視化
├─ grid/point_iDDD_jDDD.xyz # DDD = round(d × 100) Å (例: d1=1.30 Å, d2=3.10 Å → point_i130_j310.xyz)
├─ grid/point_iDDD_jDDD.pdb # 変換有効時に対応する PDB
├─ grid/point_iDDD_jDDD.cif # bridge入力。元IDを復元
├─ grid/point_iDDD_jDDD.gjf # テンプレートがある場合に対応する Gaussian
├─ grid/preopt_iDDD_jDDD.xyz # 開始構造（有効時は事前最適化後）、DDD = round(d × 100)
├─ grid/preopt_iDDD_jDDD.pdb # 変換有効時に対応する PDB
├─ grid/preopt_iDDD_jDDD.cif # bridge入力
├─ grid/preopt_iDDD_jDDD.gjf # テンプレートがある場合に対応する Gaussian
└─ grid/inner_path_d1_###_trj.xyz # --dump の場合のみ（参照トポロジーと変換があれば PDB/CIF companion も生成）
CLI オプション¶
オプション |
説明 |
デフォルト |
|---|---|---|
|
|
必須 |
|
総電荷（CLI > テンプレート/ |
テンプレート/導出がない場合は必須 |
|
単一の整数（例: |
None |
|
UMA 予測器の並列度（ |
|
|
スピン多重度 2S+1。 |
|
|
スキャンターゲット: YAML/JSON スペックファイルパス（推奨）または 単一のインライン Python リテラルで 2 つの4 要素タプル |
必須 |
|
|
|
|
|
|
|
各距離の 1 増分あたりの最大変化量（Å）。グリッド密度を決定 |
|
|
調和バイアス強度 |
|
|
各バイアス緩和の最大最適化サイクル数。明示値は YAML |
|
|
|
|
|
PDB/mmCIF トポロジー入力時にキャップ水素の親原子を凍結 |
|
|
凍結する原子の 1 始まりインデックスをカンマ区切りで明示的に指定（例: |
None |
|
外側ループごとの |
|
|
入力トポロジー／テンプレートに応じた XYZ/TRJ → PDB/CIF/GJF companion 生成を切り替え |
|
|
XYZ/GJF 入力時の参照 PDB/mmCIF トポロジー（XYZ 座標を保持） |
None |
|
出力ディレクトリ |
|
|
収束プリセットの上書き（ |
|
|
ベース YAML 設定ファイル（最初に適用） |
None |
|
MLIP バックエンド |
|
|
スキャン前に無バイアス最適化を実行 |
|
|
kcal/mol の基準をグローバル最小値または最初の格子点に設定 |
|
|
カラースケールの下限/上限（kcal/mol） |
自動 |
|
|
|
YAML 設定¶
geom:
coord_type: cart # coordinate type: cartesian vs dlc internals
freeze_atoms: [] # 1-based frozen atoms merged with CLI/link detection
calc:
charge: 0 # total charge (CLI/template override)
spin: 1 # spin multiplicity 2S+1
model: uma-s-1p2 # uma-s-1p2 | uma-m-1p1
device: auto # MLIP device selection
opt:
thresh: baker # convergence preset (default: baker)
max_cycles: 100000 # optimizer cycle cap
dump: false # optimizer dumps (scan trajectories are controlled by --dump)
lbfgs:
max_step: 0.3 # maximum step length
rfo:
trust_radius: 0.10 # trust-region radius
bias:
k: 300.0 # harmonic bias strength (eV·Å⁻²)
共有 YAML セクション¶
geom,calc,opt,lbfgs,rfo: YAML リファレンス と同じキーを使用しますが、run-scoped のopt.dumpと optimizerout_dirは無視されます。スキャン軌跡は--dump、出力先は command-owned の-o/--out-dirで制御します。
opt の詳細は YAML リファレンス を参照してください。
注意事項¶
計算エンジンは MLIP バックエンド（デフォルト: UMA、
-b/--backendで切替可能）で、scanコマンドと同じHarmonicBiasCalculatorを再利用します。Å 単位の制限値は内部で Bohr に変換され、L-BFGS ステップや RFO 信頼半径の制御に使われます。最適化の一時ファイルはテンポラリディレクトリに配置されます。
バイアスはエネルギー記録前に除去されるため、
surface.csvを下流のフィッティングや可視化スクリプトにそのまま利用できます。--freeze-linksはユーザー指定のfreeze_atomsにキャップ水素親原子をマージし、抽出された活性部位モデルの境界を固定します。明示した
--relax-max-cyclesは YAMLopt.max_cyclesを上書きします。省略時は YAML が優先され、いずれもなければデフォルト100000です。