freq

層を定義した酵素 PDB に対して、PHVA（部分 Hessian 振動解析、partial-Hessian vibrational analysis）対応の ML/MM 振動解析と熱化学（ZPE、Gibbs エネルギー等）を計算します。

mlmm freq を使う場面:

• 最適化した極小、遷移状態（TS）、IRC 端点の停留点としての性質を検証する（極小は虚振動数を持たず、遷移状態はちょうど 1 つ持ちます）。

• QRRHO（quasi-rigid-rotor-harmonic-oscillator）熱化学を計算する。

mlmm freq は ML/MM calculator（mlmm.backends.mlmm_calc.mlmm）による振動解析を実行し、PHVA により凍結原子を扱えます。基準振動軌跡を _trj.xyz と .pdb（酵素の原子順序にマップバック）としてエクスポートし、オプションの thermoanalysis パッケージがインストールされている場合は Gaussian スタイルの熱化学サマリーを出力します。

虚振動数は負の値で表示されます。runtime と memory は backend と系に 依存するため、代表的な pilot で Analytical と FiniteDifference を比較してください。

実行例

基本的な振動解析:

mlmm freq -i pocket.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --out-dir ./result_freq

まずは出力モード数を絞って確認する:

mlmm freq -i pocket.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --max-write 6 --out-dir ./result_freq_quick

凍結原子を指定した PHVA と熱化学ダンプを実行する:

mlmm freq -i pocket.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --freeze-atoms "1,3,5,7" --dump --out-dir ./result_freq_phva

VRAM に余裕があるノードで解析的 Hessian を使う:

mlmm freq -i pocket.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --hessian-calc-mode Analytical --out-dir ./result_freq_analytical

処理の流れ

1. ML/MM calculatorの構築 — ML 領域は --model-pdb で提供され、Amber パラメータは --parm から読み取られます。--hessian-calc-mode は解析的または有限差分の Hessian を選択します。計算機は完全な 3N x 3N Hessian またはアクティブ自由度（DOF）のサブブロックを返す場合があります。

2. PHVA と TR（並進/回転、translation/rotation）射影 — 凍結原子がある場合、固有解析はアクティブ部分空間内で行われます。デフォルトの constrained 射影は、凍結 anchor をすべて動かさない全系剛体運動のみを除去し、アクティブ断片を孤立分子として扱いません。3N x 3N とアクティブブロックの両方の Hessian を受け付け、振動数は cm^-1 で報告します（負の値 = 虚振動数）。

3. アクティブ自由度モード — --active-dof-mode は振動解析に含まれる原子を制御します: all（全原子）、ml-only（ML 層、B=0）、partial（ML + MovableMM、デフォルト）、unfrozen（非凍結層、通常 B=0/10）。

4. モードエクスポート — --max-write は出力するモード軌跡数を制限します。モードは値（または --sort abs で絶対値）でソートされます。エクスポートされた各モードは、酵素の原子順序にマップバックした _trj.xyz と .pdb 軌跡を書き出します。正弦波軌跡の振幅（--amplitude-ang）とフレーム数（--n-frames）は YAML のデフォルト値と同じです。

5. 熱化学 — thermoanalysis がインストールされている場合、PHVA 振動数を使用した QRRHO ライクなサマリー（E、ZPE、E/H/G 補正、熱容量、エントロピー）が出力されます。構造の Gibbs free energy は Hartree 単位で E + G_corr = G（電子エネルギー + Gibbs free-energy 補正 = Gibbs free energy）と明示します。CLI の圧力（atm）は内部で Pa に変換されます。解析対象構造ごとに分子点群と外部回転対称数を自動判定し、1/σ 補正を常に適用します。必要な場合に限り、YAML の thermo.symmetry_number で判定値を上書きできます。--dump の場合、thermoanalysis.yaml スナップショットも書き出されます。振動数処理ポリシー: freq は standalone-freq ポリシー（QRRHO、rotor cutoff 100 cm⁻¹、周波数・ZPE スケール 1、虚振動数の反転なし、正振動数のフロアなし）を適用します。これは一部の bundled-engine 経路が使う内部の Geometry.get_thermoanalysis ポリシー（小さな虚振動数を −15 cm⁻¹ から反転し、25 cm⁻¹ 未満の正振動数をフロアする）とは意図的に異なります。いずれも普遍的な科学的デフォルトではなく、各エントリポイントに固有です。有効なポリシー（kind、rotor_cutoff_cm、frequency_scale、zpe_scale、invert_imag_from_cm、positive_frequency_floor_cm）は thermoanalysis.yaml と result.json の thermo_policy にシリアライズされます。

