共通オプションと残基・原子の指定

全コマンドに共通するフラグ、残基と原子の指定、電荷と多重度、終了コード、設定の優先順位をまとめたページです。

ブール値オプション

段階や動作のオン・オフは、対になったフラグで指定します。

形	例
有効にする	--tsopt
無効にする	--no-tsopt

--tsopt --thermo --no-dft

よく使うブール値オプション：

• --tsopt / --thermo / --dft：後処理ステージの有効化

• --freeze-links：キャップ水素の親原子を固定（デフォルトで有効）

• --dump：軌跡ファイルの出力

• --preopt / --endopt：前処理／後処理の最適化

• --climb：最小エネルギー経路の探索でクライミングイメージを使う

• --convert-files：入力の形式に合わせて、出力の PDB / CIF / GJF の写しも書く

段階的ヘルプ

pdb2reaction <subcmd> --help               # 主要オプションのみ
pdb2reaction <subcmd> --help-advanced      # 全オプション

ログ詳細度 (verbosity)

-v/--verbose LEVEL は 0〜3 の整数 (デフォルト 2) で、各コマンドのコンソール出力量を決めます。コマンドごとのオプションなので、サブコマンドと一緒に指定します (例: pdb2reaction opt -v 1 ...)。4 段階は全コマンド共通で、各コマンドページはそのコマンド固有の出力だけを説明します。

レベル	表示内容
-v 0	無出力。成功は終了コードと出力ファイルで確認します。
-v 1	マイルストーンのみ: バージョン、入力要約、主要設定、出力先、dry-run / 最終ステータス。バナー・[command]・[mode]・設定の一覧は出ません。
-v 2	デフォルト。バナー、[command]、[mode]、ステージ進捗、主要なオプティマイザのサイクル表、終了ステータス、Hessian 1 行要約、熱化学 / DFT 要約、経過時間を追加します。
-v 3	デバッグ: 実際に使う設定の全体、バックエンドの DEBUG、オプティマイザ・内部座標の詳細、[HessianTiming]、[HessianVRAM]。

レベルで変わるのは表示だけで、終了コードは変わりません。成否は 終了コード で判断してください。

残基セレクタ

extract と all の -c/--center は、モデルの中心にする残基を指定します。下の表は、範囲の狭い形から順に並べています。

形	例	選ばれる残基
chain＋残基名＋番号（推奨）	-c 'A:TYR:44' / -c 'A:TYR:44,A:SAM:123'	1 項目につき 1 残基だけを確実に選べます。
chain＋残基名	-c 'A:SAM'	chain A の SAM をすべて選びます。複数あるときは警告をログに出します。
chain＋番号	-c 'A:123' / -c 'A:123,B:456' / -c 'A:123A'	chain A の残基 123 を選びます。末尾の英字は挿入コードです。
残基名だけ	-c 'SAM,GPP' / -c 'LIG'	どの chain でも、同じ名前の残基をすべて選びます。複数あるときは警告をログに出します。
番号だけ	-c '123,456' / -c '123A'	すべての chain から同じ番号の残基を選びます。
構造ファイル	-c substrate.pdb / -c substrate.cif	別の PDB / mmCIF ファイルの座標と一致する残基を選びます。

mmCIF の長い chain ID や 9999 を超える残基番号も、同じ形で指定できます。chain ID は大文字と小文字を区別します。残基名は区別しません。同梱の例の PDB のように chain 欄が空の PDB では、残基名か番号の形だけを使えます（-c 'SAM,GPP,MG'、--selected-resn '44,63,186'）。

pdb2reaction extract -i complex.cif -c 'LONG_CHAIN:SAM' -o model.pdb        # chain LONG_CHAIN の SAM をすべて
pdb2reaction extract -i complex.cif -c 'LONG_CHAIN:SAM:10001' -o model.pdb  # SAM を 1 つだけ
pdb2reaction extract -i complex.cif -c 'LONG_CHAIN:10001' -o model.pdb      # chain＋番号

--selected-resn も同じ残基セレクタを使う

extract と all の --selected-resn は、指定した残基をモデルに必ず含めます。指定の形は上の表と同じです。たとえば A:TYR:44 は 1 残基、A:SAM は chain A の SAM すべて、A:123A は挿入コード付きの 1 残基を含めます。chain を付けない TYR は一致する残基をすべて含め、複数あるときは警告を出します。

電荷の指定

PDB/mmCIF 入力では、--ligand-charge/-l を使うと非標準残基（基質・補因子など）の電荷だけを指定すれば、標準アミノ酸やイオンの電荷と合算して全系の電荷が自動計算されます。

