scan3d¶
概要¶
要約: 調和拘束と MLIP 緩和（デフォルト: UMA、
-b/--backendで ORB・MACE・AIMNet2 も選択可能）により、3 距離（d₁, d₂, d₃）のグリッドスキャンを行います。-s/--scan-lists（YAML/JSON ファイルパス、推奨）またはインライン Python リテラルを使用できます。--csvでは既存surface.csvの可視化のみ実行します。
要点¶
想定場面: 3 つの距離
(d₁, d₂, d₃)上で 3D ポテンシャル体積を得たいとき、または既存のsurface.csvを再プロットしたいとき。入力は 1 つの構造 +-s scan3d.yaml（推奨）または-s/--scan-listsの 単一 インラインリテラル（四つ組は 3 つ）。--csv指定時はプロットのみで実行可能です。計算手法: d₁ → d₂ → d₃ のネストループで
--max-step-sizeから線形グリッドを構成し、事前最適化構造に近い値が先に走査されるよう各軸を並べ替えます。各点は対応する調和拘束を有効にして MLIP バックエンド（デフォルト: UMA）で緩和し、記録されるエネルギーは バイアスを除去して評価されるため、格子点間で直接比較できます。主な出力:
surface.csv、grid/配下の各点の構造、HTML の等値面図（scan3d_density.html）。デフォルト値:
--opt-mode grad（LBFGS）、--no-preopt、--max-step-size 0.20 Å、--bias-k 300 eV·Å⁻²、--thresh baker、--baseline min、--out-dir ./result_scan3d/。3D グリッドは点数が急激に増加するため、まず--max-step-sizeを大きくするか範囲を狭めることを検討してください。次のステップ:
scan3d_density.htmlで低エネルギーチャネルを確認し、2D のscan2dスライスで絞り込むか、tsoptで TS 候補を精密化します。
scan3d は d₁ → d₂ → d₃ の順にループをネストし、対応する拘束をかけて各格子点を緩和します。デフォルトは LBFGS（--opt-mode grad）で、RFOptimizer が必要な場合は --opt-mode hess を指定してください。
XYZ/GJF 入力では、--ref-pdb で参照 PDB トポロジーを指定すると、XYZ 座標を保持したまま PDB/GJF へのフォーマット対応変換が可能になります。
最小例¶
pdb2reaction scan3d -i input.pdb -q 0 -s scan3d.yaml --out-dir ./result_scan3d/
出力の見方¶
result_scan3d/surface.csvresult_scan3d/grid/point_i000_j000_k000.xyzresult_scan3d/scan3d_density.html
よくある例¶
Note:
-s/--scan-listsの解釈結果を確認したい場合は--print-parsedを追加してください。
使用法¶
pdb2reaction scan3d [-i INPUT.{pdb|xyz|trj|...}] [-q CHARGE] [-l, --ligand-charge <number|'RES:Q,...'>] [-m MULT] \
[-b/--backend uma|orb|mace|aimnet2] [--solvent SOLVENT] [--solvent-model alpb|cpcmx] \
[-s scan3d.yaml | --scan-lists '[(i,j,lowÅ,highÅ), (i,j,lowÅ,highÅ), (i,j,lowÅ,highÅ)]'] [options] \
[--convert-files/--no-convert-files] [--ref-pdb FILE] [--csv PATH]
注: -i/--input と -s/--scan-lists は --csv が指定されていない限り必須です。
例¶
# 推奨: YAML/JSON spec
cat > scan3d.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]
- ["TYR,285,CG", "SAM,309,C12", 1.10, 3.00]
YAML
pdb2reaction scan3d -i input.pdb -q 0 -s scan3d.yaml
# 代替: Python リテラル
pdb2reaction scan3d -i input.pdb -q 0 \
--scan-lists '[("TYR,285,CA","SAM,309,C10",1.30,3.10),("TYR,285,CB","SAM,309,C11",1.20,3.20),("TYR,285,CG","SAM,309,C12",1.10,3.00)]'
# LBFGS 緩和、内側軌跡ダンプ、HTML 等値面プロット
pdb2reaction scan3d -i input.pdb -q 0 \
--scan-lists '[("TYR,285,CA","SAM,309,C10",1.30,3.10),("TYR,285,CB","SAM,309,C11",1.20,3.20),("TYR,285,CG","SAM,309,C12",1.10,3.00)]' \
--max-step-size 0.20 --dump --out-dir ./result_scan3d/ --opt-mode grad \
--preopt --baseline min
# 既存surface.csvからのプロットのみ（スキャンしない）
pdb2reaction scan3d --csv ./result_scan3d/surface.csv --zmin -10 --zmax 40 --out-dir ./result_scan3d/
スキャンリスト仕様¶
scan3d はちょうど 3 つの四つ組 (i, j, low_Å, high_Å) を受け付けます（YAML/JSON では pairs キー、インラインでは単一リテラル）。scan と異なり、リテラルは 1 つだけを受け付けます（複数ステージは非対応）。
YAML/JSON ファイル書式、インライン Python リテラル構文、原子セレクタ、クォート規則については CLI 規約: スキャンリスト仕様 を参照してください。
ワークフロー¶
geom_loaderで構造を読み込み、CLI または Gaussian テンプレートから電荷とスピンを解決します。--preoptの場合は無バイアスの事前最適化を実行します。-qが省略され--ligand-chargeが与えられている場合、構造は酵素–基質複合体として扱われ、PDB 入力（または--ref-pdb付き XYZ/GJF）でextract.pyの電荷サマリーから総電荷を導出します。-s/--scan-lists（YAML/JSON ファイルパスまたはインライン Python リテラル、デフォルト 1 始まり、--zero-basedで 0 始まり）を 3 つの四つ組に解析します。PDB 入力では、各原子指定に整数インデックスまたは'TYR,285,CA'のようなセレクタ文字列を使用できます。区切りは空白・カンマ・スラッシュ・バッククォート・バックスラッシュのいずれも可で、トークン順序は任意です。h = --max-step-sizeで各距離の線形グリッドを生成し、開始距離に近い値が先に走査されるよう並べ替えます。外側ループで
d1[i]を走査し、d₁ 拘束のみを適用して緩和します。近い d₁ 値の既存構造から開始します。中間ループで
d2[j]を走査し、d₁ + d₂ 拘束を適用して緩和します。近い (d₁, d₂) の構造から開始します。内側ループで
d3[k]を走査し、3 つの拘束すべてを適用して緩和します。バイアスを除去したエネルギーを測定し、構造と収束フラグを書き出します。完了後に
surface.csvを組み立て、--baseline {min|first}で kcal/mol の基準を設定し、--zmin/--zmaxに従った 3D RBF 補間等値面図scan3d_density.htmlを生成します。--csvが指定された場合、この可視化ステップのみを実行します。
CLI オプション¶
オプション |
説明 |
デフォルト |
|---|---|---|
|
|
|
|
総電荷（CLI > テンプレート/ |
テンプレート/導出がない場合は必須 |
|
残基別電荷マッピング（例: |
None |
|
UMA 予測器の並列度（workers > 1 で解析ヘシアン無効; |
|
|
スピン多重度 2S+1。 |
|
|
スキャンターゲット: YAML/JSON スペックファイルパス（推奨）または 単一のインライン Python リテラルで 3 つの四つ組 |
|
|
|
|
|
|
|
|
各距離の 1 増分あたりの最大変化量（Å）。グリッド密度を決定 |
|
|
調和バイアス強度 |
|
|
各バイアス緩和の最大最適化サイクル数。YAML で |
|
|
|
|
|
PDB 入力時にリンク水素の親原子を凍結 |
|
|
凍結する原子の 1 始まりインデックスをカンマ区切りで明示的に指定（例: |
None |
|
各 (d₁, d₂) ペアの |
|
|
PDB/Gaussian 入力で XYZ/TRJ → PDB/GJF 変換を切り替え |
|
|
XYZ/GJF 入力時の参照 PDB トポロジー（XYZ 座標を保持） |
None |
|
出力ディレクトリ |
|
|
既存の |
None |
|
収束プリセットの上書き（ |
|
|
ベース YAML 設定ファイル（最初に適用） |
None |
|
MLIP バックエンド |
|
|
xTB 暗黙溶媒（例: |
|
|
xTB 溶媒モデル |
|
|
スキャン前に無バイアス最適化を実行。スコープ依存デフォルト: 単体では |
|
|
kcal/mol の基準をグローバル最小値または |
|
|
等値面の色範囲（kcal/mol） |
自動 |
|
|
|
共有 YAML セクション¶
geom,calc,opt,lbfgs,rfo: YAML リファレンス と同じキーを使用します。opt.dumpは YAML で設定可能ですが、軌跡出力は--dumpで制御します。
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-1p1 # uma-s-1p1 | uma-m-1p1
device: auto # MLIP device selection
opt:
thresh: baker # convergence preset (default: baker)
max_cycles: 10000 # optimizer cycle cap
dump: false # optimizer dumps (scan trajectories are controlled by --dump)
out_dir: ./result_scan3d/ # output directory
lbfgs:
max_step: 0.3 # maximum step length
out_dir: ./result_scan3d/ # LBFGS-specific output directory
rfo:
trust_radius: 0.10 # trust-region radius
out_dir: ./result_scan3d/ # RFO-specific output directory
bias:
k: 300.0 # harmonic bias strength (eV·Å⁻²)
--relax-max-cycles は明示的に指定され、かつ YAML で opt.max_cycles が設定されていない場合にのみ適用されます（デフォルト 10000）。
セクション bias¶
k（300）: 調和バイアス強度（eV·Å⁻²）。
出力¶
out_dir/ (デフォルト:./result_scan3d/)
├─ surface.csv # グリッドメタデータ（i=j=k=-1 の参照行を含む場合あり）
├─ scan3d_density.html # 3D エネルギー等値面の可視化
├─ grid/point_i###_j###_k###.xyz # 各グリッド点の緩和構造（Å×100 タグ）
├─ grid/point_i###_j###_k###.pdb # 変換有効時の PDB コンパニオン
├─ grid/point_i###_j###_k###.gjf # テンプレートがある場合の Gaussian コンパニオン
├─ grid/preopt_i###_j###_k###.xyz # スキャン開始前の構造（--preopt の場合は最適化済み）
└─ grid/inner_path_d1_###_d2_###_trj.xyz # --dump の場合のみ（PDB 入力で変換有効時は .pdb も生成）
注意事項¶
症状起点で切り分ける場合は 典型エラー別レシピ を先に参照し、詳細は トラブルシューティング を確認してください。
MLIP バックエンド（デフォルト: UMA、
-b/--backendで切替可能）が計算エンジンで、1D/2D スキャンと同じHarmonicBiasCalculatorを再利用します。Å 単位の制限値は内部で Bohr に変換され、LBFGS ステップや RFO 信頼半径の制御に使われます。最適化の一時ファイルはテンポラリディレクトリに配置されます。
--baselineはデフォルトでグローバル最小値を基準としてゼロにします。--baseline firstは(i,j,k)=(0,0,0)の格子点を基準にします。3D 可視化は 50×50×50 グリッドでの RBF 補間と、半透明の段階的等値面を使用します（断面表示はありません）。
--freeze-linksはユーザー指定のfreeze_atomsにリンク水素親原子をマージし、抽出された活性部位モデルの境界を固定します。