tsopt

pdb2reaction tsopt は、遷移状態（TS）候補を一次鞍点に最適化します。虚振動数チェックを内蔵しています。候補には path-opt / path-search の最高エネルギー像（HEI: highest-energy image）、または自前の構造を使えます。

optimizer は --opt-mode で選びます。ほとんどの系では --opt-mode hess（デフォルトの RS-I-RFO: Restricted-Step Image Rational Function Optimization）を使ってください。完全 Hessian を用いるため、一般的により堅牢です。RS-I-RFO で収束しない場合や完全 Hessian の再計算コストが過大な場合は、--opt-mode grad（Hessian-Guided Dimer）に切り替えます。候補に複数の虚振動数があり余分なモードの除去が必要な場合は、--flatten（デフォルト無効）を有効化します。

収束後、tsopt は最終的な Hessian 計算と虚振動数チェックを自動で行います。妥当な TS では虚振動数が ちょうど 1 つ です。別途の freq は、完全な振動解析や熱化学補正が必要な場合にのみ実行します。端点の接続性は必ず irc で確認してください。

TS 初期構造がまず必要な場合は、2 端点なら path-opt、2 構造以上なら path-search を実行し、得られた HEI を tsopt → irc の順で最適化・検証してください。XYZ/GJF 入力では --ref-pdb で参照 PDB トポロジーを指定し、XYZ 座標を保持したまま、形式に応じた PDB/GJF 出力への変換ができます。

命名規則の注意: CLI は grad|dimer（= Dimer）および hess|rsirfo（= RS-I-RFO、デフォルト）を受け付けます。YAML ではトップレベルの hessian_dimer:（Dimer）または rsirfo:（RS-I-RFO）ブロックを直接指定してください。

TS 候補を得る 2 つの経路

tsopt は既に手元にある候補を精密化します。その候補を構築するには補完的な 2 つの方法があり、手元の情報に合わせて選びます。

経路	サブコマンド	使う場面	動作
(a) MEP / 経路探索	path-search	両端点（反応物および生成物）があり、TS を自動でブラケットしたい	再帰的な最小エネルギー経路探索（GSM / DMF）と結合変化検出。多段階経路を自動分割し、各反応区間を精密化し、区間ごとの最高エネルギー像（hei_seg_NN.xyz）を返す
(b) 距離拘束スキャン	scan	反応物のみがある、または特定の反応距離を直接駆動したい	調和距離拘束 E = ½k(r − target)² で各反応距離を完全緩和しながら駆動し、系を TS 候補まで押し上げる

opt --restraint フラグはありません。opt は純粋な無拘束最小化であり、距離拘束による積み上げ経路は scan（--preopt / --endopt で駆動経路まわりの端点を緩和できる）です。いずれの経路で得た候補も tsopt → freq → irc に渡して最適化・検証します。

実行例

PDB 候補のデフォルト RS-I-RFO 最適化:

pdb2reaction tsopt -i ts_cand.pdb -q 0 -m 1 --out-dir ./result_tsopt

dimer モード + 解析的Hessian（VRAM に余裕がある場合）:

# VRAM に余裕がある場合に dimer モード + 解析的Hessianで実行する
pdb2reaction tsopt -i ts_cand.pdb -q 0 -m 1 \
 --opt-mode grad --hessian-calc-mode Analytical --out-dir ./result_tsopt_grad

rsirfo モードを YAML 上書きと併用:

# rsirfo モードを YAML 上書きと併用する
pdb2reaction tsopt -i ts_cand.pdb -q 0 -m 1 \
 --opt-mode hess --config tsopt.yaml --out-dir ./result_tsopt_hess

rsirfo モードで flatten を有効化:

# rsirfo モードで flatten を有効化して実行する
pdb2reaction tsopt -i ts_cand.pdb -q 0 -m 1 \
 --opt-mode hess --flatten --out-dir ./result_tsopt_flatten

最適化軌跡を保存して確認したい場合は --dump を追加します。

処理の流れ

• 電荷/スピン解決: 電荷は標準の優先順位チェーンで解決されます。詳細は CLI 規約: 電荷の指定 を参照してください。

• 構造ロードと freeze-links: 構造は pysisyphus.helpers.geom_loader で読み込まれます。--freeze-links が有効な場合、キャップ水素の親原子は自動的に凍結されます（キャップ水素と凍結原子 を参照）。

