`scan2d`（2 次元の拘束付きグリッドスキャン）¶

scan2d サブコマンドは、2 つの座標の格子の各点を調和拘束で保って緩和し、拘束を外したエネルギーを記録して、反応の 2D エネルギーマップを作ります。

主な用途¶

TS 領域の見当づけ: 経路探索や TS 最適化の前に、反応物側と生成物側の谷を結ぶ鞍点がどのあたりにあるかを調べる
MEP の前の地形の確認: 最小エネルギー経路（MEP）を精密化する前に、結合形成とプロトン移動のような 2 つの変化が同時に起きるか、順に起きるかを確かめる

計算バックエンドにはデフォルトの UMA（Meta）のほか、-b/--backend オプションで ORB、MACE、AIMNet2、DFT（dft）も選択可能です。1 つ以上の座標を動かして 1 本の経路を作るには scan を、3 つの座標の格子には scan3d を使います。

基本的な実行例¶

例の input.pdb は、同梱の酵素構造から extract で切り出したクラスターモデルで、電荷は -l 'SAM:1,GPP:-3' から求めます。

pdb2reaction extract -i examples/1.R.pdb -c 'SAM,GPP,MG' -l 'SAM:1,GPP:-3' -o input.pdb

この PDB は chain の欄が空なので、原子は残基名・残基番号・原子名の 3 項目を任意の順序で、カンマか空白で区切って書きます。

1. YAML スペックファイルからの実行¶

2 つの範囲を pairs: に書きます。デフォルトの刻み幅 0.2 Å では、このファイルから 9 × 9 の格子ができます。

# scan2d.yaml
pairs:
  - ["SAM,320,CS1", "GPP,321,C7", 1.50, 3.00]
  - ["GPP,321,H11", "GLU,186,OE2", 0.90, 2.50]

構造・電荷と、このファイルを渡します。--out-json を付けると result.json も出力します。

pdb2reaction scan2d -i input.pdb -l 'SAM:1,GPP:-3' -m 1 -s scan2d.yaml --out-json -o ./result_scan2d/

等高線図は result_scan2d/scan2d_map.png、3D 曲面は scan2d_landscape.html で確認できます。result.json には scientific_status と使える点の数が入ります。

2. インラインリテラルでの指定¶

同じ 2 つの範囲を、1 つのリテラルとしてコマンドラインに書けます。

pdb2reaction scan2d -i input.pdb -l 'SAM:1,GPP:-3' \
    -s '[("SAM,320,CS1","GPP,321,C7",1.50,3.00),("GPP,321,H11","GLU,186,OE2",0.90,2.50)]'

3. 事前最適化・軌跡の保存¶

スキャンの前に入力構造を最適化し、内側ループの軌跡を保存します。

pdb2reaction scan2d -i input.pdb -l 'SAM:1,GPP:-3' \
    -s '[("SAM,320,CS1","GPP,321,C7",1.50,3.00),("GPP,321,H11","GLU,186,OE2",0.90,2.50)]' \
    --dump -o ./result_scan2d/ --preopt

処理の仕組みと計算仕様¶

開始構造と格子: 電荷は -q または -l から決まります。--preopt を付けると、まず拘束なしで入力構造を最適化します。収束しなかった場合は入力構造を使います。各軸には両端を含めて ceil(|high − low| / h) + 1 個の等間隔の値ができます。h は距離では --max-step-size（Å）、角度と二面角では --max-angle-step-size と --max-dihedral-step-size（度）です。値は開始構造に近いものから順に計算します。
外側と内側のループ: d₁ の各値で、d₁ の拘束だけをかけて構造を緩和します。続く内側ループで、両方の拘束をかけて d₂ を走査します。各点は、すでに収束した点のうち最も近いものから始めます。
各点の緩和: 調和拘束 E = ½ k (q − q_target)² が各座標 q を目標値に保ち（k は --restraint-k）、残りの構造を --opt-mode grad（デフォルト）では L-BFGS、hess では RFO で緩和します。そのあと拘束を外してエネルギーを計算し、構造を grid/ に書き出します。
表と図: 最後の点のあと、全点を surface.csv にまとめます。使える点を 50 × 50 の格子上で動径基底関数（RBF）で補間し、等高線図と 3D 曲面を描きます。

