irc¶
遷移状態（TS）から反応物・生成物方向へ EulerPC（Euler Predictor-Corrector）ベースの固有反応座標（IRC）積分を実行します。tsopt で最適化・検証済みの TS 構造を出発点に経路を追跡し、端点接続性（R ↔ TS ↔ P）を確認します。デフォルトで前方・後方の両方向を実行します。--no-backward（または --no-forward）で一方向のみをたどります。Hessian のデフォルトは有限差分です。解析 autograd の速度とメモリ量は backend・model・系サイズ・precision・GPU に依存するため、対象環境で検証した場合にだけ明示的に選択してください。mmCIF入力は内部PDBで計算し、出力CIFに元IDを復元します。XYZ/GJF入力では--ref-pdbにPDBまたはmmCIF topologyを指定できます。一般的な手順は tsopt → irc です。
実行例¶
コマンド形式:
pdb2reaction irc -i INPUT.{pdb|xyz|trj|...} [-q CHARGE] [-l, --ligand-charge <number|'RES:Q,...'>] \
[-b/--backend uma|orb|mace|aimnet2] \
[--workers N] [--workers-per-node N] [-m 2S+1] \
[--max-cycles N] [--step-size Δs] [--never-stop/--no-never-stop] [--root k] \
[--forward/--no-forward] [--backward/--no-backward] \
[--freeze-links/--no-freeze-links] \
[--out-dir DIR] [--config FILE] \
[--convert-files/--no-convert-files] [--ref-pdb FILE] \
[--hessian-calc-mode Analytical|FiniteDifference] \
[--show-config] [--dry-run]
両方向の基本実行:
pdb2reaction irc -i ts.pdb -q 0 -m 1 --max-cycles 50 --out-dir ./result_irc
順方向のみ、有限差分 Hessian、大きいステップサイズ:
# 順方向のみ、有限差分Hessian、大きいステップサイズ
pdb2reaction irc -i ts.pdb -q 0 -m 1 --no-backward \
--step-size 0.2 --hessian-calc-mode FiniteDifference --out-dir ./irc_fd/
解析 Hessian を明示的に使用:
# UMAで解析Hessianを明示する場合はworkersを1にする
pdb2reaction irc -i ts.pdb -q 0 -m 1 \
--hessian-calc-mode Analytical --out-dir ./result_irc_analytical
分岐が1〜2 stepですぐ停止する場合は、まずEulerPCの最大stepを小さくします。
再試行の目安は0.05 Bohrです。
pdb2reaction irc -i ts.pdb -q 0 -m 1 --step-size 0.05 \
--out-dir ./result_irc_small_step
すべての物理的な端点判定を無視して追跡する場合は
--never-stopを追加します。このopt-inモードはRMS-gradient、
hard-gradient、energy上昇、energy変化量による停止を無視します。
数値／integration失敗や外部中断がなければ--max-cyclesまで進みます。
pdb2reaction irc -i ts.pdb -q 0 -m 1 --step-size 0.05 --never-stop \
--max-cycles 250 --out-dir ./result_irc_continue
処理の流れ¶
入力準備 – 共通bridgeがPDB/mmCIFと
geom_loader対応形式を受け入れます。参照topologyがある場合は軌跡をPDBへ変換し、bridge入力では元IDを復元したCIFも生成します。--freeze-linksはcap水素の親原子を凍結します。EulerPC 積分 – EulerPC 予測子-修正子積分器が遷移状態から IRC 経路をたどります。
--forward/--backwardフラグに従って順方向および/または逆方向の分岐を実行します。初期モード選択前に、デフォルトのconstrainedが凍結anchorを動かさない全系並進・回転だけを除去します。各ステップでは、質量加重の最急降下方向に沿う Euler 予測子（勾配は現在の Hessian を用いた 2 次の Taylor 展開で近似）を適用し、続いて距離加重補間（DWI）面上で修正 Bulirsch–Stoer 修正子を適用します。軌跡出力 – 完了済み、順方向、逆方向の IRC 軌跡をXYZへ書きます。参照topologyと
--convert-filesがあればPDB、bridge入力ならCIF companionも生成します。
出力¶
out_dir/ (デフォルト:./result_irc/)
├─ <prefix>finished_irc_trj.xyz # 完全な IRC 軌跡
├─ <prefix>finished_first.xyz # endpoint comparison に使う最初の生 endpoint
├─ <prefix>finished_last.xyz # endpoint comparison に使う最後の生 endpoint
├─ <prefix>finished_irc.pdb # 参照 PDB が利用可能な場合の軌跡に対応する PDB（変換有効時）
├─ <prefix>finished_irc.cif # bridge入力。元IDを復元
├─ <prefix>forward_irc_trj.xyz # 順方向分岐が実行された場合
├─ <prefix>forward_irc.pdb # 順方向分岐に対応する PDB（同条件）
├─ <prefix>forward_irc.cif # bridge入力
├─ <prefix>backward_irc_trj.xyz # 逆方向分岐が実行された場合
├─ <prefix>backward_irc.pdb # 逆方向分岐に対応する PDB（同条件）
└─ <prefix>backward_irc.cif # bridge入力
finished_first.xyz と finished_last.xyz は方向付き endpoint artifact
です。first/last の順序だけでは化学的な R/P identity は決まりません。
irc.prefixが空でない場合、EulerPCはファイル名との間に_を1つ補います。たとえば
prefix: trialはtrial_finished_irc_trj.xyzを生成し、result.json.filesにも
正規化後の名前を記録します。
低レベルの周期 HDF5 checkpoint は YAML でのみ有効化できます。
irc.dump_every のデフォルトは null で、正の値を指定した場合だけ
<prefix>irc_data.h5 を作成します。このファイルは現在方向の座標・
エネルギー・勾配で上書きされるもので、最終的な双方向 IRC 成果物ではなく、
Hessian を含まず、result.json.files にも登録しません。
コンソールには確定済みの geom/calc/irc 設定と実行時間の要約が表示されます。
CLI オプション¶
以下の表は説明が必要なオプションを扱います。全フラグの一覧は生成された コマンドリファレンス にあります。
オプション |
説明 |
デフォルト |
|---|---|---|
|
|
必須 |
|
総電荷。明示的な |
YAML/テンプレート/導出がない限り必須 |
|
単一の整数（例: |
None |
|
UMA 予測器の並列度。 |
|
|
ノードあたりのワーカー数。並列予測器に渡されます |
|
|
スピン多重度（2S+1）。明示的な |
YAML/ |
|
最大 IRC ステップ。明示値は YAML |
|
|
ステップ長（Bohr、非質量加重デカルト座標）。明示値は YAML |
|
|
RMS-gradient、hard-gradient、energy上昇、1 stepのenergy変化量による停止（ |
|
|
射影 Hessian の固有値を昇順（最も負の値を先頭）に並べたときの0 始まりのインデックス。初期 IRC 変位に使用するモードを指定します。虚振動が 1 個だけの妥当な TS では |
|
|
順方向分岐を実行。明示 toggle は YAML |
|
|
逆方向分岐を実行。明示 toggle は YAML |
|
|
射影 Hessian の正定値性を IRC 収束条件に加える opt-in guard。肩を収束と誤認する可能性がある場合に有効化 |
|
|
PDB/mmCIF トポロジー用、キャップ H 親を凍結（ |
|
|
凍結する原子の 1 始まりインデックスをカンマ区切りで明示的に指定（例: |
None |
|
出力ディレクトリ。明示値は YAML |
|
|
参照PDB/mmCIF topologyがある場合の XYZ/TRJ → PDB/CIF を切り替え |
|
|
XYZ/GJF入力に使用する参照PDBまたはmmCIF topology |
None |
|
MLIP Hessian モード。明示値は YAML |
|
|
明示 CLI 適用前に読み込むベース YAML |
None |
|
解決済み YAML レイヤー/設定を表示して続行 |
|
|
|
|
|
MLIP バックエンド |
|
|
実行せずに検証と実行計画のみ表示 |
|
YAML 設定¶
設定の優先順位は CLI 規約: 設定の優先順位 を参照してください。
geom、calc、irc の各セクションは YAML リファレンス の正規定義から変更ありません: geom、calc、irc を参照してください。--freeze-links は PDB/mmCIF トポロジーで geom.freeze_atoms を拡張し、--hessian-calc-mode と CLI の charge/spin 値はマージ済み calc ブロックを補完します。
irc 固有の強制上書き（YAML/CLI マージ後に YAML 値を無視して適用）:
geom:
coord_type: cart # irc では cart に強制（YAML 値は無視）
calc:
return_partial_hessian: true # irc では true に強制（partial Hessian、active-DOF 処理）
終了コード¶
終了コードは CLI 規約の 終了コード を参照。
注意事項¶
MLIP バックエンド（デフォルト: UMA）は IRC 全体で再利用されます。
step_lengthを大きくし過ぎると EulerPC が不安定になることがあります。ほぼ直ちに停止する分岐は、まず小さい--step-size（例:0.05）で再試行してください。--never-stopはデフォルトOFFです。有効時は物理的端点で収束宣言せずcycle上限まで進むため、軌跡と端点接続を確認してください。--freeze-linksが有効な場合、キャップ水素の親原子が自動的に凍結されます（キャップ水素と凍結原子 を参照）。result.json["rigid_projection"]にtreatment、effective rank、初期 Hessian のsourceとshapeを記録します。詳細は凍結原子を参照してください。
関連項目¶
典型エラー別レシピ – 症状起点の切り分け
トラブルシューティング — よくある失敗モードの詳細な対処
tsopt — IRC 実行前に TS を最適化
freq — 完全な振動解析と熱化学補正
opt — IRC 端点を真の極小に最適化
all — tsopt 後に IRC を実行する一気通貫ワークフロー
YAML リファレンス —
ircの完全な設定オプション用語集 — IRC（固有反応座標）の定義