• MLIP Hessian（デフォルト: UMA）: --hessian-calc-mode で解析的Hessianと有限差分Hessianを切り替えます。いずれも活性（PHVA）部分空間を考慮します。凍結原子が存在する場合、MLIP バックエンドは活性ブロックのみを返すことがあります。Hessian評価モードの詳細は Hessian評価モード を参照してください。

• Dimer モード詳細:

• Hessian Guided Dimer 段階は、正確なHessian（活性サブスペース、TR 射影）を周期的に評価してダイマー方向を更新します。root == 0 のときは最小固有対に torch.lobpcg を優先し、失敗時は torch.linalg.eigh にフォールバックします。

• --flatten が有効な場合、フラット化ループはΔx とΔg を用い、Bofill（SR1/MS ↔ PSB ブレンド; hessian_dimer.flatten_loop_bofill で切替）で活性Hessianを更新します。各ループは虚振動数モード推定 → 1 回フラット化 → ダイマー方向再更新 → dimer+L-BFGS マイクロ区間 → （任意で）Bofill 更新を実行します。虚振動数モードが 1 つになったら最終的な正確なHessianで振動解析を行います。

• root != 0 の場合は初期ダイマー方向のみその root を使用し、以降の更新は最も負のモード（root = 0）に従います。

• RS-I-RFO モード: RS-I-RFO を実行し、任意のHessian参照や R+S 分割セーフガード、マイクロサイクル制御は rsirfo セクションで設定します。--flatten が有効で収束後も虚振動数モードが複数残る場合、追加モードをフラット化して RS-I-RFO を再実行し、虚振動数モードが 1 つになるか上限に達するまで繰り返します。

• モード出力と変換: 検出された虚振動数モードはすべて vib/imag_*_trj.xyz に書き出されます。PDB 入力で変換が有効な場合は .pdb としても出力されます。最適化軌跡と最終構造は --dump 時に入力テンプレート経由で PDB に変換されます。Gaussian テンプレートでは最終構造のみ .gjf が生成されます。

出力

実行結果は final_geometry.*（最適化された鞍点）と vib/imag_* モード（妥当な TS ではちょうど 1 つ）を開いて検証します。

• result_tsopt/final_geometry.pdb（または final_geometry.xyz）

• result_tsopt/vib/imag_*_trj.xyz

• result_tsopt/vib/imag_*.pdb（PDB 入力の場合）

out_dir/ (デフォルト:./result_tsopt/)
├─ final_geometry.xyz # 常に書き込み
├─ final_geometry.pdb # 入力がPDBの場合（変換有効時）
├─ final_geometry.gjf # 入力がGaussianの場合（変換有効時）
├─ optimization_all_trj.xyz # --dumpがTrueのときの dimer モードダンプ
├─ optimization_all.pdb # PDB 入力の dimer モードに対応する PDB（変換有効時、--dump）
├─ optimization_trj.xyz # --dumpがTrueのときの rsirfo モード軌跡
├─ optimization.pdb # rsirfo モードに対応する PDB（変換有効時、--dump）
├─ vib/
│ ├─ imag_±XXXX.Xcm-1_trj.xyz
│ └─ imag_±XXXX.Xcm-1.pdb
└─.dimer_mode.dat # dimer モード方向シード

終了コードは CLI 規約の 終了コード を参照。

CLI オプション

コマンド形式:

pdb2reaction tsopt -i INPUT.{pdb|xyz|trj|...} [-q CHARGE] [-l, --ligand-charge <number|'RES:Q,...'>] [-m 2S+1] \
 [-b/--backend uma|orb|mace|aimnet2] [--solvent SOLVENT] [--solvent-model alpb|cpcmx] \
 [--opt-mode grad|hess|dimer|rsirfo|trim|rsprfo] [--flatten/--no-flatten] \
 [--freeze-links/--no-freeze-links] [--max-cycles N] [--thresh PRESET] \
 [--hessian-calc-mode Analytical|FiniteDifference] \
 [--convert-files/--no-convert-files] [--ref-pdb FILE]

pdb2reaction tsopt --help でコアオプション、pdb2reaction tsopt --help-advanced で全オプションを表示します。入力ファイルの完全な要件（水素、元素列、原子順序の整合性、電荷指定）は CLI 規約 を参照してください。