-l 'SAM:1,GPP:-3'        # 残基ごとの指定（推奨）
-l 'LIG:-2'              # 1 残基の指定
-l -3                    # 整数 1 つ = リガンドの総電荷
-q 0                     # 全系の総電荷を明示

電荷の決まり方（上ほど優先）:

1. 明示的な -q/--charge

2. --ligand-charge/-l があるとき：PDB/mmCIF 入力の標準残基・イオン・指定したリガンドの電荷の合計。all -c では抽出したモデルの中の合計

3. --config 内の calc.charge

4. -l が無いとき：all -c では抽出したモデルの標準残基とイオンの電荷の合計（ほかの残基は 0 とする）、.gjf 入力ではテンプレートの電荷

5. どれでも決まらなければ実行を中断

導出した電荷は、端末の Total active site model charge の行に出ます。extract の後に読む行は モデルを確かめる にあります。

Tip

非標準の残基には必ず --ligand-charge/-l を指定し、電荷が正しく伝播するようにしてください。

スピン多重度

-m 1    # 一重項 (singlet)（デフォルト）
-m 2    # 二重項 (doublet)
-m 3    # 三重項 (triplet)

all と各サブコマンドで、同じ -m/--multiplicity を指定してください。

原子セレクタ

原子セレクタは --scan-lists と opt の --distance-restraint で 1 つの原子を指します。--freeze-atoms は 1 始まりの原子のインデックスだけを受け付けます（原子の固定と距離の拘束）。

--scan-lists '[(1, 5, 2.0)]'                                          # 1 始まりの整数インデックス
--scan-lists '[("SAM,320,CS1", "GPP,321,C7", 1.60)]'                  # 残基名、残基番号、原子名
--scan-lists '[("A:SAM:320:CS1", "A:GPP:321:C7", 1.60)]'              # chain ID 付き

3 項目のセレクタは、残基名・残基番号・原子名を任意の順序で並べ、空白・カンマ・コロン・スラッシュ・バッククォート・バックスラッシュのどれでも区切れます（"SAM,320,CS1"、"SAM 320 CS1"、"320,SAM,CS1" は同じ原子）。3 項目に chain は入りません。chain を指定するときは、4 項目の形 CHAIN:RESNAME:RESSEQ[ICODE]:ATOM をこの順で書き、挿入コードは残基番号に続けます（A:SAM:12B:C1）。

スキャンリスト仕様

scan と all の -s/--scan-lists は 1 個以上の、scan2d / scan3d は 1 個だけのインライン Python リテラルを受け付けます。スタンドアロンの scan / scan2d / scan3d はこれに加えて YAML/JSON スペックファイルパスも受け付けます。複数ステージの実行にはファイルが、短い指定にはインラインリテラルが適しています。

YAML/JSON スペックファイル（ルートはマッピング。キーは scan では stages、scan2d / scan3d では pairs）:

one_based: true            # 任意。未指定時はコマンドの --one-based/--zero-based（デフォルトは 1 始まり）に従う
stages:                    # scan 用
  - [[1, 5, 1.35]]
  - [[1, 5, 2.20], [2, 8, 1.80]]

one_based: true
pairs:                     # scan2d（ちょうど 2 要素） / scan3d（ちょうど 3 要素）
  - [1, 5, 1.30, 3.10]
  - [2, 8, 1.20, 3.20]

scan2d / scan3d の各軸は (i,j,low,high)、(i,j,k,low,high)、(i,j,k,l,low,high) のいずれかです。インデックスは整数、3 項目のセレクタ、または位置固定の CHAIN:RESNAME:RESSEQ[ICODE]:ATOM で指定できます。

インラインリテラル: シェルがカッコや空白を解釈しないように、リスト全体をシングルクォートで囲み、中の PDB セレクタはダブルクォートで書いてください。

-s '[(atom1, atom2, target_Å), ...]'             # scan: 3 要素タプル
-s '[(atom1, atom2, low_Å, high_Å), ...]'        # 距離の範囲
-s '[(atom1, atom2, atom3, low_deg, high_deg)]'  # 角度の範囲
-s '[("SAM,320,CS1","GPP,321,C7",1.60)]'         # クォートしたセレクタ
-s "[(\"SAM,320,CS1\",\"GPP,321,C7\",1.60)]"       # 非推奨: 外側をダブルクォートで囲むと内側のエスケープが必要

scan では 1 リテラル = 1 ステージです。複数ステージを実行するには、1 つの --scan-lists フラグの後に複数リテラルを並べます。scan2d / scan3d ではリテラルは 1 つだけ を受け付けます。

