irc

mlmm irc は ML/MM calculatorを用いた EulerPC ベースの IRC（固有反応座標）積分により、遷移状態から反応物・生成物の方向へ経路を追跡します。最適化された TS が期待どおり反応物と生成物を接続するかを検証したいとき、あるいは下流の熱化学計算 / DFT 単点計算用の反応物 / 生成物構造を生成したいときに使用します。典型的には tsopt -> freq（1 つの虚振動数モードを確認）-> irc というワークフローで実行します。デフォルトでは正方向と逆方向の両方のブランチが計算されます。CLI は意図的に最小限に絞っており、コマンドラインに用意されていないパラメータは YAML で提供し、実行を明示的かつ再現可能に保つべきです。入力は pysisyphus.helpers.geom_loader で読み取り可能な任意の構造（.pdb、.xyz、_trj.xyz、…）です。入力が .pdb の場合、生成される軌跡は追加で PDB に変換されます。

実行例

最小構成で TS の PDB から実行:

mlmm irc -i ts.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 --no-detect-layer -q 0 -m 1 --max-cycles 50 --out-dir ./result_irc

正方向のみ実行:

mlmm irc -i ts.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 --no-backward --out-dir ./result_irc_forward

ステップサイズを増やして解析的Hessianを使用:

mlmm irc -i ts.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 --no-detect-layer -q 0 -m 1 --step-size 0.20 \
 --hessian-calc-mode Analytical --out-dir ./result_irc_analytical

両ブランチを保持してステップ上限を引き上げ:

mlmm irc -i ts.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 --no-detect-layer -q 0 -m 1 --max-cycles 150 \
 --out-dir ./result_irc_long

コマンド形式:

mlmm irc -i TS_STRUCTURE --parm PARM7 --model-pdb ML_REGION [options]

mlmm irc --help でコアオプションを、mlmm irc --help-advanced で全オプション一覧を表示します。

処理の流れ

1. 入力準備 – TS 構造、Amber トポロジー（--parm）、ML 領域定義（--model-pdb / --model-indices）を読み込み、電荷とスピンを確定します。geom_loader でサポートされる任意の形式を受け付けます。参照 PDB が利用可能な場合（入力が .pdb または --ref-pdb 指定時）、EulerPC 軌跡はそのトポロジーを使用して PDB に変換されます。

2. ML/MM calculatorの構築 – --parm と --model-pdb から ML/MM calculatorを構築します。-b/--backend で ML バックエンドを選択し（デフォルト: uma）、--hessian-calc-mode は MLIP Hessian評価を制御します。--embedcharge で xTB 点電荷埋め込み補正を有効化できます。

3. IRC 積分 – EulerPC 積分器が両方向に沿って IRC を伝播します（--no-forward または --no-backward でブランチを無効化可能）。ステップサイズとサイクル数で積分長を制御します。

4. 出力と変換 – 軌跡は XYZ で書き出されます。PDB テンプレートが利用可能で --convert-files が有効な場合、対応する PDB が生成されます。

出力

out_dir/ (デフォルト: ./result_irc/)
├─ <prefix>irc_data.h5              # irc.dump_every ステップごとに書き出される HDF5 ダンプ
├─ <prefix>finished_irc_trj.xyz     # 完全 IRC 軌跡（XYZ/TRJ）
├─ <prefix>forward_irc_trj.xyz      # 正方向パスセグメント
├─ <prefix>backward_irc_trj.xyz     # 逆方向パスセグメント
├─ <prefix>finished_irc.pdb         # PDB 変換（入力が .pdb または --ref-pdb 指定時）
├─ <prefix>forward_irc.pdb          # PDB 変換（入力が .pdb または --ref-pdb 指定時）
├─ <prefix>backward_irc.pdb         # PDB 変換（入力が .pdb または --ref-pdb 指定時）
├─ <prefix>forward_last.xyz         # 正方向 IRC 終点（XYZ、単一フレーム）
├─ <prefix>forward_last.pdb         # 正方向 IRC 終点（PDB、利用可能時）
├─ <prefix>backward_last.xyz        # 逆方向 IRC 終点（XYZ、単一フレーム）
└─ <prefix>backward_last.pdb        # 逆方向 IRC 終点（PDB、利用可能時）