オプション	説明	デフォルト
入力と電荷
-i, --input PATH	geom_loader が受け入れる構造ファイル（.pdb / .xyz / .gjf / .trj）	必須
-q, --charge INT	総電荷。.gjf テンプレートまたは --ligand-charge（PDB 入力または --ref-pdb 付き XYZ/GJF）が提供しない限り必須。両方指定時は -q が優先	テンプレート/導出が適用されない限り必須
-l, --ligand-charge TEXT	単一の整数（例: -1）でリガンド総電荷を指定するか、残基別マッピング（例: GPP:-3,SAM:1）で PDB 残基電荷から全系の電荷を導出。-q 省略時に使用（PDB 入力、または --ref-pdb 付き XYZ/GJF）	None
-m, --multiplicity INT	スピン多重度（2S+1）	.gjf テンプレート値または 1
--ref-pdb FILE	入力が XYZ/GJF の場合に使用する参照 PDB トポロジー	None
バックエンドと計算
-b, --backend {uma,orb,mace,aimnet2}	MLIP バックエンド	uma
--workers INT	MLIP 予測器の並列度（workers > 1 で解析Hessian無効）。診断上の注意は workers > 1 は解析Hessianを無効化する（UMA バックエンド） を参照	1
--workers-per-node INT	ノードあたりのワーカー数。並列予測器に渡されます	1
--hessian-calc-mode CHOICE	MLIP Hessianモード（Analytical または FiniteDifference）	FiniteDifference
--solvent TEXT	xTB 暗黙溶媒（例: water）。none で無効化	none
--solvent-model {alpb,cpcmx}	xTB 溶媒モデル	alpb
活性領域の凍結
--freeze-links/--no-freeze-links	PDB 入力（または --ref-pdb 付き XYZ/GJF）。キャップ水素の親を凍結（geom.freeze_atoms にマージ）。キャップ水素の詳細は extract を参照	True
--freeze-atoms TEXT	凍結する原子の 1 始まりインデックスをカンマ区切りで明示的に指定（例: '1,3,5'）。--freeze-links と併用可、任意の入力形式に適用	None
TS optimizer とモード
--opt-mode TEXT	TS optimizer プリセット（Choice: grad / hess / dimer / rsirfo / trim / rsprfo）。grad/dimer → Hessian-Guided Dimer; hess/rsirfo → RS-I-RFO（デフォルト）; trim → TRIM（Helgaker、non-microiter）; rsprfo → RS-P-RFO（Banerjee、non-microiter）。サブコマンド別の対応表（opt は L-BFGS/RFO、tsopt は Dimer/RS-I-RFO）は --opt-mode（サブコマンド依存） を参照	hess
--flatten/--no-flatten	余分な虚振動数モードのフラット化ループを有効化（False は flatten_max_iter=0 を強制）。TS 最適化が収束した後、Hessian行列の余分な負の固有値モードを反復的にフラット化し、虚振動数が 1 つだけ残るか反復上限に達するまで繰り返します。dimer（dimer ループ）および RS-I-RFO（収束後）の両方に適用	False
--coord-type TEXT	最適化座標系（cart / redund / dlc / tric）。cart は公表値の基準となる確実なデフォルト。dlc（非局在内部座標）は低速だが、ねじれの多い系で一次鞍点へより堅牢に収束する。Hessianベースの最適化器が必要（tsopt の RS-I-RFO / Dimer は該当）。path-opt / path-search は cart / dlc のみ受け付ける	cart
--precision [fp32|fp64]	MLIP バックエンド精度。バックエンド固有のキー（UMA precision / ORB precision / MACE default_dtype。aimnet2: fp32 は no-op、fp64 は拒否）へ振り分け。データセンター GPU では数値ノイズの少ない Hessian のために fp64 を使用。再現性: GPU クラスによる精度の選択 を参照	fp32
閾値とサイクル
--thresh TEXT	収束プリセットの上書き（gau_loose、gau、gau_tight、gau_vtight、baker、never）	baker
--max-cycles INT	opt.max_cycles に渡されるマクロサイクル上限	10000
出力と設定
-o, --out-dir TEXT	出力ディレクトリ	./result_tsopt/
--convert-files/--no-convert-files	PDB または Gaussian 入力用の XYZ/TRJ → 対応する PDB/GJF 出力を切り替え	True
--dump/--no-dump	軌跡をダンプ	False
--out-json/--no-out-json	out_dir に機械可読な result.json を書き出す。スキーマは JSON 出力スキーマ を参照	False
--config FILE	明示 CLI オプションより前に適用するベース YAML 設定ファイル	None
--show-config/--no-show-config	解決後の設定レイヤーを表示して実行を継続	False
--dry-run/--no-dry-run	実行せずに入力/設定を検証し、実行計画を表示	False

--flatten 優先順位の注意

Note