コマンド	受け付けるスキャン仕様
scan	インラインの距離の目標値 (i,j,target)、または入力構造から両方向にスキャンする範囲 (i,j,low,high)・(i,j,k,low,high)・(i,j,k,l,low,high)（双方向スキャン）。YAML/JSON にも対応
all --scan-lists	インラインの目標値のみ：距離 (i,j,target)、角度 (i,j,k,deg)、二面角 (i,j,k,l,deg)（範囲と YAML/JSON は不可）
scan2d	距離・角度・二面角の軸を2本含む1リテラル/ファイル
scan3d	距離・角度・二面角の軸を3本含む1リテラル/ファイル

したがって 4 要素のタプルは、scan では距離の範囲、all では角度の目標値です。

入力ファイル要件

• PDB — 水素原子を含み（reduce、pdb2pqr、Open Babel で追加）、列 77–78 に元素記号が必要です（欠けている場合は pdb2reaction add-elem-info）。複数の PDB は同じ原子を同じ順序で持つ必要があります。

• mmCIF — 下の mmCIF と大きな構造 を参照してください。

• XYZ / GJF — 活性部位モデルの抽出を行わない場合（-c/--center を省略）に使えます。.gjf ファイルは埋め込みメタデータから電荷／スピンのデフォルトを与えます。

mmCIF と大きな構造

PDB を受け付ける計算コマンドは、すべて .cif と .mmcif も受け付けます。2 文字以上の chain ID、4 桁を超える残基番号、5 桁を超える原子の通し番号を持つ構造や、残基が 10,000 以上の構造には mmCIF を使ってください。

pdb2reaction は最初の座標モデルを読み、altLoc（別位置の配座）は残基ごとに平均占有率の最も高いものを 1 つ残します。計算の間は一時的な chain ID と残基番号を使い、出力の CIF で元の chain ID・残基番号・挿入コードに戻します。大きな PDB や標準の欄に収まらない PDB（残基が 10,000 以上、原子が 99,999 以上、hybrid-36 の番号、桁があふれた欄など）も同じように扱います。

残基と原子のセレクタには、元の chain ID と残基番号を使います。出力の横に書かれる .cif については 出力ディレクトリのレイアウト を参照してください。

軌跡から 1 フレームを取り出す

_trj.xyz はふつうの複数フレームの XYZ なので、k 番目（1 から数える）のフレームは次のように取り出せます。

N=$(head -1 scan_trj.xyz); k=12
sed -n "$(( (k-1)*(N+2)+1 )),$(( k*(N+2) ))p" scan_trj.xyz > frame_12.xyz

PDB のトポロジーを使って続けるときは、元の PDB を次のコマンドの --ref-pdb に渡してください。座標はフレームのものを使います。

終了コード

コード	意味
0	成功、または利用できる一部の結果あり
1	未収束、利用できる結果なし、実行中の例外、出力失敗
2	コマンドが受け付けなかった CLI 引数、書式の誤った設定 YAML
130	ユーザー中断（SIGINT）

JSON の有無で終了コードは変わりません。終了コード 0 には success と partial の両方が入るので、scientific_status で見分けます。all と path-search はこれを summary.log に書き、all は端末にも Scientific status: として出します。ほかのコマンドは --out-json を付けたときに result.json に記録します（実行の完了と指定した段の完了）。--out-json を付けないときは、そのコマンドのページにある端末の行で見分けてください（例：irc では IRC の成否の判定）。

--opt-mode（サブコマンド依存）

--opt-mode は最適化法を選びます。L-BFGS（記憶制限 BFGS）と RFO（有理関数最適化）は極小を探し、Dimer、RS-P-RFO（制限ステップ分割 RFO）、RS-I-RFO（制限ステップイメージ RFO）、TRIM（信頼領域イメージ最小化）は TS（遷移状態）を探します。

サブコマンド	grad エイリアス	hess エイリアス	デフォルト
opt	L-BFGS (lbfgs)	RFO (rfo)	grad (L-BFGS)
tsopt	Dimer (dimer)	RS-P-RFO (rsprfo)	hess (RS-P-RFO)
path-opt（端点の事前最適化）	L-BFGS	RFO	grad
path-search（HEI±1 と配座変化の区間（kink）のノードを 1 構造ずつ最適化。HEI は最高エネルギーのイメージ）	L-BFGS	RFO	grad
scan / scan2d / scan3d（格子の各点の緩和）	L-BFGS	RFO	grad
all（前処理の最適化、--opt-mode）	L-BFGS	RFO	grad
all（TS 最適化、--opt-mode-post）	Dimer	RS-P-RFO	hess
all（IRC 後の端点の最適化、--opt-mode-post）	L-BFGS	RFO	hess

