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

scan3d サブコマンドは、3 つの座標の格子の各点を調和拘束で保って緩和し、拘束を外したエネルギーを記録して、エネルギーの分布を等値面の HTML に描きます。

主な用途¶

3 つの座標が同時に関わる反応: 結合の形成・別の結合の切断・プロトン移動が 1 つの段階で起きるような反応で、エネルギーの地形を調べる
計算済みの格子の描き直し: 既存の surface.csv を、別のエネルギーの範囲で描き直す（--csv）

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

基本的な実行例¶

例の 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 スペックファイルからの実行¶

3 つの範囲を pairs: に書き、--out-json を付けて result.json も出力します。デフォルトの刻み幅 0.2 Å では、このファイルから 9 × 9 × 7 の格子（567 点）ができます。

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

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

等値面は result_scan3d/scan3d_density.html をブラウザで開いて確認できます。result.json には scientific_status と使える点の数 n_points_usable が入ります。

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

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

pdb2reaction scan3d -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),("SAM,320,SD","SAM,320,CS1",1.80,3.00)]'

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

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

pdb2reaction scan3d -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),("SAM,320,SD","SAM,320,CS1",1.80,3.00)]' \
    --dump -o ./result_scan3d/ --preopt

4. 既存の surface.csv からの描き直し¶

計算済みの格子の等値面を、−10〜40 kcal/mol の範囲で描き直します。エネルギーは計算しません。別の -o を指定すると、元のスキャンのファイルが残ります。

pdb2reaction scan3d --csv ./result_scan3d/surface.csv --zmin -10 --zmax 40 -o ./result_scan3d_replot/

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

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

surface.csv の読み方と判定¶

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

列	内容
`i`, `j`, `k`	格子の番号。開始構造に最も近い値が 0 なので、値の昇順ではなく計算した順の番号
`d1_A`, `d2_A`, `d3_A`（`q1`, `q2`, `q3` も同じ値）	緩和の後に測った座標の値。どの軸でも列名は `_A` のままで、角度の軸には度が入る。単位は `q1_unit`, `q2_unit`, `q3_unit`（`angstrom` か `degree`）
`target_d1_A`, `target_d2_A`, `target_d3_A`（`target_q1`, `target_q2`, `target_q3` も同じ値）	その点の拘束の目標値
`energy_hartree`	拘束を外したエネルギー（Hartree）
`bias_converged`	拘束付きの緩和が収束したか
`is_preopt`	基準の行だけ `true`
`energy_kcal`	基準からの相対エネルギー（kcal/mol）
`d1_label`, `d2_label`, `d3_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 も付けます。反応物側と生成物側の谷の点は path-search の入力にできます。

主な出力ファイル¶

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

result_scan3d/
├─ surface.csv                          # 基準の行を含む格子の表
├─ scan3d_density.html                  # 3D 等値面（ブラウザで開く）
├─ grid/
│  ├─ point_i150_j090_k180.xyz          # 各格子点の緩和後の構造
│  ├─ preopt_iDDD_jDDD_kDDD.xyz         # 開始構造（基準の行）
│  └─ inner_path_d1_000_d2_000_trj.xyz  # (d₁, d₂) の組ごとの内側ループの軌跡（--dump 指定時）
└─ result.json                          # 結果の要約（--out-json 指定時）。summary.json も同じ内容

まず scan3d_density.html と surface.csv を確認し、各点の構造は grid/ を見てください。result.json の grid_points[] には、各格子点の番号・値・目標値・エネルギー・収束の可否・構造ファイルが入ります。

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

主な CLI オプション¶

オプション	引数の型	デフォルト	説明
`-i, --input`	パス	`None`	入力構造ファイル（`.pdb`, `.cif`, `.mmcif`, `.xyz` 等）。`--csv` を使う場合のほかは必須
`-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`	文字列	`None`	YAML/JSON スペックファイルまたは 1 つのインラインリテラルで 3 つの範囲を指定。距離 `(i,j,low,high)`、角度 `(i,j,k,low,high)`、二面角 `(i,j,k,l,low,high)`。`--csv` を使う場合のほかは必須
`-o, --out-dir`	パス	`./result_scan3d/`	出力先ディレクトリ
`--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`。省くと YAML の `bias.k` を使用
`--opt-mode`	`grad` / `hess`	`grad`	各点の緩和の方法：L-BFGS / RFO
`--preopt/--no-preopt`	フラグ	`False`	スキャンの前に入力構造を拘束なしで最適化
`--dump/--no-dump`	フラグ	`False`	(d₁, d₂) の組ごとの内側ループ（d₃）の軌跡を `grid/` に出力
`--baseline`	`min` / `first`	`min`	`energy_kcal` の 0 点：使える点の最小値、または点 `(0, 0, 0)`
`--zmin`, `--zmax`	浮動小数点数	補間した値の最小値 / 最大値	8 枚の等値面を置くエネルギーの範囲の下限と上限（kcal/mol）
`--thresh`	文字列	`baker`	各緩和の収束プリセット（`gau_loose`, `gau`, `gau_tight`, `gau_vtight`, `baker`, `never`）
`--csv`	パス	`None`	計算済みの `surface.csv` を読み、図だけを描く。`-i`・`-s`・`-q` は不要
`--out-json/--no-out-json`	フラグ	`False`	結果の要約を `result.json` に出力（JSON 出力の一覧）

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

使用上の注意点¶

範囲は 1 つのリテラルに 3 つ: -s には、1 つのインラインリテラル、または YAML/JSON ファイルの pairs: で、ちょうど 3 つの範囲を渡します。複数ステージのスキャンには scan を使ってください。
chain のある PDB: 位置固定の 4 項目の形 A:SAM:320:CS1 を使うと原子を一意に指定できます。
格子の大きさ: 緩和の回数は 3 つの軸の値の数の積で、すぐに大きくなります（例 1 では 567 回）。最初は --max-step-size を大きくするか、範囲を狭めてください。
--baseline first: 点 (i, j, k) = (0, 0, 0) が使える点ならそこを 0 にします。使える点でなければ [baseline] 'first' requested but no eligible (i=0,j=0,k=0); using eligible minimum instead. を表示し、使える点の最小値を使います。
キャップ水素: --freeze-links（デフォルト有効）では、切り出したクラスターのキャップ水素の親原子を固定します。
計算せずに指定を確かめる: --dry-run は入力・電荷とスピン・-s を読み、計画を表示して、最適化をせずに終わります。--csv を付けたときは、オプションだけを確かめます。
サイクル数の上限: --relax-max-cycles（デフォルト 100000）が各緩和のサイクル数を制限します。指定すると YAML の opt.max_cycles より優先されます。
基準の行: i = j = k = -1、is_preopt = true の行は開始構造です。表には残りますが、格子点・エネルギーの基準・図の点には使いません。
表からの描き直し（--csv）: 表には d1_A, d2_A, d3_A と、energy_hartree か energy_kcal の列が要ります。基準の行と、bias_converged = false かエネルギーが有限でない行は除きます。
使える点が少ないとき: 使える点が 4 つ未満か、すべて 1 つの平面上にあるときは、図だけを省きます。[plot] NOTE: Volume plot skipped: … を表示し、終了コード 0 で終わります。使える点が 1 つも無いときは [plot] No finite data for plotting. を表示し、終了コード 1 で終わります。
同じ --out-dir への再実行: スキャン全体でも --csv での描き直しでも、--out-json を付けない実行は --out-dir の result.json と summary.json を消し、付けた実行はこれらを上書きします。また、どの実行も scan3d_density.html を置き換えます。

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