--flatten はデフォルトで無効です（優先順位の注意）。 defaults.py では flatten_max_iter: 50 が定義されており（下記インライン YAML 表記でも flatten_max_iter: 50）、それにもかかわらず CLI の初期化器はコマンドラインで --flatten が 明示的に 渡されない限り flatten_max_iter = 0 を強制します。実効値は以下のとおりです:

• CLI --flatten 未指定 → YAML で hessian_dimer.flatten_max_iter を明示的に指定しない限り flatten_max_iter = 0（余剰モード除去ループ無効）。フラット化のカウンタは Dimer・RS-I-RFO のどちらの経路でも hessian_dimer ブロックからのみ読み取られます。defaults.py の値 50 は無視されます。

• CLI --flatten 指定 → YAML / defaults.py の値が有効（デフォルト flatten_max_iter = 50）。引き続き YAML で上書きできます。

TS 候補に複数の虚振動数がある場合は、--flatten を追加して余分なモードの除去ループを有効にしてください。

最適化後に虚振動数の本数が誤っている場合

真の一次鞍点は虚振動数をちょうど 1 つだけ持ち、そのモードは反応座標に沿って変位します（検出閾値 hessian_dimer.neg_freq_thresh_cm、デフォルト 5 cm⁻¹）。tsopt が代わりに偽の 2 本目の小さい虚振動数を報告したり、支配的な反応モードが無い場合は、以下のレバーを段階的に強めます。これらは補完的なので併用できます。

レバー	フラグ	効果
精度を上げる	--precision fp64	よりクリーンな Hessian が数値ノイズ由来の虚振動数モードを除去（データセンター GPU で使用）
内部座標	--coord-type dlc	非局在内部座標。低速だが、ねじれの多い系で一次鞍点へより堅牢に収束
小さいモードのフラット化	--flatten	余分な虚振動数モードのフラット化ループを実行（grad: dimer ループ、hess: RS-I-RFO 後の処理）。--no-flatten は flatten_max_iter = 0 を強制

まず --precision fp64 および／または --coord-type dlc を試し、残った小さいモードは --flatten で除去します。

pdb2reaction tsopt -i ts_candidate.xyz -q -1 -m 1 \
    --precision fp64 --coord-type dlc --flatten -o result_tsopt

例えば、ある変異型コリスミ酸ムターゼの TS は支配的な Claisen モード −223 cm⁻¹ に加え残留 −12.5 cm⁻¹ を伴って収束しましたが、--flatten でクリーンな単一虚振動数の鞍点へ駆動できます。

よくあるエラーのレシピ → 収束・後処理で止まる も参照してください。

生成物側から開始したスキャンの障壁の読み方

この TS 候補を生成した scan（または経路）が生成物から始まった場合、報告される生のバリアは逆方向のバリア E(TS) − E(product) です。通常ほしい順方向のバリアは反応物から計算します。

実行内容	順方向バリア
生成物始点のスキャン	E(TS) − E(reactant) — 生の生成物始点の値ではない

これはフラグではなく読み取り時の解釈です。特に結晶構造の生成物複合体から開始した場合は、バリアを引用する前にスキャンがどちらの端点から始まったかを必ず確認してください。scan: スキャン方向とバリアの符号 も参照してください。

条件を揃えた変異体 vs WT 比較

変異体 vs WT（または機構 vs 機構）のバリア比較では、比較するすべてのモデルが同一の原子集合（同じ原子数・同じ残基）を使わなければなりません。さもなければ対照が揃わず比較にならず、バリア差は解釈できません。

pdb2reaction ではクラスターの原子集合を直接指定するため、同一原子集合の規則は仕組み上保証されます。

• 1 つのクラスター原子集合を用意し、変異（または機構変更）をその同じ集合上で適用することで、比較するすべての実行で原子数と残基を同一に保ちます。共有クラスターをその場で編集してください。各変異体を独立に再抽出しないこと。--radius や残基の含め方が異なると原子集合が警告なく変わり、比較が壊れます。

• 非標準リガンドの電荷は -l 'RES:Q'（例 -l 'GPP:-3,SAM:1'）で比較するすべての実行に揃え、電荷差がバリア比較を交絡しないようにします。

# WT と変異体は 1 つの用意したクラスターを共有（原子数・残基が同一）
pdb2reaction all -i wt_cluster.pdb     -l 'GPP:-3,SAM:1' --tsopt --thermo -o result_wt
pdb2reaction all -i mutant_cluster.pdb -l 'GPP:-3,SAM:1' --tsopt --thermo -o result_mutant

