scan2d¶
概要¶
要約: 調和拘束と ML/MM 緩和による 2 距離（d1, d2）グリッドスキャンを実行します。
-s/--scan-listsで YAML/JSON スペックファイル（推奨）またはインライン Python リテラルを使用します。
mlmm scan2d は --max-step-size を使用して 2 つの結合距離の線形グリッドを構築し、適切な拘束を適用して各グリッド点を緩和し、バイアスなしの ML/MM エネルギーを可視化用に記録します。スキャンはまず d1 を反復し d1 拘束のみで構造を緩和し、次に各 d1 値について d2 を反復し両方の拘束を適用します。
各グリッド点のエネルギーはバイアスなしで再評価され、PES グリッドとコンタープロットが作成されます。出力にはグリッド点ごとの XYZ スナップショット、PES をまとめた surface.csv、2D コンターマップ（scan2d_map.png）、底面投影付き 3D ランドスケープ（scan2d_landscape.html）が含まれます。
最小例¶
mlmm scan2d -i input.pdb --parm real.parm7 --model-pdb ml_region.pdb \
-q 0 -s scan2d.yaml --print-parsed -o ./result_scan2d/
出力の見方¶
result_scan2d/surface.csvresult_scan2d/grid/point_i000_j000.xyzresult_scan2d/scan2d_map.pngとresult_scan2d/scan2d_landscape.html
よくある例¶
YAML spec の解釈結果を先に確認する。
インライン
-sリテラルを使う。--dumpを有効にして d1 ごとの内側軌跡を保存する。
注記:
-s/--scan-listsの解釈結果を確認したい場合は--print-parsedを追加してください。
使用法¶
mlmm scan2d -i INPUT.pdb --parm real.parm7 --model-pdb ml_region.pdb \
-q CHARGE [-m SPIN] \
[-s scan2d.yaml | -s "[(I1,J1,LOW1,HIGH1),(I2,J2,LOW2,HIGH2)]"] \
[--one-based|--zero-based] [--max-step-size FLOAT] [--bias-k FLOAT] \
[--freeze-atoms "1,3,5"] [--relax-max-cycles INT] [--thresh PRESET] \
[--dump/--no-dump] [--out-dir DIR] \
[--preopt/--no-preopt] [--baseline {min|first}] [--zmin FLOAT] [--zmax FLOAT]
例¶
# 推奨: YAML/JSON spec
cat > scan2d.yaml << 'YAML'
one_based: true
pairs:
- [12, 45, 1.30, 3.10]
- [10, 55, 1.20, 3.20]
YAML
mlmm scan2d -i input.pdb --parm real.parm7 --model-pdb ml_region.pdb \
-q 0 -s scan2d.yaml --print-parsed
# 代替: インライン Python リテラル
mlmm scan2d -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)]"
# TRJ ダンプ付き LBFGS スキャン、コンタープロットの固定カラースケール
mlmm scan2d -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)]" \
--max-step-size 0.20 --dump -o ./result_scan2d/ --preopt --baseline min \
--zmin 0.0 --zmax 40.0
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]
pairsは必須で、正確に 2 つの四つ組を含む必要があります。各四つ組は
(i, j, low_A, high_A)です。インデックスは整数または PDB セレクター（インラインリテラルと同じ）が使用可能です。
インラインリテラルフォーマット¶
-s/--scan-lists がファイルパスでない値を受け取ると、単一の Python リテラル文字列として評価されます。シェルクォートに注意してください。
基本構造¶
リテラルは正確に 2 つの四つ組 (atom1, atom2, low_A, high_A) の Python リストです:
-s '[(atom1, atom2, low_A, high_A), (atom3, atom4, low_A, high_A)]'
シェルが括弧やスペースを解釈しないよう、リテラル全体をシングルクォートで囲んでください。
各四つ組は 1 つのスキャン軸を定義します:
atom1–atom2間の距離をlow_Aからhigh_Aまでスキャンします。scanと異なり、1 つのリテラルのみ受け付けます（マルチステージ非対応）。
原子の指定¶
原子は整数インデックスまたは PDB セレクター文字列で指定できます:
方法 |
例 |
備考 |
|---|---|---|
整数インデックス |
|
デフォルトは 1 始まり（ |
PDB セレクター |
|
残基名、残基番号、原子名 |
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)]'
# 正しい: 整数インデックスは内側のクォート不要
-s '[(1, 5, 1.30, 3.10), (2, 8, 1.20, 3.20)]'
# 非推奨: 外側をダブルクォートにすると内側のクォートをエスケープする必要あり
-s "[(\"TYR,285,CA\",\"MMT,309,C10\",1.30,3.10),...]"
ワークフロー¶
入力と事前最適化 – 酵素 PDB を読み込み、電荷/スピンを解決し、ML/MM 計算機（MLIP バックエンド + hessian_ff）を構築し、
--preoptの場合は任意でバイアスなし事前最適化を実行。-b/--backendで ML バックエンドを選択（デフォルト:uma）、--embedchargeで xTB 点電荷埋め込み補正を有効化可能。グリッド構築 –
-s/--scan-lists（YAML/JSON スペックファイルまたはインラインリテラル）からターゲットを 2 つの四つ組に解析し、インデックスを正規化（デフォルト 1 始まりまたは"TYR,285,CA"のような PDB 原子セレクター）。ceil(|high - low| / h) + 1点の線形グリッドを構築（h = --max-step-size）。外側ループ（d1） – 各 d1 値について、d1 拘束のみで系を緩和。
内側ループ（d2） – 現在の d1 での各 d2 値について、最も近い収束済み構造から開始し両方の拘束で緩和。
エネルギー評価 – 各 (i, j) ペアで ML/MM エネルギーをバイアスなしで評価し
surface.csvに記録。可視化 –
scan2d_map.png（2D コンター）とscan2d_landscape.html（3D サーフェス）を書き出し。--zmin/--zmaxでカラースケールをクランプ。ベースライン:--baseline minは最小エネルギーをゼロに;--baseline firstは (i=0, j=0) グリッド点をゼロに。
CLI オプション¶
オプション |
説明 |
デフォルト |
|---|---|---|
|
入力酵素複合体 PDB（必須）。 |
必須 |
|
酵素の Amber parm7 トポロジー（必須）。 |
必須 |
|
ML 領域を定義する PDB。 |
None |
|
ML 領域のカンマ区切り原子インデックス（範囲指定可）。 |
None |
|
|
|
|
入力 PDB の B 因子から ML/MM レイヤーを検出。 |
|
|
ML 領域の総電荷。 |
None（ |
|
残基ごとの電荷マッピング（例: |
None |
|
スピン多重度 (2S+1)。 |
|
|
凍結する 1 始まりカンマ区切りインデックス。 |
None |
|
ML 領域からの距離カットオフ (Å) — ヘシアン計算に含める MM 原子を指定。 |
None |
|
ML 領域からの可動 MM 原子の距離カットオフ (Å)。指定すると |
None |
|
スキャンターゲット: YAML/JSON スペックファイルパス（自動検出、 |
必須 |
|
|
|
|
|
|
|
ステップごとの最大距離増分 (Å)。グリッド密度を決定。 |
|
|
調和ウェル強度 k (eV/Ų)。 |
|
|
バイアス緩和ごとの最大 LBFGS サイクル。 |
|
|
d1 スライスごとの内側 d2 スキャン TRJ を書き出し。 |
|
|
基本出力ディレクトリ。 |
|
|
収束プリセット（ |
|
|
ベース YAML 設定ファイル（最初に適用）。 |
None |
|
|
None |
|
スキャン前にバイアスなし事前最適化を実行。 |
|
|
相対エネルギーの基準（kcal/mol）。 |
|
|
コンターカラースケールの下限（kcal/mol）。 |
自動スケール |
|
コンターカラースケールの上限（kcal/mol）。 |
自動スケール |
|
ML 領域の MLIP バックエンド: |
None（内部で |
|
xTB 点電荷埋め込み補正の有効化。MM 環境から ML 領域への静電的影響を考慮。 |
|
|
xTB 埋め込み用 MM 原子のカットオフ半径（Å）。 |
|
|
PDB テンプレート利用可能時の XYZ/TRJ から PDB コンパニオン生成の切り替え。 |
|
出力¶
out_dir/ (デフォルト:./result_scan2d/)
├── surface.csv # PES グリッド: i, j, d1_A, d2_A, energy_hartree, energy_kcal, bias_converged
├── scan2d_map.png # 2D コンターマップ
├── scan2d_landscape.html # 3D サーフェス可視化（Plotly）
├── grid/
│ ├── point_i###_j###.xyz # 各 (i, j) ペアの緩和ジオメトリ
│ ├── point_i###_j###.pdb # PDB コンパニオン（入力が PDB の場合）
│ ├── preopt_i###_j###.xyz # 事前最適化構造（--preopt 時）
│ └── inner_path_d1_###_trj.xyz # d1 スライスごとの内側 d2 軌跡（--dump 時）
└── (stdout) # 進捗とエネルギーサマリー
YAML 設定¶
geom:
coord_type: cart
freeze_atoms: []
calc:
charge: 0
spin: 1
mlmm:
real_parm7: real.parm7
model_pdb: ml_region.pdb
opt:
thresh: baker
max_cycles: 10000
dump: false
out_dir: ./result_scan2d/
lbfgs:
max_step: 0.3
out_dir: ./result_scan2d/
bias:
k: 300.0