6. デバイス選択 — ml_device="auto" は CUDA が利用可能な場合は CUDA を使用し、それ以外は CPU を使用します。内部の TR 射影/モード組み立ては転送を抑えるため同じデバイスで実行されます。

7. 終了動作 — キーボード割り込みはコード 130 で終了します。その他の失敗はトレースバックを出力してコード 1 で終了します。

凍結境界の TR 射影

PHVA は固定の constrained 処理を使用します。 全系の剛体並進/回転から、凍結 anchor を動かさない成分だけを残します。 一般的な有効 rank は次のとおりです。

凍結 anchor の幾何	除去する有効 rank
0 個	6
1 個	3
異なる 2 個	1
非共線の 3 個以上	0

実用的な ML/MM 境界には通常、非共線の anchor が複数あるため、 有効 rank は通常 0 で、アクティブ部分空間の方向は除去されません。 全原子を凍結するとアクティブ自由度が無いため、明示的なエラーになります。

geom.tr_projection の古い非constrained値は明示的に拒否されます。 直線、共線、同一座標など rank が退化する構造も現行 kernel で処理され、 bitwise 一致は保証しません。

--out-json 時は result.json.rigid_projection に treatment、有効 rank、 Hessian source、Hessian shape を記録します。--dump 時は同じ provenance を thermoanalysis.yaml に記録します。

出力

out_dir/ (デフォルト: ./result_freq/)
├─ result.json                      # --out-json 時。rigid_projection provenance を含む
├─ mode_XXXX_±freqcm-1_trj.xyz   # モードごとの正弦波軌跡
├─ mode_XXXX_±freqcm-1.pdb       # 酵素原子順序にマップバックされた PDB 軌跡
├─ frequencies_cm-1.txt           # 選択されたソート順での全振動数リスト
└─ thermoanalysis.yaml            # thermoanalysis がインポート可能で --dump が True の場合

• コンソールには確定した geom、calc、freq、熱化学設定をまとめたブロックが出力されます。

出力の確認ポイント:

• result_freq/frequencies_cm-1.txt

• result_freq/mode_*_trj.xyz

• result_freq/mode_*.pdb（PDB 入力の場合）

CLI オプション

mlmm freq --help でコアオプション、mlmm freq --help-advanced で全オプションリストを表示します。全フラグは自動生成された コマンドリファレンス にあります。以下の表は説明が必要なオプションを扱います。

オプション	説明	デフォルト
入力と電荷
-i, --input PATH	完全酵素 PDB（リンク原子なし）。	必須
--parm PATH	完全酵素の Amber parm7 トポロジー。	必須
--model-pdb PATH	ML 領域を定義する PDB。--detect-layer 有効時はオプション。	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	入力 PDB の B 因子から ML/MM 層を自動検出。	有効
-q, --charge INT	ML 領域の電荷。	None（-l 未指定時は必須）
-l, --ligand-charge TEXT	残基ごとの電荷マッピング（例: GPP:-3,SAM:1）。-q 省略時に合計電荷を導出。	None
-m, --multiplicity INT	スピン多重度 (2S+1)。	1
--ref-pdb FILE	非 PDB 入力用の参照 PDB トポロジー。	None
バックエンドと計算
-b, --backend CHOICE	ML バックエンド: uma（デフォルト）、orb、mace、aimnet2。	uma
--precision [fp32|fp64]	MLIP バックエンド精度。省略時は UMA/AIMNet2 fp32、ORB/MACE fp64。AIMNet2 は fp64 を拒否。	バックエンド依存
--workers INT	UMA predictor worker 数。2 以上は fairchem-core[extras] が必要で、Analytical と併用不可。	1
--workers-per-node INT	UMA 並列 predictor のノード当たり worker 数。	None
--mm-backend [hessian_ff|openmm]	MM バックエンド。Hessian 構築法は calc.mm_fd が別に制御します（デフォルト true: 有限差分）。	hessian_ff
--link-atom-method [scaled|fixed]	リンク原子配置: scaled（g 因子）または fixed（1.09/1.01 Å）。	scaled
--out-json/--no-out-json	機械可読な result.json を out_dir に書き出す。	False
--cmap/--no-cmap	REAL と MODEL の両 MM 層で CMAP を保持します。	--cmap
--hess-device CHOICE	評価後 Hessian の配置/対角化 device: auto、cuda、cpu。Hessian 評価/assembly 自体は移動せず、cpu は評価済み行列を対角化前に移動。	auto
アクティブ領域の凍結と Hessian
--freeze-atoms TEXT	1 始まりカンマ区切りの凍結原子インデックス。	None
--active-dof-mode CHOICE	アクティブ自由度選択: all、ml-only、partial、unfrozen。	partial
--hess-cutoff FLOAT	Hessian 対象 MM 原子のカットオフ距離。	None
--movable-cutoff FLOAT	Movable-MM 層のカットオフ距離。	None
--hessian-calc-mode CHOICE	Hessian モード（Analytical または FiniteDifference）。	FiniteDifference
--dump-hess PATH	Hessian、原子順序、Cartesian geometry、active-DOF basis、PHVA metadata、model charge、多重度を.npzへ保存し、一致するmlmm irc --read-hessへ渡す。	None
モードエクスポート
--max-write INT	エクスポートするモード数。	10
--sort CHOICE	モードのソート方法: value（cm^-1）または abs。	value
--amplitude-ang FLOAT	モード軌跡の振幅 (Å)。	0.8
--n-frames INT	モード軌跡のフレーム数。	20
--convert-files/--no-convert-files	PDB テンプレートが利用可能な場合の XYZ/TRJ から対応する PDB への変換の切り替え。	True
熱化学
--temperature FLOAT	熱化学温度 (K)。	298.15
--pressure FLOAT	熱化学圧力 (atm)。	1.0
--dump/--no-dump	thermoanalysis.yaml を書き出し。	False
出力と設定
-o, --out-dir TEXT	出力ディレクトリ。	./result_freq/
--config FILE	明示 CLI 適用前に読み込むベース YAML。	None
--show-config/--no-show-config	確定した YAML レイヤー/設定を表示して続行。	False
--dry-run/--no-dry-run	実行せずに検証と実行計画のみ表示。--help-advanced に表示。	False

