scan3d

調和拘束と ML/MM 緩和による 3 距離（d1, d2, d3）のグリッドスキャンを実行し、3 つの結合距離を変数とする 3D PES をマッピングします。入力には PDB/mmCIF、または --ref-pdb を伴う XYZ を使用できます。mlmm scan3d は d1、d2、d3 のネストループを実行し、ML/MM calculator（mlmm.backends.mlmm_calc.mlmm）を使用して適切な拘束で各点を緩和します。ML 領域は --model-pdb、--model-indices、または --detect-layer による B-factor layer から解決し、Amber パラメータは --parm から読み取ります。MLIP バックエンドは -b/--backend で選択し（デフォルト: uma）、オプティマイザは PySisyphus L-BFGS です。-s/--scan-lists で YAML/JSON スペックファイル（推奨）またはインライン Python リテラルを使用します。--csv で事前計算した surface を読み込めば、スキャンを再実行せずに再描画のみ行えます。

実行例

# 最小: YAML spec から 3D スキャンを実行
mlmm scan3d -i input.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -s scan3d.yaml -o ./result_scan3d/

（--print-parsed を追加すると、解釈されたスキャンスペックを検証し、GPU 計算を実行せずに終了します。）

# 推奨: YAML/JSON spec
cat > scan3d.yaml << 'YAML'
one_based: true
pairs:
 - [12, 45, 1.30, 3.10]
 - [10, 55, 1.20, 3.20]
 - [15, 60, 1.10, 3.00]
YAML
mlmm scan3d -i input.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -s scan3d.yaml --print-parsed

# インライン Python リテラル、事前最適化・--dump・カスタム出力ディレクトリ付き
mlmm scan3d -i input.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -s "[(12,45,1.30,3.10),(10,55,1.20,3.20),(15,60,1.10,3.00)]" \
 --max-step-size 0.20 --dump -o ./result_scan3d/ \
 --preopt --baseline min

処理の流れ

  1. geom_loader で構造を読み込み、CLI から電荷/スピンを解決し、--preopt の場合は任意でバイアスなし事前最適化を実行。

  2. -s/--scan-lists（YAML/JSON スペックファイルまたはインラインリテラル）からターゲットを解析して 3 つの 4 要素タプルにします（デフォルト 1 始まりインデックス、--zero-based 指定時は 0 始まり）。PDB メタデータを利用できる場合、各原子エントリは整数インデックスまたは "TYR,285,CA" のようなセレクター文字列が使用可能。区切り文字はスペース、カンマ、スラッシュ、バッククォート、バックスラッシュ。

  3. 外側ループ d1[i]: d1 拘束のみで緩和。d1 値が最も近い以前のスキャン済みジオメトリから開始。

  4. 中間ループ d2[j]: d1 と d2 の拘束で緩和。最も近い (d1, d2) ジオメトリから開始。

  5. 内側ループ d3[k]: 3 つの拘束すべてで緩和。バイアスなしエネルギーを測定（評価時にバイアス除去）し、拘束ジオメトリと収束フラグを書き出し。

  6. スキャン完了後、surface.csv を組み立て、開始／事前最適化構造を常に i = j = k = -1 の参照行として残し、kcal/mol ベースラインシフト（--baseline {min|first}）を適用し、3D RBF 補間アイソサーフェスプロット（scan3d_density.html）を生成（--zmin/--zmax を尊重）。参照行は基準エネルギー、補間、plot から除外します。

プロット専用 CSV には d1_A、d2_A、d3_A と energy_hartree または energy_kcal が必要です。新規出力は baseline=first の場合は grid index 列 i、j、k も必要です。 新規出力は bias_converged、artifact_written、is_preopt も記録し、事前最適化行、 明示的な非収束行、構造ファイル未作成行、非有限値を除外します。provenance が 不完全な旧形式は警告付きで読み込み、全 index が -1 の行も参照行として除外します。補間には座標重複がなく、全 3 軸を またぐ 4 点以上の非共面 usable point が必要です。baseline=first で (0,0,0) が usable でなければ usable minimum にフォールバックします。