同じ --opt-mode の値でも、サブコマンドによって選ばれる最適化法が異なり、デフォルトも異なります。レシピをコピーする前に表を確認してください。アルゴリズム名を受け付けるのは opt（lbfgs / rfo）と tsopt（dimer / rsirfo / trim / rsprfo）だけで、ほかのサブコマンドは grad / hess だけを受け付けます。したがって tsopt の --opt-mode grad は L-BFGS 最小化ではなく Dimer TS 探索で、この Dimer 法は Hessian を周期的に計算して Dimer の向きを更新します。曖昧さを避けるには、tsopt では --opt-mode dimer か rsirfo、opt では --opt-mode lbfgs か rfo と書いてください。

CLI ↔ YAML 名称の不一致

一部の CLI フラグは YAML のキーと名前が少し違い、all から指定するときに別の名前になるものもあります。主なフラグと YAML キーの対応は YAML 設定の一覧の主要な CLI→YAML マッピング にあります。特によく聞かれる 2 ケースを以下に示します:

• --pressure (CLI) と pressure_atm (YAML) — freq のフラグは --pressure FLOAT、all では --freq-pressure です。YAML キーは thermo.pressure_atm です。どちらも値は atm 単位で、内部で Pa に変換されます。

• --step-size (CLI) と step_length (YAML) — irc のフラグは --step-size FLOAT（bohr）、all では --irc-step-size です。YAML キーは irc.step_length です。

pdb2reaction irc -i ts.pdb -q 0 --step-size 0.05
pdb2reaction all -i r.pdb p.pdb -c SAM -l 'SAM:1' --tsopt --irc-step-size 0.05

YAML 設定

pdb2reaction all -i r.pdb p.pdb -q -1 --config my_settings.yaml --out-dir result/

組み込みデフォルト  <  --config (YAML)  <  CLI オプション

各オプションの組み込みデフォルトは、pdb2reaction <subcmd> --help-advanced と コマンドの一覧（英語のみ） の [default: …] で確かめられます。YAML を上書きするのは明示的に指定した CLI の値だけで、CLI のデフォルトのままのオプションは YAML の値を隠しません。この順序は --config を受け付けるすべてのコマンドに共通です。全設定は YAML 設定の一覧 を参照してください。

出力ディレクトリ

-o/--out-dir ./my_results/ で計算コマンドの出力先を指定します。コマンドごとのデフォルトは 出力ディレクトリのレイアウト にあります。extract だけは -o/--output に 1 つ以上のファイルパスを取り、デフォルトではカレントディレクトリに書き出します。

使用上の注意点

• 値を付けたフラグ: フラグに値（true / false）を付けた形も受け付けますが、コマンドやスクリプトには対のフラグを書いてください。

• 残基名と番号には chain を付けてください: TYR:44 は「chain TYR の残基 44」と読まれ、「見つからない」というエラーで止まります。A:TYR:44 と書いてください。

• 1 つのリストには 1 種類の残基セレクタだけを使ってください: 表の形は、残基名だけ（SAM）、chain＋残基名（番号の有無を問わない。A:SAM・A:TYR:44）、番号（chain の有無を問わない。A:123・123）の 3 種類に分かれ、種類の違う形は 1 つのリストに混ぜられません。A:TYR:44,A:SAM は通りますが、A:SAM,SAM・A:44,A:SAM・SAM,TYR:44 はエラーで止まります。

• chain 欄が空の PDB での原子セレクタ: 'SER:11:HG' や 'SER 11 HG' のように 3 項目で書きます。_ は空の chain の意味にならないので、'_:SER:11:HG' はどの原子にも一致せず、エラーで止まります。

• mmCIF と大きな構造の制限: 扱える残基は 619,938 個までです（計算の間に使う内部の PDB の、1 文字の chain ID 62 種 × 残基番号 9,999）。fix-altloc と add-elem-info は PDB だけを読みます。mmCIF では、読み込みのときに altLoc を選び、元素記号を _atom_site.type_symbol から取ります。この値が無い行があるとエラーで止まります。

• --flatten と YAML: --flatten（opt・tsopt・all。デフォルトで無効）は、余分な虚振動モードに沿って構造をずらし、最適化をやり直します。--flatten も --no-flatten も指定しないときは、tsopt は YAML に書いた hessian_dimer.flatten_max_iter の値を使います（opt は --flatten のとき最大 50 回）。--no-flatten は 0 に固定します（--flatten を使うとき を参照）。

関連ドキュメント

• インストール — セットアップと依存関係

• はじめに — 最短の実行と次に読むページ

• 出力ディレクトリのレイアウト — ファイル名とデフォルトの出力ディレクトリ

• トラブルシューティング — よくあるエラーと対処法

• YAML 設定の一覧 — 全設定オプション