受け渡し時に識別情報（identity）を検証します。IRC は、原子順序・座標・ レイヤー選択・Hessian のアクティブ基底・model charge・多重度が異なる ファイルを拒否します。電子状態 identity 導入前の schema 1 は、独立に状態を 確認したうえで IRC に --allow-unverified-hess-state を明示した場合だけ使用できます。

YAML 設定

解析 Hessian を明示した状態で workers > 1 を指定するとエラーになります。 解析曲率には worker 1、UMA 並列 predictor には FiniteDifference を使用してください。

マージ順 デフォルト < config < 明示 CLI でマッピングを提供します。 共有セクションは YAML リファレンス を再利用します。 熱化学制御用の追加 thermo セクションがサポートされます。

geom:
 coord_type: cart                  # 座標タイプ: デカルト vs dlc 内部座標
 freeze_atoms: []                  # 1 始まり凍結原子（CLI/リンク検出とマージ）
 tr_projection: constrained        # 固定の内部 PHVA 処理
calc:
 model_charge: 0                   # 総電荷（CLI 上書き）
 model_mult: 1                     # スピン多重度 2S+1
 real_parm7: real.parm7            # Amber parm7 トポロジー
 model_pdb: ml_region.pdb          # ML 領域定義
 backend: uma                      # ML バックエンド (uma/orb/mace/aimnet2)
 uma_model: uma-s-1p2              # uma-s-1p2 | uma-m-1p1
 uma_task_name: omol                # UMA タスク名 (backend=uma 時)
 ml_device: auto                   # ML デバイス選択
 hessian_calc_mode: FiniteDifference   # 代表的な pilot で両 mode を比較
 out_hess_torch: true              # torch 形式Hessianを要求
 mm_fd: true                       # MM 有限差分トグル
 return_partial_hessian: true      # 部分Hessianを許可（PHVA デフォルト）
freq:
 amplitude_ang: 0.8                # モードの変位振幅 (Å)
 n_frames: 20                      # モードごとのフレーム数
 max_write: 10                     # 書き出す最大モード数
 sort: value                       # ソート順: value vs abs
thermo:
 temperature: 298.15               # 熱化学温度 (K)
 pressure_atm: 1.0                 # 熱化学圧力 (atm)
 symmetry_number: null             # 自動判定。正整数で上書き
 dump: false                       # true の場合 thermoanalysis.yaml を書き出し

関連項目

• tsopt — TS 候補の最適化（freq/IRC で検証; 期待: 1 つの虚振動数）

• opt — 構造最適化（多くの場合 freq の前に実行）

• dft — より高い理論レベルでエネルギーを評価するための DFT 一点計算

• all — --thermo 付き一気通貫ワークフロー

• 典型エラー別レシピ — 症状起点の切り分け

• トラブルシューティング — 詳細なトラブルシューティングガイド

• YAML リファレンス — freq と thermo の完全な設定オプション

• 用語集 — ZPE、Gibbs エネルギー、エンタルピー、エントロピーの定義