YAML 設定

共通セクションについては YAML リファレンス を参照してください。必要な値だけ変更してください。

共通設定（両モード共通）

geom と calc のキーは正規定義から変更ありません。詳細は YAML リファレンスの geom と calc を参照してください。

opt ブロックは opt と同じキーを使用し、以下が tsopt 固有のデフォルトです:

opt:
 thresh: baker # tsopt のデフォルト（`opt` は `gau`）
 out_dir: ./result_tsopt/ # tsopt のデフォルト（`opt` は `./result_opt/`）

Note

平坦なエネルギー地形によるフォールバック収束。 RS-I-RFO は共通の energy_plateau 設定を参照します。直近 energy_plateau_window ステップ（デフォルト 50）の エネルギーレンジ（max − min）が energy_plateau_thresh（デフォルト 1×10⁻⁴ au ≈ 0.06 kcal/mol） を下回ると収束と判定されます。大規模 TS 系では MLIP の力のノイズフロア（~4×10⁻⁴ au）が baker max_force 閾値（3×10⁻⁴ au）を上回ることがあり、エネルギー地形がすでに平坦になっていても 力ベース判定に到達しないためです。無効化するには energy_plateau: false を指定してください。

Dimer モード（--opt-mode grad）

--opt-mode grad（Hessian Guided Dimer + L-BFGS）で使用します。

hessian_dimer ブロック全体（内部 dimer: とそのネストされた lbfgs: を含む）は hessian_dimer に記載されています。内部 lbfgs: は lbfgs セクションを継承し、以下が tsopt 固有の上書きです:

hessian_dimer:
 dimer:
   lbfgs:
     out_dir: ./result_tsopt/ # tsopt の上書き（defaults.py の値は ./result_opt/）

RS-I-RFO モード（--opt-mode hess、デフォルト）

--opt-mode hess（RS-I-RFO、デフォルト）で使用します。

rsirfo ブロック全体は rsirfo に記載されています（trust-region と Hessian-update の各キーは rfo からも継承）。tsopt 固有の上書きは以下のとおりです:

rsirfo:
 trust_max: 0.10 # 最大信頼半径 (bohr)
 out_dir: ./result_tsopt/ # tsopt の上書き（defaults.py の値は ./result_opt/）
 hessian_recalc: 500 # N マクロステップごとに exact Hessian を再計算

Tip

最適化中に TS モードが別のルートに切り替わる場合（例: 複数の虚振動数が存在する場合）は rsirfo.track_mode_by_overlap: true を設定してください。

Tip

TS 収束が遅い場合や最適化中に TS モードが失われる場合は、rsirfo セクションの hessian_recalc を小さくしてみてください（例: 50–200）。正確なHessian再計算の頻度を上げることで、追加のHessian評価コストと引き換えに堅牢性が向上します。

注記

• 虚振動数モード検出の閾値はデフォルトで 5.0 cm⁻¹（hessian_dimer.neg_freq_thresh_cm で変更可能）。この閾値未満の振動数は虚振動数としてカウントされません。選択した root は最適化中にどの振動モードを追跡するかを制御します。root は YAML（rsirfo.root または hessian_dimer.root、デフォルト 0）で設定します。tsopt に --root CLI フラグはありません（irc とは異なります）。

• --opt-mode はワークフロー選択用です（デフォルト: rsirfo）。YAML のモードマッピングを手動で変更するのではなく、目的のアルゴリズムに合ったモードを選択してください。

• Dimer モードは初期Hessianの対角化前に並進/回転射影（凍結原子がある場合は PHVA）を適用し、freq と同じ実装に揃えています。RS-I-RFO モードは活性 DOF のデカルトHessianを TR 射影なしで直接扱います（凍結原子により剛体対称性が失われるためです）。

• 設定の優先順位は CLI 規約: 設定の優先順位 を参照してください。

関連項目

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

• トラブルシューティング — 詳細な切り分け

• path-search — TS 候補（HEI）を特定する MEP 探索

• irc — 最適化された TS からの反応経路追跡

• freq — 完全な振動解析と熱化学補正（虚振動数チェックは tsopt が内部で実行済み）

• all — 抽出 → MEP → tsopt → IRC（→ オプションで freq/DFT）を連鎖する一気通貫ワークフロー

• YAML リファレンス — hessian_dimer（Hessian Guided Dimer）と rsirfo の完全な設定オプション

• 用語集 — TS、Dimer、RS-I-RFO、Hessianの定義