scan3d¶
調和拘束と機械学習原子間ポテンシャル（MLIP）緩和により、3 距離 (d₁, d₂, d₃) のグリッドスキャンを行い、その距離空間上の 3次元ポテンシャルエネルギー分布（マップ）を生成します。この分布を得たいとき、または既存の surface.csv を再プロットしたいときに使用します。
コマンドの呼び出し方は 2 通りあります。新規スキャンを実行するには、ターゲットを -s/--scan-lists で指定します（YAML/JSON ファイルパスが推奨、またはインライン Python リテラル）。エネルギーを再評価せずに既存の surface.csv を再プロットするだけなら、--csv で渡します。スキャン中、scan3d は d₁ → d₂ → d₃ の順にループをネストし、対応する調和拘束をかけて各格子点を緩和します。
デフォルトのオプティマイザは L-BFGS（--opt-mode grad）です。RFOptimizer が必要な場合は --opt-mode hess を指定してください。
XYZ/GJF 入力では、--ref-pdb で参照 PDB トポロジーを指定すると、XYZ 座標を保持したまま PDB/GJF 形式へ変換できます。
実行例¶
コマンド形式:
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/--scan-lists scan3d.yaml | '[(i,j,lowÅ,highÅ), (i,j,lowÅ,highÅ), (i,j,lowÅ,highÅ)]'] [options] \
[--convert-files/--no-convert-files] [--ref-pdb FILE] [--csv PATH]
推奨: YAML/JSON spec ファイル。
# 推奨: 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 リテラル。
# 代替: Python リテラル
pdb2reaction scan3d -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),("TYR,285,CG","SAM,309,C12",1.10,3.00)]'
LBFGS 緩和、内側軌跡ダンプ、HTML 等値面プロット。
# LBFGS 緩和、内側軌跡ダンプ、HTML 等値面プロット
pdb2reaction scan3d -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),("TYR,285,CG","SAM,309,C12",1.10,3.00)]' \
--max-step-size 0.20 --dump -o ./result_scan3d/ --opt-mode grad \
--preopt --baseline min
既存 surface.csv からのプロットのみ（新規エネルギー評価をスキップ）。
# 既存 surface.csv からのプロットのみ（スキャンしない）
pdb2reaction scan3d --csv ./result_scan3d/surface.csv --zmin -10 --zmax 40 -o ./result_scan3d/
処理の流れ¶
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 つの 4 要素タプルに解析します。PDB 入力では、各原子指定に整数インデックスまたは'TYR,285,CA'のようなセレクタ文字列を使用できます。区切りは空白・カンマ・スラッシュ・バッククォート・バックスラッシュのいずれも可で、トークン順序は任意です（不明な場合は resname, resseq, atom の順と仮定）。h = --max-step-sizeで各距離の線形グリッドを生成し、開始距離に近い値が先に走査されるよう並べ替えます。外側ループで
d1[i]を走査し、d₁ 拘束のみを適用して緩和します。近い d₁ 値の既存構造から開始します。中間ループで
d2[j]を走査し、d₁ + d₂ 拘束を適用して緩和します。近い (d₁, d₂) の構造から開始します。内側ループで
d3[k]を走査し、3 つの拘束すべてを適用して緩和します。バイアスを除去したエネルギーを測定し、構造と収束フラグを書き出します。完了後に
surface.csv（カラム:i,j,k,d1_A,d2_A,d3_A,energy_hartree,bias_converged,energy_kcal,d1_label,d2_label,d3_label）を組み立て、--baseline {min|first}で kcal/mol の基準を設定し、--zmin/--zmaxに従った 3D RBF 補間等値面図scan3d_density.htmlを生成します。--csvが指定された場合、この可視化ステップのみを実行します。
出力¶
主要な成果物は surface.csv、grid/ 配下の各点の構造、そして等値面図 scan3d_density.html です。
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 も生成）
グリッド点の構造は Å×100 タグを使用するため、point_i130_j310_k200.xyz は d₁=1.30, d₂=3.10, d₃=2.00 Å に対応します。
CLI オプション¶
オプション |
説明 |
デフォルト |
|---|---|---|
入力と電荷 |
||
|
|
|
|
総電荷（CLI > テンプレート/ |
テンプレート/導出がない場合は必須 |
|
単一の整数（例: |
None |
|
スピン多重度 2S+1。 |
|
バックエンドと計算 |
||
|
MLIP バックエンド |
|
|
MLIP 予測器の並列度（workers > 1 で解析Hessianが無効、UMA バックエンドのみ対応; |
|
|
xTB 暗黙溶媒（例: |
|
|
xTB 溶媒モデル |
|
活性領域の凍結 |
||
|
PDB 入力時にキャップ水素の親原子を凍結 |
|
|
凍結する原子の 1 始まりインデックスをカンマ区切りで明示的に指定（例: |
None |
スキャンターゲット |
||
|
スキャンターゲット: YAML/JSON スペックファイルパス（推奨）または 単一のインライン Python リテラルで 3 つの4 要素タプル |
|
|
|
|
|
|
|
|
各距離の 1 増分あたりの最大変化量（Å）。グリッド密度を決定 |
|
緩和 |
||
|
調和バイアス強度 |
|
|
|
|
|
各バイアス緩和の最大最適化サイクル数。YAML で |
|
|
収束プリセットの上書き（ |
|
|
スキャン前に無バイアス最適化を実行 |
|
マージとアラインメント |
||
|
XYZ/GJF 入力時の参照 PDB トポロジー（XYZ 座標を保持） |
None |
|
PDB/Gaussian 入力で XYZ/TRJ → PDB/GJF 変換を切り替え |
|
出力と設定 |
||
|
グリッドとプロットの出力ディレクトリ |
|
|
既存の |
None |
|
各 (d₁, d₂) ペアの |
|
|
kcal/mol の基準をグローバル最小値または |
|
|
等値面の色範囲（kcal/mol） |
自動 |
|
|
|
|
ベース YAML 設定ファイル（最初に適用） |
None |
YAML 設定¶
共有 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·Å⁻²）。
注記¶
scan3dはちょうど 3 つの4 要素タプル(i, j, low_Å, high_Å)を受け付けます（YAML/JSON ではpairsキー、インラインでは単一リテラル）。scanと異なり、リテラルは 1 つだけを受け付けます（複数ステージは非対応）。YAML/JSON ファイル書式、インライン Python リテラル構文、原子セレクタ、クォート規則については CLI 規約: スキャンリスト仕様 を参照してください。3D グリッドは点数が急激に増加するため、まず
--max-step-sizeを大きくするか範囲を狭めることを検討してください。計算エンジンは MLIP バックエンド（デフォルト: UMA）で、1D/2D スキャンと同じ
HarmonicBiasCalculatorを再利用します。Å 単位の制限値は内部で Bohr に変換され、L-BFGS ステップや RFO 信頼半径の制御に使われます。最適化の一時ファイルはテンポラリディレクトリに配置されます。
--baselineはデフォルトでグローバル最小値を基準としてゼロにします。--baseline firstは(i,j,k)=(0,0,0)の格子点を基準にします。3D 可視化は 50×50×50 グリッドでの RBF 補間と、半透明の段階的等値面を使用します（断面表示はありません）。
--freeze-linksはユーザー指定のfreeze_atomsにキャップ水素親原子をマージし、抽出された活性部位モデルの境界を固定します。-s/--scan-listsの解釈結果を確認したい場合は--print-parsedを追加してください。症状起点で切り分ける場合は 典型エラー別レシピ を先に参照し、詳細は トラブルシューティング を確認してください。