CLI 規約¶
ブール値オプション¶
手入力のコマンド、docs、skill では flag pair を使用します。
--tsopt --thermo --no-dft
旧来の value-style 表記も後方互換のため入力としては受理しますが、
canonical な表記ではなく、docs・skill・生成コマンドからは出力しません。
root CLI の bool_compat が互換入力を正規化します。
よく使うブール値オプション：
--tsopt,--thermo,--dft— 後処理ステージの有効化--freeze-links— キャップ水素の親原子を凍結（デフォルト:True）--dump— 軌跡ファイルの出力--preopt,--endopt— 前処理/後処理最適化の切り替え--climb— MEP 探索でクライミングイメージを有効化--convert-files— 入力トポロジー／テンプレートに応じた PDB/CIF/GJF companion の生成
段階的ヘルプ（all）¶
pdb2reaction all は 2 段階ヘルプです:
pdb2reaction all --help # 主要オプションのみ
pdb2reaction all --help-advanced # 全オプション
以下のコマンドも同じ段階的ヘルプに対応しています（--help で主要オプション、--help-advanced で全オプション）: scan, scan2d, scan3d, opt, path-opt, path-search, tsopt, freq, irc, dft, sp, add-elem-info, trj2fig, energy-diagram, bond-summary, extract, fix-altloc。
ログ詳細度 (verbosity)¶
-v/--verbose LEVEL は 0〜3 の整数 (デフォルト 2) で、各コマンドのコンソール出力量を決めます。コマンドごとのオプションなので、サブコマンドと一緒に指定します (例: pdb2reaction opt -v 1 ...)。4 段階は全コマンド共通で、各コマンドページはそのコマンド固有の出力だけを説明します。
レベル |
表示内容 |
|---|---|
|
無出力。成功は終了コードと出力成果物で確認します。 |
|
マイルストーンのみ: バージョン、入力要約、主要設定、出力先、dry-run / 最終ステータス。banner・ |
|
デフォルト。banner、 |
|
デバッグ: resolved config / dry-run plan、backend DEBUG、raw optimizer・内部座標の詳細、 |
意味的な失敗はどのレベルでも失敗です。-v 3 でのみ現れる Traceback も実行失敗を意味します。
残基セレクタ¶
残基セレクタ（Residue Selector）は、基質や抽出中心として使用する残基を指定します。
残基名による指定¶
-c 'SAM,GPP' # SAM または GPP という名前の残基をすべて選択
-c 'LIG' # LIG という名前の残基をすべて選択
残基 ID による指定¶
-c '123,456' # 残基 123 と 456
-c 'A:123,B:456' # チェーン A の残基 123、チェーン B の残基 456
-c '123A' # 挿入コード A を持つ残基 123
-c 'A:123A' # チェーン A、残基 123、挿入コード A
chain + 残基名による指定¶
-c 'A:SAM' # chain A 内の SAM をすべて選択
-c 'A:SAM:123' # chain A、残基名 SAM、残基番号 123 の1残基
PDB/mmCIF ファイルによる指定¶
-c substrate.pdb # 別の PDB から座標を使用して基質を特定
-c substrate.cif # 別の mmCIF も使用可能
Note
残基名で選択する場合、同名の残基が複数あればすべてが含まれ、警告がログに出力されます。
--selected-resn も同じ残基selectorを使う¶
extract と all の --selected-resn は、残基ID・残基名・chain付き
残基名を受け付けます。A:123A は挿入コード付きの1残基、A:SAM
はchain A内の全SAM、A:SAM:123 はそのうち1残基を強制包含します。
chainを付けない TYR は全matchを包含し、複数match時に警告します。
電荷の指定¶
PDB/mmCIF 入力では、--ligand-charge/-l を使うと非標準残基（基質・補因子・金属イオンなど）の電荷だけを指定すれば、標準アミノ酸やイオンの電荷と合算して全系の電荷が自動計算されます。大きな酵素–基質系で総電荷を手動で数える必要がなくなります。
残基別マッピング（推奨）¶
-l 'SAM:1,GPP:-3' # SAM は +1、GPP は -3
-l 'LIG:-2' # LIG は -2
-l -3 # 単一の整数を渡すとリガンド総電荷を直接指定（マッピングの代替）
総電荷の明示指定¶
-q 0 # 総電荷を 0 に指定
-q -1 # 総電荷を -1 に指定
抽出を行わない場合の電荷解決順序¶
明示的な
-q/--charge明示的な
--ligand-charge/-lと PDB/mmCIF 残基情報から導出した総電荷どちらの CLI 電荷指定もない場合の
--config内calc.charge.gjfテンプレートのメタデータ未解決の場合は実行を中断
この順序は opt/tsopt/freq などの単独サブコマンドと、
-c/--center を省略した all に適用されます。
all -c/--center: 抽出処理は、標準残基、イオン、
--ligand-charge/-l を合算して総電荷を導出します。明示的な -q は
ここでも最優先で、系の総電荷を設定します。抽出値と異なる場合は警告を
表示します。-q を省略して --ligand-charge/-l を明示した場合は、
その指定を使った抽出由来の電荷が YAML より優先します。CLI の電荷指定が
どちらもない場合は、設定ファイルの calc.charge が自動抽出値を上書きし、
それもなければ抽出値を使用します。
Tip
非標準の残基（基質、補因子、特殊なリガンド）には必ず --ligand-charge/-l を指定し、電荷が正しく伝播するようにしてください。
スピン多重度¶
-m 1 # 一重項 (singlet)（デフォルト）
-m 2 # 二重項 (doublet)
-m 3 # 三重項 (triplet)
Note
all を含む全サブコマンドで -m/--multiplicity を統一して使用します。
原子セレクタ¶
原子セレクタ（Atom Selector）は、スキャンや拘束に使用する特定の原子を指定します。指定方法は以下の通りです。
整数インデックス（デフォルトは 1 始まり）¶
--scan-lists '[(1, 5, 2.0)]' # 原子 1 と 5、ターゲット距離 2.0 Å
PDB 形式のセレクタ文字列¶
--scan-lists '[("TYR,285,CA", "SAM,309,C10", 2.20)]'
--scan-lists '[("A:TYR:285:CA", "B:SAM:309:C10", 2.20)]' # chain付き
セレクタのフィールドは以下で区切れます。
空白:
'TYR 285 CA'カンマ:
'TYR,285,CA'スラッシュ:
'TYR/285/CA'バッククォート:
'TYR`285`CA'バックスラッシュ:
'TYR\285\CA'
3つのtoken（残基名、残基番号、原子名）は任意の順序で指定できます。残基名や番号が重複するときは、位置固定の4-field形式CHAIN:RESNAME:RESSEQ[ICODE]:ATOMを使います。
スキャンリスト仕様¶
-s/--scan-lists（scan / scan2d / scan3d / all で使用）は 1 個以上のインライン Python リテラルを受け付けます。スタンドアロンの scan / scan2d / scan3d はこれに加えて YAML/JSON スペックファイルパスも受け付けます。複雑な設定や複数ステージの実行にはファイルが、単純な 1 ステージのみの場合にはインラインリテラルが適しています。
YAML/JSON スペックファイルの書式（推奨）¶
ルートはマッピング形式で、リスト・オブ・タプルのキーは scan では stages、scan2d/scan3d では pairs です。
one_based: true # 任意。未指定時は CLI の --one-based を使用
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]
stages/pairsは必須です。scanの各ステージは(i, j, target_Å)3 要素タプルのリストです。scan2d/scan3dの各軸は(i, j, low_Å, high_Å)の 4 要素タプルです。indexは整数、3-field selector、または位置固定
CHAIN:RESNAME:RESSEQ[ICODE]:ATOMで指定できます。
インライン Python リテラルの書式¶
各リテラルは Python リストです。シェルのクォート処理に注意が必要です。
-s '[(原子1, 原子2, ターゲット距離Å), ...]' # scan: 3 要素タプル
-s '[(原子1, 原子2, 下限Å, 上限Å), ...]' # scan2d / scan3d: 4 要素タプル
リスト全体を シングルクォート
'...'で囲みます（シェルがカッコや空白を解釈しないようにするため）。scanでは 1 リテラル = 1 ステージです。複数ステージを実行するには、1 つの-s/--scan-listsフラグの後に複数リテラルを並べます。scan2d/scan3dではリテラルは 1 つだけ を受け付けます（複数ステージは非対応）。scan2dではちょうど 2 つ、scan3dではちょうど 3 つの 4 要素タプルを含む必要があります。
コマンド |
受け付けるスキャン仕様 |
|---|---|
|
インライン3-tupleまたは双方向4-tuple。YAML/JSONにも対応 |
|
インライン3-tupleのみ |
|
|
|
|
原子の指定方法¶
原子は整数インデックスまたは PDB セレクタ文字列で指定します。
方法 |
例 |
備考 |
|---|---|---|
整数インデックス |
|
デフォルトは 1 始まり（ |
PDB セレクタ |
|
残基名、残基番号、原子名の 3 要素タプル |
chain付きselector |
|
位置固定 |
PDB セレクタのトークンは、カンマ ,、スペース、スラッシュ /、バッククォート `、バックスラッシュ \ のいずれでも区切れます。トークンの順序も任意です。
# 以下はすべて同じ原子を指定:
"TYR,285,CA"
"TYR 285 CA"
"TYR/285/CA"
"285,TYR,CA" # 順序は自由
クォートの規則¶
# 正しい: シングルクォートでリストを囲み、セレクタはダブルクォート
-s '[("TYR,285,CA","SAM,309,C10",1.35)]'
# 正しい: 整数インデックスなら内側のダブルクォートは不要
-s '[(1, 5, 2.0)]'
# 非推奨: ダブルクォートで外側を囲むとエスケープが必要
-s "[(\"TYR,285,CA\",\"SAM,309,C10\",1.35)]"
入力ファイル要件¶
PDB ファイル¶
水素原子を含む必要があります（
reduce、pdb2pqr、または Open Babel で追加）列 77–78 に元素記号が必要（欠けている場合は
pdb2reaction add-elem-infoを使用）複数の PDB は同じ原子を同じ順序で持つ必要があります（座標のみ異なる）
mmCIFファイル¶
multi-character chain、PDB欄を超えるresidue／atom ID、10,000残基以上では
.cif／.mmcifを使用共通bridgeが内部PDBで計算し、出力CIFへ元IDを復元
反応順に並べる複数入力は、形式変換後も同じ原子identityと順序が必要
XYZ および GJF ファイル¶
活性部位モデル抽出をスキップする場合に使用可能（
-c/--centerを省略）.gjfファイルは埋め込みメタデータから電荷/スピンのデフォルトを提供可能
終了コード¶
pdb2reaction サブコマンドは概ね共通の終了コード規約に従いますが、実際に返されるコードはサブコマンドごとに異なります（下表「主な発生元」列を参照）。各サブコマンドが返し得る終了コードの一覧は、当該サブコマンドのページを確認してください。
コード |
意味 |
主な発生元 |
|---|---|---|
|
成功 |
すべてのサブコマンド |
|
予期しない内部エラー、または意図された utility の部分完了 |
すべてのサブコマンド、 |
|
CLI usage・設定・入力エラー、ゼロ step、依存関係不足、command-specific processing failure |
Click/parser layer、 |
|
最適化失敗 または SCF 非収束 |
|
|
軌跡書き出しエラー |
|
|
HEI エクスポートエラー |
|
|
キーボード割り込み (SIGINT) |
すべてのサブコマンド |
irc や freq のように 0 / 1 / 130 しか使わないサブコマンドも同じ規約に従います。単に、これらは現時点で最適化固有のエラーを送出していないだけです。
--opt-mode（サブコマンド依存）¶
Warning
同じ --opt-mode トークンでも、サブコマンドによって選択される最適化アルゴリズムが異なり、デフォルトも統一されていません。レシピをコピーする前に必ずサブコマンドごとの表を確認してください。
サブコマンド |
|
|
デフォルト |
|---|---|---|---|
|
L-BFGS ( |
RFO ( |
|
|
Dimer ( |
RS-P-RFO ( |
|
|
L-BFGS |
RFO |
|
|
L-BFGS |
RFO |
|
|
L-BFGS |
RFO |
|
|
L-BFGS |
RFO |
|
|
Dimer ( |
RS-P-RFO ( |
|
|
L-BFGS |
RFO |
|
受け付けるエイリアスもサブコマンド固有です:
optはgrad/lbfgsとhess/rfoを受け付けます。tsoptはgrad/dimerとhess/rsprfoに加え、rsirfo（RS-I-RFO）、trim（TRIM/Helgaker）も単独の--opt-mode値として受け付けます。scan/scan2d/scan3d/path-opt/path-search/allはgrad/hessのみ受け付けます（アルゴリズム名 alias なし）。allの--opt-mode-postもgrad/hessのみです。
したがって tsopt に対する --opt-mode grad は L-BFGS 最小化ではなく Dimer TS 探索です。曖昧さを避けたい場合は、各サブコマンドが受け付けるアルゴリズム名を使用してください: opt では --opt-mode lbfgs|rfo、tsopt では --opt-mode dimer|rsirfo。（他のサブコマンドは grad / hess のみ受け付けます。）
CLI ↔ YAML 名称の不一致¶
一部の CLI フラグは YAML の対応キーと微妙に名前が異なり、all でラップされたときにリネームされるものもあります。完全なマッピング表は YAML リファレンスの主要な CLI→YAML マッピング にあります。特に混同されやすい 2 ケースを以下に示します:
--pressure (CLI) vs pressure_atm (YAML)¶
CLI フラグ:
--pressure FLOAT（freqサブコマンド;allでは--freq-pressureとして提供されます）。YAML キー:
thermo.pressure_atm（単位接尾辞付き）。両方とも値は atm 単位で扱われ、内部で Pa に変換されます。
--engine（単体 dft）vs --dft-engine（all 内）¶
単体
dftサブコマンドではバックエンド選択フラグは--engine（値:gpu,cpu）です。pdb2reaction all内では同じオプションが--dft-engineにリネームされます（allラッパーで他の engine 系フラグと衝突しないようプレフィックスで区別するため）。YAML では両方とも同じ
dftセクション設定に解決されます。YAML リファレンスの dft セクション を参照してください。
等価なコマンド:
# 単体 dft
pdb2reaction dft -i ts.xyz -q 0 --engine gpu
# all ラッパー内で同じ処理
pdb2reaction all -i r.pdb p.pdb -c SAM --tsopt --dft --dft-engine gpu
YAML 設定¶
詳細設定は多層 YAML で渡せます：
pdb2reaction -i r.pdb p.pdb -q -1 --config my_settings.yaml --out-dir result/
利用可能なすべてのオプションは YAML リファレンス を参照してください。
設定の優先順位¶
設定は以下の順序で解決されます（後のものが前のものを上書き）：
組み込みデフォルト < --config (YAML) < CLI オプション
組み込みデフォルト — すべてのパラメータのハードコード値（
pdb2reaction/core/defaults.pyを参照）。--config— デフォルトを上書きする YAML ファイル。サイト共通やプロジェクト共通の設定に便利です。CLI オプション — コマンドラインで明示的に指定されたフラグ（例:
--backend orb）。明示的に指定された値のみが YAML を上書きし、CLI デフォルトのままのオプションは YAML の値を隠しません。既知のデフォルト例外:
flatten_max_iterは YAML 適用前に 0 で初期化されます。toggle 未指定なら明示した YAML 値を保持し、--flattenは YAML／組み込みの正値を有効化、--no-flattenは 0 を強制します。--flatten 優先順位の注意 を参照してください。
この優先順位は all, opt, tsopt, freq, irc, scan, scan2d, scan3d, path-opt, path-search, dft に共通です。あわせて YAML リファレンス: 設定の優先順位 を参照してください。
出力ディレクトリ¶
-o/--out-dir で結果の保存先を指定します：
-o ./my_results/ # カスタム出力ディレクトリ
デフォルトの出力ディレクトリ：
all:./result_all/extract: カレントディレクトリまたは指定の-oopt:./result_opt/tsopt:./result_tsopt/path-opt:./result_path_opt/path-search:./result_path_search/scan:./result_scan/scan2d:./result_scan2d/scan3d:./result_scan3d/freq:./result_freq/irc:./result_irc/dft:./result_dft/
関連項目¶
インストール — セットアップと依存関係
はじめに — 初回実行とワークフロー概要
典型エラー別レシピ — 症状起点の切り分け
トラブルシューティング — よくあるエラーと対処法
YAML リファレンス — 全設定オプション