主に確認するファイル:

• result_irc/finished_irc_trj.xyz

• result_irc/forward_irc_trj.xyz

CLI オプション

オプション	説明	デフォルト
-b, --backend CHOICE	ML バックエンド: uma（デフォルト）、orb、mace、aimnet2。	uma
--embedcharge/--no-embedcharge	xTB 点電荷埋め込み補正（実験的機能）の有効化。MM 環境から ML 領域への静電的影響を考慮。	False
--embedcharge-cutoff FLOAT	xTB 埋め込み用 MM 原子のカットオフ半径（Å）。	12.0
--cmap/--no-cmap	model parm7 に CMAP（骨格クロスマップ二面角補正）を含めるかどうか。デフォルト: 無効（Gaussian ONIOM と同一）。	--no-cmap
--hess-device CHOICE	初期Hessianの格納・IRC演算のデバイス: auto、cuda、cpu。大規模非凍結系では cpu を推奨。	auto
--read-hess PATH	.npz ファイルから初期Hessianを読み込み（mlmm freq --dump-hess で出力）。hessian_cache および新規計算より優先。	None
-i, --input PATH	構造ファイル（.pdb/.xyz/_trj.xyz/…）。geom_loader で読み取り可能な任意の形式。	必須
--parm PATH	全酵素/MM 領域の Amber トポロジー。YAML の calc.real_parm7 が無い場合は必須。	None
--model-pdb PATH	ML 領域を定義する PDB。--no-detect-layer かつ --model-indices 未指定時は必須。	None
--model-indices TEXT	ML 領域原子インデックス（カンマ区切り、範囲指定可: 1-10,15）。--model-pdb 省略時に使用。	None
--model-indices-one-based/--model-indices-zero-based	--model-indices を 1 始まり/0 始まりとして解釈。	True（1 始まり）
--detect-layer/--no-detect-layer	入力 PDB の B 因子（B=0/10/20）から ML/MM レイヤーを検出。	True
-q, --charge INT	総電荷。YAML の calc.charge を上書き。	None（-l 未指定時は必須）
-l, --ligand-charge TEXT	残基ごとの電荷マッピング（例: GPP:-3,SAM:1）。-q 省略時に合計電荷を導出。	None
-m, --multiplicity INT	スピン多重度 (2S+1)。calc.spin を上書き。	1
--max-cycles INT	IRC ステップの最大数。irc.max_cycles を上書き。	125
--step-size FLOAT	ステップ長（Bohr、非質量加重デカルト座標）。irc.step_length を上書き。	0.10
--root INT	初期変位の虚振動数モードインデックス。irc.root を上書き。	0
--forward/--no-forward	正方向 IRC を実行。irc.forward を上書き。	True
--backward/--no-backward	逆方向 IRC を実行。irc.backward を上書き。	True
-o, --out-dir PATH	出力ディレクトリ。irc.out_dir を上書き。	./result_irc/
--ref-pdb FILE	--input が XYZ の場合に使用する参照 PDB トポロジー（XYZ 座標を保持）。	None
--convert-files/--no-convert-files	参照 PDB が利用可能な場合に XYZ/TRJ を対応する PDB へ変換するかの切り替え。	True
--hessian-calc-mode CHOICE	MLIP がHessianを構築する方法（Analytical または FiniteDifference）。calc.hessian_calc_mode を上書き。	FiniteDifference
--config FILE	明示 CLI 適用前に読み込むベース YAML。	None
--show-config/--no-show-config	解決済み YAML レイヤー/設定を表示して続行。	False
--mm-backend [hessian_ff|openmm]	MM バックエンド（hessian_ff: 解析的Hessian / openmm: 有限差分Hessian）。	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
--dry-run/--no-dry-run	実行せずに検証と実行計画のみ表示。--help-advanced に表示。	False