出力

out_dir/ (デフォルト:./result_scan3d/)
 surface.csv # グリッドメタデータ（座標、energy、convergence、artifact status）
 scan3d_density.html # 3D エネルギーアイソサーフェス可視化
 grid/point_i###_j###_k###.xyz # 各グリッド点の緩和ジオメトリ
 grid/point_i###_j###_k###.pdb # 対応する PDB（B 因子: ML=0, Movable-MM=10, Frozen=20）
 grid/inner_path_d1_###_d2_###_trj.xyz # --dump が True の場合のみ

ファイル名タグ i###_j###_k### は Å の 100 分の 1 の整数（d1×100, d2×100, d3×100）であり、ステップ番号ではありません。

CLI オプション

オプション

説明

デフォルト

-i, --input PATH

全系 PDB/mmCIF、または --ref-pdb を伴う XYZ（リンク原子なし）。

--csv 指定時を除き必須

--parm PATH

完全酵素の Amber parm7 トポロジー。

--csv 指定時を除き必須

--model-pdb PATH

ML 領域を定義する PDB。

None

--model-indices TEXT

明示的な ML 領域原子インデックス（--model-pdb の代替）。

None

--model-indices-one-based / --model-indices-zero-based

--model-indices のインデックス規約。

True（1 始まり）

--detect-layer / --no-detect-layer

B 因子から ML/MM レイヤーを自動検出。

有効

-q, --charge INT

ML 領域の総電荷。

None（-l または --csv 未指定時は必須）

-l, --ligand-charge TEXT

残基ごとの電荷マッピング（例: GPP:-3,SAM:1）。-q 省略時に合計電荷を導出。

None

-m, --multiplicity INT

スピン多重度 (2S+1)。

1

--freeze-atoms TEXT

1 始まりカンマ区切りの凍結原子インデックス。

None

--movable-cutoff FLOAT

ML 領域からの可動 MM 原子の距離カットオフ (Å)。指定すると --detect-layer が無効化されます。

None

-s, --scan-lists TEXT

スキャンターゲット: YAML/JSON スペックファイルパス（自動検出、pairs に 3 つの 4 要素タプル）またはインライン Python リテラル。i/j は整数インデックスまたは PDB 原子セレクター。

--csv 指定時を除き必須

--csv FILE

事前計算済み surface.csv を読み込みスキャンなしでプロット生成。

None

--one-based / --zero-based

(i, j) インデックスを 1 始まりまたは 0 始まりとして解釈。

True（1 始まり）

--print-parsed/--no-print-parsed

-s/--scan-lists 解釈後のペア情報を表示。

False

--max-step-size FLOAT

ステップごとの最大距離増分 (Å)。グリッド密度を制御。

0.20

--bias-k FLOAT

調和拘束ポテンシャル強度 k (eV/Ų)。

300.0

--relax-max-cycles INT

バイアス緩和ごとのオプティマイザサイクル上限。

100000

--dump/--no-dump

(d1, d2) スライスごとの内側 d3 スキャン TRJ を書き出し。

False

-o, --out-dir TEXT

グリッドとプロットの出力ディレクトリルート。

./result_scan3d/

--thresh TEXT

収束プリセット上書き（gau_loose、gau、gau_tight、gau_vtight、baker、never）。

baker

--config FILE

ベース YAML 設定ファイル（最初に適用）。

None

--ref-pdb FILE

XYZ 入力用の参照 PDB トポロジー。

None

--preopt/--no-preopt

スキャン前にバイアスなし最適化を実行。

False

--baseline {min,first}

kcal/mol エネルギーをグローバル最小値または (i,j,k)=(0,0,0) がゼロになるようシフト。

min

--zmin FLOAT

アイソサーフェスカラーバンドの手動下限（kcal/mol）。

自動スケール

--zmax FLOAT

アイソサーフェスカラーバンドの手動上限（kcal/mol）。

自動スケール

-b, --backend CHOICE

ML 領域の MLIP バックエンド: uma、orb、mace、aimnet2。

uma

--cmap/--no-cmap