surface.csv の読み方と判定¶

surface.csv には格子点ごとの行と、基準の行が 1 つ入ります。

列	内容
`i`, `j`	格子の番号。開始構造に最も近い値が 0 なので、値の昇順ではなく計算した順の番号
`d1_A`, `d2_A`（`q1`, `q2` も同じ値）	緩和の後に測った座標の値。どの軸でも列名は `_A` のままで、角度の軸には度が入る。単位は `q1_unit`, `q2_unit`（`angstrom` か `degree`）
`target_d1_A`, `target_d2_A`（`target_q1`, `target_q2` も同じ値）	その点の拘束の目標値
`energy_hartree`	拘束を外したエネルギー（Hartree）
`energy_kcal`	基準からの相対エネルギー（kcal/mol）
`bias_converged`	拘束付きの緩和が収束したか
`is_preopt`	基準の行だけ `true`
`d1_label`, `d2_label`	図に使う軸の名前

使える点: 緩和が収束し、エネルギーが有限で、構造ファイルが書けた点を「使える点」とします。エネルギーの基準と図には、使える点だけを使います。
判定: result.json（--out-json）の scientific_status は、すべての格子点が使える点なら success、一部だけなら partial（終了コード 0）、1 つも無ければ failed（終了コード 1）です。点の数は n_points_attempted と n_points_usable に入ります。収束しない点については max_cycles とプラトー停止を参照してください。
次の段階: 図は補間なので、鞍点に近い計算点の構造 grid/point_*.pdb を tsopt に渡します。.xyz を渡すときは --ref-pdb も付けます。2 つの谷の点は path-search の入力にできます。

主な出力ファイル¶

--out-dir に次のファイルを書きます。

result_scan2d/
├─ surface.csv                   # 基準の行を含む格子の表
├─ scan2d_map.png                # 2D 等高線図
├─ scan2d_landscape.html         # 3D 曲面（ブラウザで開く）
├─ grid/
│  ├─ point_i150_j090.xyz        # 各格子点の緩和後の構造
│  ├─ preopt_iDDD_jDDD.xyz       # 開始構造（基準の行）
│  └─ inner_path_d1_000_trj.xyz  # d₁ の値ごとの内側ループの軌跡（--dump 指定時）
└─ result.json                   # 結果の要約（--out-json 指定時）。summary.json も同じ内容

まず surface.csv と 2 つの図を確認し、各点の構造は grid/ を見てください。result.json の grid_points[] には、各格子点の番号・値・目標値・エネルギー・収束の可否・構造ファイルが入ります。ファイル名から値を読み取らずに、この対応を使ってください。

ファイル名: i・j の後の数字（タグ DDD）は目標値の 100 倍（Å、角度では度）を 3 桁以上に 0 で埋めた数で、surface.csv の格子の番号ではありません。d1 = 1.50 Å, d2 = 0.90 Å なら point_i150_j090.xyz、角度 120° なら 12000 です。丸めたタグが別の点と重なると、後のファイル名にはその点の surface.csv の i・j を使った _grid_III_JJJ が付きます。
ほかの形式: PDB・mmCIF 入力では各構造を .pdb でも、Gaussian 入力では .gjf でも書きます。mmCIF の入力では、元の識別子を保った .cif も書きます。

主な CLI オプション¶