YAML 設定

マージ順 デフォルト < config < 明示CLI < override でマッピングを提供します。 共有セクションはジオメトリ/計算機キーについて YAML リファレンス を再利用します。irc では YAML/CLI マージ後に geom.coord_type が cart に強制されます。calc.return_partial_hessian は明示的な YAML 指定が無い場合に true がデフォルト適用されます（active-DOF 処理を伴う partial Hessian）。

CLI から YAML へのマッピング

CLI オプション	YAML キー
--charge	calc.charge
--multiplicity	calc.spin
--step-size	irc.step_length
--max-cycles	irc.max_cycles
--root	irc.root
--forward	irc.forward
--backward	irc.backward
--out-dir	irc.out_dir
--hessian-calc-mode	calc.hessian_calc_mode

YAML 例

geom:
 coord_type: cart                  # irc では cart に強制（YAML 値は無視）
 freeze_atoms: []                  # 1 始まり凍結原子（CLI/リンク検出とマージ）
calc:
 charge: 0                         # 総電荷（CLI 上書き）
 spin: 1                           # スピン多重度 2S+1
mlmm:
 real_parm7: real.parm7            # Amber parm7 トポロジー
 model_pdb: ml_region.pdb          # ML 領域定義
 backend: uma                      # ML バックエンド (uma/orb/mace/aimnet2)
 embedcharge: false                # xTB 点電荷埋め込み補正
 uma_model: uma-s-1p1              # uma-s-1p1 | uma-m-1p1
 uma_task_name: omol                # UMA タスク名 (backend=uma 時)
 ml_device: auto                   # ML デバイス選択
 hessian_calc_mode: Analytical         # Hessianモード選択
 return_partial_hessian: true      # irc では true に強制（partial Hessian、active-DOF 処理）
irc:
 step_length: 0.1                  # 積分ステップ長
 max_cycles: 125                   # IRC に沿った最大ステップ数
 downhill: false                   # 下り方向のみに追従
 forward: true                     # 正方向に伝播
 backward: true                    # 逆方向に伝播
 root: 0                           # 基準振動ルートインデックス
 hessian_init: calc                # Hessian初期化ソース
 displ: energy                     # 変位構築方法
 displ_energy: 0.001               # エネルギーベースの変位スケーリング
 displ_length: 0.1                 # 長さベースの変位フォールバック
 rms_grad_thresh: 0.001            # RMS 勾配収束閾値
 hard_rms_grad_thresh: null        # ハード RMS 勾配停止
 energy_thresh: 0.000001           # エネルギー変化閾値
 imag_below: 0.0                   # 虚振動数カットオフ
 force_inflection: true            # 変曲点検出を強制
 check_bonds: false                # 伝播中の結合チェック
 out_dir: ./result_irc/            # 出力ディレクトリ
 prefix: ""                        # ファイル名プレフィックス
 hessian_update: bofill            # Hessian更新方式
 hessian_recalc: null              # Hessian再構築間隔
 max_pred_steps: 500               # 予測子-補正子の最大ステップ数
 loose_cycles: 3                   # 厳密化前のゆるいサイクル数
 corr_func: mbs                    # 相関関数の選択

完全なスキーマ（すべての irc キーとデフォルト）: YAML リファレンス。

注記

• デフォルトでは両方のブランチを実行します。片方向のみが必要な場合は --no-forward または --no-backward で一方を無効化します。

関連項目

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

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

• tsopt – IRC 実行前に TS を最適化

• freq – TS 候補が 1 つの虚振動数を持つことを検証; IRC 端点を解析

• opt – IRC 端点を真の極小に最適化

• all – tsopt の後に IRC を実行する一気通貫ワークフロー

• YAML リファレンス – irc の完全な設定オプション

• 用語集 – IRC（固有反応座標）の定義