REAL と MODEL の両 MM 層で CMAP を保持します。

--cmap

--mm-backend [hessian_ff|openmm]

MM バックエンド。Hessian 構築法は calc.mm_fd が別に制御します（デフォルト true: 有限差分）。

hessian_ff

--link-atom-method [scaled|fixed]

リンク原子の配置法: scaled（$g$ 因子）または固定 1.09/1.01 Å。

scaled

--out-json/--no-out-json

機械可読な result.json を out_dir に書き出し。

False

--convert-files/--no-convert-files

PDB テンプレート利用可能時の XYZ/TRJ から対応する PDB の生成を切り替え。

True

全フラグの一覧は自動生成されたコマンドリファレンスにあります。ここに手動で複製しないでください。

スキャンリスト構文

YAML/JSON スペックフォーマット（推奨）

-s/--scan-lists は YAML/JSON ファイルを自動検出します。ファイルパスを渡すとスペックモードになります:

one_based: true # 任意; デフォルトは CLI の --one-based/--zero-based
pairs:
 - [12, 45, 1.30, 3.10]
 - [10, 55, 1.20, 3.20]
 - [15, 60, 1.10, 3.00]

  • pairs は必須で、正確に 3 つの 4 要素タプルを含む必要があります。

  • 各 4 要素タプルは (i, j, low_A, high_A) です。

  • インデックスは整数または PDB セレクター（--scan-lists と同じ）が使用可能です。

インラインリテラルフォーマット

-s/--scan-lists がファイルパスでない値を受け取ると、単一の Python リテラル文字列として評価されます。シェルクォートに注意してください。

リテラルは正確に 3 つの 4 要素タプル (atom1, atom2, low_A, high_A) の Python リストです:

-s '[(atom1, atom2, low_A, high_A), (atom3, atom4, low_A, high_A), (atom5, atom6, low_A, high_A)]'

  • シェルが括弧やスペースを解釈しないよう、リテラル全体をシングルクォートで囲んでください。

  • 各 4 要素タプルは 1 つのスキャン軸を定義します: atom1–atom2 間の距離を low_A から high_A までスキャンします。

  • scan と異なり、1 つのリテラルのみ受け付けます（マルチステージ非対応）。

原子は整数インデックスまたは PDB セレクター文字列で指定できます:

方法

例

備考

整数インデックス

(1, 5, 1.30, 3.10)

デフォルトは 1 始まり（--one-based）

PDB セレクター

("TYR,285,CA", "MMT,309,C10", 1.30, 3.10)

残基名、残基番号、原子名

PDB セレクターのトークンは、カンマ ,、スペース、スラッシュ /、バッククォート `、バックスラッシュ \ のいずれかで区切れます。トークンの順序は自由です。

# 以下はすべて同じ原子を指定:
"TYR,285,CA"
"TYR 285 CA"
"TYR/285/CA"
"285,TYR,CA" # 順序は自由

クォート規則:

# 正しい: リスト全体をシングルクォート、内側のセレクター文字列をダブルクォート
-s '[("TYR,285,CA","MMT,309,C10",1.30,3.10),("TYR,285,CB","MMT,309,C11",1.20,3.20),("TYR,285,CG","MMT,309,C12",1.10,3.00)]'

# 正しい: 整数インデックスは内側のクォート不要
-s '[(1, 5, 1.30, 3.10), (2, 8, 1.20, 3.20), (3, 12, 1.10, 3.00)]'

# 非推奨: 外側をダブルクォートにすると内側のクォートをエスケープする必要あり
-s "[(\"TYR,285,CA\",\"MMT,309,C10\",1.30,3.10),...]"

YAML 設定

geom:
 coord_type: cart
 freeze_atoms: []
calc:
 model_charge: 0
 model_mult: 1
 real_parm7: real.parm7
 model_pdb: ml_region.pdb
opt:
 thresh: baker
 # max_cycles: 100000 # 任意の有限上限
lbfgs:
 max_step: 0.3
bias:
 k: 300.0

軌跡保存と出力先は CLI が所有する --dump と --out-dir を使います。

関連項目