凍結原子（Frozen Atoms）¶

概要¶

クラスターモデルでは切り出し境界の少数の原子を固定しないと、最適化器が末端のフラグメントを非物理的な構造へ引き込んでしまいます。pdb2reaction は キャップ水素（extract が切断結合に付加）と、3 通りの freeze_atoms 指定でこれを扱います。

extract サブコマンドでタンパク質から残基を切り出すと、境界の結合は キャップ水素（残基 LKH、原子 HL、元の結合ベクトル方向に 1.09 Å）でキャップされます。キャップ水素の親原子を自由なまま放置すると、勾配降下によってキャップと親原子が一緒に動き、境界形状が変形します。関連する原子を凍結すれば、構造最適化・MEP 探索・IRC・振動解析を通じて境界が固定されます。

凍結原子の 3 通りの指定方法¶

1. `--freeze-links/--no-freeze-links`（デフォルト `True`）¶

extract が付加したキャップ水素の親原子を下表のサブコマンドで自動的に凍結します。sp は link 親を自動凍結せず、明示した geom.freeze_atoms のみを使用します。

pdb2reaction extract -i complex.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' -o model.pdb
pdb2reaction opt -i model.pdb -q 0 -m 1   # --freeze-links は True、LKH 親原子を自動凍結

XYZ/GJF 入力には LKH レコードがないため --freeze-links は無効で、次の 2 つの方法を使ってください。--ref-pdb FILE を渡すと XYZ/GJF 実行が PDB トポロジーを継承し、キャップ水素検出が復活します。

2. `--freeze-atoms 'i,j,k,...'`（CLI 明示指定）¶

カンマ区切りの 1 始まり 原子インデックスで、任意の入力形式に適用できます。--freeze-links と併用すると和集合が凍結されます。

活性部位抽出を伴うallでは、CLIリストとYAML geom.freeze_atomsのどちらも元のfull inputの原子順で指定し、抽出後モデルへ自動変換されます。その他のコマンドでは、そのコマンドへ直接渡した構造の原子順を使います。

pdb2reaction tsopt -i ts_candidate.xyz -q 0 -m 1 \
  --freeze-atoms '12,15,28,29,42'

3. YAML `geom.freeze_atoms`（`--config` 経由）¶

geom:
  freeze_atoms: [12, 15, 28, 29, 42]   # 1 始まりインデックス

リストが長い場合や、設定ファイルに同梱したい場合に便利です。CLI と YAML のリストは置換ではなくマージされます。

pdb2reaction tsopt -i ts.xyz -q 0 -m 1 --config tsopt.yaml

3 つのソースの組み合わせ方¶

実行時に凍結される原子集合は以下の 和集合:

YAML geom.freeze_atoms（--config FILE）
CLI --freeze-atoms
--freeze-links 有効時に検出された LKH 親原子

どれかを優先する仕組みはなく、いずれかのソースに登録された原子はすべて凍結されます。

計算への効果¶

力（Force）: opt / tsopt / scan / freq / irc と path-opt / path-search の --mep-mode gsm では凍結 DOF の力をゼロ化（hard freeze）。
Hessian: 凍結 DOF の行・列は除去される（calc.return_partial_hessian: true。calculator のグローバルデフォルトで、opt / tsopt / scan / freq / irc で再度強制設定）か、フル行列でゼロ化されます。
振動解析: 凍結原子があるとき freq は自動で Partial Hessian Vibrational Analysis（PHVA）を実行し、active ブロックのみ対角化します。剛体モードの扱いは次節を参照してください。
path-opt --mep-mode dmf と path-search --mep-mode dmf（soft restraint）: ゼロ化の代わりに HarmonicFixAtoms（デフォルト k_fix = 300 eV/Å²、ASE 単位系）を各 image に追加し、凍結原子を調和拘束で緩和させます（hard 拘束ではなく、初期座標から微小ずれが生じ得ます）。
MEP / IRC: path-opt / path-search の --mep-mode gsm と irc は解かれた経路 / IRC 軌跡で hard freeze を適用、--mep-mode dmf（path-opt / path-search）は上記 soft restraint を使用。

凍結境界での剛体モード¶

Cartesian PHVA 関連の固有値解析では、全系の剛体運動のうち、すべての凍結anchor（固定点）を動かさない組合せだけを除去します。一般的な非線形構造では、凍結anchorが0、1、2、3個以上（非共線）のとき、effective rankはそれぞれ6、3、1、0です。通常のクラスターモデル境界には非共線なanchorが複数あるため、effective rankは通常0で、active modeを除去しません。

この固定処理はfreq、irc、TSのexact PHVA checkとDimer方向、opt / tsoptのflattenで使用します。MEP からCartesian反応方向を渡すtsopt --ref-modeとは無関係です。全原子を凍結した系にはactiveな振動DOFがないため、明示的なエラーで停止します。

JSON出力を有効にすると、result.json["rigid_projection"]にtreatment、effective rank、Hessian のsourceとshapeを記録します。freq --dumpでは同じprovenanceをthermoanalysis.yamlにも記録します。詳細はJSON出力スキーマを参照してください。

サブコマンド対応表¶

サブコマンド	`--freeze-links`（PDB）	`--freeze-atoms`（任意の入力）	YAML `geom.freeze_atoms`
`extract`	（`LKH/HL` を挿入。フラグは下流用）	n/a	n/a
`opt`	yes	yes	yes
`tsopt`	yes	yes	yes
`freq`	yes（PHVA を起動）	yes	yes
`irc`	yes	yes	yes
`path-opt`	yes	yes	yes
`path-search`	yes	yes	yes
`scan` / `scan2d` / `scan3d`	yes	yes	yes
`all`	yes	yes	yes
`sp`	no	no CLI flag	yes

よくある落とし穴¶

LKH/HL レコードを手動削除した場合: --freeze-links が凍結対象を見つけられません。--freeze-atoms で明示指定するか、extract を再実行してください。
原子インデックスの再番号化: --freeze-atoms と geom.freeze_atoms は1始まりで、対象となる入力の原子順に依存します。allは元のfull inputから抽出モデルへ変換しますが、抽出済みモデルを別コマンドへ直接渡す場合はそのモデルの原子順を使います。
トポロジーなしの XYZ/GJF: LKH レコードが無く --freeze-links は no-op です。--ref-pdb FILE または明示的な --freeze-atoms を使用してください。
--no-freeze-links の使いどころ: 自動凍結を切る診断目的のみ。本番のクラスターモデル実行では --freeze-links を有効のままにしてください。
全原子を凍結した場合: PHVAと IRC には少なくとも1個のactive atomが必要なため、明示的なエラーで停止します。checkを回避せず、freeze setを減らしてください。