オプション	引数の型	デフォルト	説明
`-i, --input`	パス	（必須）	入力構造ファイル（`.pdb`, `.cif`, `.mmcif`, `.xyz` 等）
`-q, --charge`	整数	`None`	系全体の総電荷。`-l`、YAML の `calc.charge`、`.gjf` 入力のどれも無ければ必須
`-m, --multiplicity`	整数	`1`	スピン多重度（2S+1）
`-l, --ligand-charge`	文字列	`None`	リガンドの総電荷（例: `-1`）または残基名ごとの電荷（例: `'GPP:-3,SAM:1'`）。`-q` を省いたときに使用（PDB/mmCIF 入力または `--ref-pdb`）
`-s, --scan-lists`	文字列	（必須）	YAML/JSON スペックファイルまたは 1 つのインラインリテラルで 2 つの範囲を指定。距離 `(i,j,low,high)`、角度 `(i,j,k,low,high)`、二面角 `(i,j,k,l,low,high)`
`-o, --out-dir`	パス	`./result_scan2d/`	出力先ディレクトリ
`--max-step-size`	浮動小数点数	`0.2`	距離の軸の格子間隔の上限（Å）
`--max-angle-step-size`	浮動小数点数	`5.0`	角度の軸の格子間隔の上限（度）
`--max-dihedral-step-size`	浮動小数点数	`10.0`	二面角の軸の格子間隔の上限（度）
`--restraint-k`	浮動小数点数	`300.0`	拘束の強さ k（距離は eV/Å²、角度は eV/rad²）。別名 `--bias-k`
`--preopt/--no-preopt`	フラグ	`False`	スキャンの前に入力構造を拘束なしで最適化
`--opt-mode`	`grad` / `hess`	`grad`	各点の緩和の方法：L-BFGS / RFO
`--dump/--no-dump`	フラグ	`False`	d₁ の値ごとの内側ループの軌跡を `grid/` に出力
`--baseline`	`min` / `first`	`min`	`energy_kcal` の 0 点：使える点の最小値、または点 `(0, 0)`
`--zmin`, `--zmax`	浮動小数点数	曲面の最小値 / 最大値	カラースケールの下限と上限（kcal/mol）
`--thresh`	文字列	`baker`	各緩和の収束プリセット（`gau_loose`, `gau`, `gau_tight`, `gau_vtight`, `baker`, `never`）
`--out-json/--no-out-json`	フラグ	`False`	結果の要約を `result.json` に出力（JSON 出力の一覧）

全オプションは自動生成のオプションの一覧（英語のみ）を参照してください。

使用上の注意点¶

範囲は 1 つのリテラルに 2 つ: -s には、1 つのインラインリテラル、または YAML/JSON ファイルの pairs: で、ちょうど 2 つの範囲を渡します。複数ステージのスキャンには scan を使ってください。
chain のある PDB: 位置固定の 4 項目の形 A:SAM:320:CS1 を使うと原子を一意に指定できます。
YAML での拘束の強さ: --restraint-k を省くと bias.k が使われます。
キャップ水素: --freeze-links（デフォルト有効）では、切り出したクラスターのキャップ水素の親原子を固定します。
サイクル数の上限: --relax-max-cycles（デフォルト 100000）が各緩和のサイクル数を制限します。指定すると YAML の opt.max_cycles より優先されます。
基準の行: i = j = -1、is_preopt = true の行は開始構造です。表には残りますが、格子点・エネルギーの基準・図の点には使いません。
エネルギーの基準: --baseline min（デフォルト）は使える点の最小値を 0 にします。--baseline first は点 (i, j) = (0, 0) を 0 にし、(0, 0) が使える点でなければ使える点の最小値を使います。
使える点が少ないとき: 使える点が 3 つ未満か、すべて 1 本の直線上にあるときは、図だけを省きます。[plot] NOTE: Plots skipped: … を表示し、終了コード 0 で終わります。使える点が 1 つも無いときは [plot] No finite data for plotting. を表示し、終了コード 1 で終わります。
PNG の書き出し: PNG は Plotly と Kaleido で書き出します。書き出しに失敗したときは [plot] NOTE: PNG export skipped: … を表示して HTML の曲面は書き、result.json には PNG を載せません。

scan2d（2 次元の拘束付きグリッドスキャン）¶