# YAML 設定リファレンス


## 概要


| セクション | 説明 | 使用されるコマンド |
|---------|-------------|---------|
| [`geom`](#geom) | ジオメトリと座標設定 | all, opt, scan, scan2d, scan3d, tsopt, freq, irc, path-opt, path-search |
| [`calc`](#calc) | MLIP バックエンドの設定 | all, opt, scan, scan2d, scan3d, tsopt, freq, irc, path-opt, path-search |
| [`opt`](#opt) | 最適化の共通設定 | opt, scan, scan2d, scan3d, tsopt, path-opt, path-search |
| [`lbfgs`](#lbfgs) | L-BFGSの設定 | opt, scan, scan2d, scan3d, path-search |
| [`rfo`](#rfo) | RFOの設定 | opt, scan, scan2d, scan3d, path-search |
| [`gs`](#gs) | GSM（Growing String Method）設定 | path-opt, path-search |
| [`dmf`](#dmf) | DMF（Direct Max Flux）設定 | path-opt, path-search |
| [`stopt`](#stopt) | StringOptimizer 設定 | path-opt, path-search |
| [`irc`](#ja-irc-section) | IRC積分設定 | irc |
| [`freq`](#ja-freq-section) | 振動解析設定 | freq |
| [`thermo`](#thermo) | 熱化学設定 | freq |
| [`dft`](#ja-dft-section) | DFT計算設定 | dft |
| [`bias`](#bias) | 調和バイアス設定 | scan, scan2d, scan3d |
| [`bond`](#bond) | 結合変化検出設定 | scan, path-search |
| [`search`](#search) | 再帰的経路探索設定 | path-search |
| [`hessian_dimer`](#hessian_dimer) | Hessian Guided Dimer TS 最適化 | tsopt |
| [`rsirfo`](#rsirfo) | RS-I-RFO TS 最適化 | tsopt |

---

## 共通セクション

### `geom`

ジオメトリ読み込みと座標系の設定。

```yaml
geom:
 coord_type: cart # Coordinate type: "cart" (Cartesian) or "dlc" (delocalized internals)
 freeze_atoms: [] # 0-based indices of atoms to freeze; merged with CLI --freeze-links detection
```

**注記:**
- `freeze_atoms` は PDB 入力時の `--freeze-links` 検出原子とマージされます。
- 凍結原子は力がゼロ化され、ヘシアンの該当行/列もゼロ化されます。
- `irc` では `geom.coord_type` が YAML/CLI マージ後に `cart` へ強制されます。

---

### `calc`

MLIP バックエンドの設定。複数バックエンド（UMA, ORB, MACE, AIMNet2）と xTB 溶媒補正に対応。

```yaml
calc:
 backend: uma           # MLIP backend: "uma", "orb", "mace", or "aimnet2"
 charge: 0 # Total system charge (overridden by CLI -q)
 spin: 1 # Spin multiplicity 2S+1 (overridden by CLI -m)
 model: uma-s-1p1 # uma-s-1p1 | uma-m-1p1
 task_name: omol # Task tag recorded in UMA batches
 device: auto # Device: "cuda", "cpu", or "auto"
 max_neigh: null # Maximum neighbors for graph construction
 radius: null # Cutoff radius for neighbor search
 r_edges: false # Store radial edges
 workers: 1 # UMA inference workers (workers>1 disables analytical Hessians)
 workers_per_node: 1 # Workers per node for parallel predictor
 out_hess_torch: true # Return Hessian as torch.Tensor
 hessian_double: true # Assemble/return Hessian in float64
 # freeze_atoms: null # geom.freeze_atoms から継承されるため直接指定しない
 hessian_calc_mode: FiniteDifference # Hessian mode: "Analytical" or "FiniteDifference"
 return_partial_hessian: true  # active-DOF ブロックのヘシアンを返す
 print_timing: true # ヘシアン計算のタイミング内訳を表示
 print_vram: true # ヘシアン計算中の CUDA VRAM 使用量を表示 (UMA バックエンドのみ)
 # Solvent correction (xTB)
 solvent: none           # Implicit solvent name (e.g. "water", "methanol") or "none" to disable
 solvent_model: alpb     # xTB solvent model: "alpb" or "cpcmx"
 xtb_cmd: xtb            # Path to xTB executable
 xtb_acc: 0.2            # xTB accuracy parameter
```

**注記:**
- `backend` で MLIP エンジンを選択。UMA（デフォルト）は解析ヘシアンとマルチワーカー推論に対応。他のバックエンドは有限差分ヘシアンを使用。
- `workers` / `workers_per_node` は UMA バックエンドでのみ有効。
- `solvent` で xTB ベースの暗黙溶媒補正を有効化（デルタ補正方式）。`xtb` のインストールが必要。
- VRAMが十分な場合は `hessian_calc_mode: Analytical` を推奨します。
- `workers > 1` の場合、解析ヘシアンは無効化されます。
- 電荷/スピンは `.gjf` テンプレートがあればそれを継承します。
- `freq` はデフォルトで `calc.return_partial_hessian = true`（PHVA）を設定します（YAML で上書き可能）。
- IRC は `geom.coord_type = cart` と `calc.return_partial_hessian = true` を常に強制します（YAMLより優先、partial Hessian で active-DOF 処理）。
- `irc` では `calc.return_partial_hessian` が YAML/CLI マージ後に `true` へ強制されます。

---

### `opt`

L-BFGS/RFO で共通の単一構造最適化設定。

```yaml
opt:
 thresh: gau # Convergence preset: gau_loose, gau, gau_tight, gau_vtight, baker, never
 max_cycles: 10000 # Maximum optimizer iterations
 print_every: 100 # Logging stride
 min_step_norm: 1.0e-08 # Minimum step norm for acceptance
 assert_min_step: true # Stop if steps fall below threshold
 rms_force: null # Explicit RMS force target
 rms_force_only: false # Rely only on RMS force convergence
 max_force_only: false # Rely only on max force convergence
 force_only: false # Skip displacement checks
 converge_to_geom_rms_thresh: 0.05 # RMS threshold when converging to reference geometry
 overachieve_factor: 0.0 # Factor to tighten thresholds
 check_eigval_structure: false # Validate Hessian eigenstructure
 line_search: true # Enable line search
 dump: false # Dump trajectory/restart data
 dump_restart: false # Dump restart checkpoints
 prefix: "" # Filename prefix
 out_dir: ./result_opt/ # Output directory
```

**収束プリセット:**

| Preset | Max Force | RMS Force | Max Step | RMS Step |
|--------|-----------|-----------|----------|----------|
| `gau_loose` | 2.5e-3 | 1.7e-3 | 1.0e-2 | 6.7e-3 |
| `gau` | 4.5e-4 | 3.0e-4 | 1.8e-3 | 1.2e-3 |
| `gau_tight` | 1.5e-5 | 1.0e-5 | 6.0e-5 | 4.0e-5 |
| `gau_vtight` | 2.0e-6 | 1.0e-6 | 6.0e-6 | 4.0e-6 |
| `baker` | 3.0e-4 | 2.0e-4 | 3.0e-4 | 2.0e-4 |

---

### `lbfgs`

L-BFGSの設定（`opt` を拡張）。

```yaml
lbfgs:
 # Inherits all opt settings, plus:
 keep_last: 7 # History size for L-BFGS buffers
 beta: 1.0 # Initial damping beta
 gamma_mult: false # Multiplicative gamma update toggle
 max_step: 0.3 # Maximum step length
 control_step: true # Control step length adaptively
 double_damp: true # Double damping safeguard
 mu_reg: null # Regularization strength
 max_mu_reg_adaptions: 10 # Cap on mu adaptations
```

---

### `rfo`

RFO（Rational Function Optimizer）の設定（`opt` を拡張）。

```yaml
rfo:
 # Inherits all opt settings, plus:
 trust_radius: 0.10 # Trust-region radius
 trust_update: true # Enable trust-region updates
 trust_min: 0.0001 # Minimum trust radius
 trust_max: 0.20 # Maximum trust radius
 max_energy_incr: null # Allowed energy increase per step
 hessian_update: bfgs # Hessian update scheme: bfgs, bofill, etc.
 hessian_init: calc # Hessian initialization: calc, unit, etc.
 hessian_recalc: 500 # Rebuild Hessian every N steps
 hessian_recalc_adapt: null # Adaptive Hessian rebuild factor
 small_eigval_thresh: 1.0e-08 # Eigenvalue threshold for stability
 alpha0: 1.0 # Initial micro step
 max_micro_cycles: 50 # Micro-iteration limit
 rfo_overlaps: false # Enable RFO overlaps
 gediis: false # Enable GEDIIS
 gdiis: true # Enable GDIIS
 gdiis_thresh: 0.0025 # GDIIS acceptance threshold
 gediis_thresh: 0.01 # GEDIIS acceptance threshold
 gdiis_test_direction: true # Test descent direction before DIIS
 adapt_step_func: true # Adaptive step scaling
```

---

## 経路最適化セクション

### `gs`

Growing String Method（GSM）の設定。

```yaml
gs:
 fix_first: true # Keep first endpoint fixed
 fix_last: true # Keep last endpoint fixed
 max_nodes: 20 # Maximum string nodes (internal images)
 perp_thresh: 0.005 # Perpendicular displacement threshold
 reparam_check: rms # Reparametrization check metric
 reparam_every: 1 # Reparametrization stride
 reparam_every_full: 1 # Full reparametrization stride
 param: equi # Parametrization scheme
 max_micro_cycles: 10 # Micro-iteration limit
 reset_dlc: true # Rebuild delocalized coordinates each step
 climb: true # Enable climbing image
 climb_rms: 0.0005 # Climbing RMS threshold
 climb_lanczos: true # Lanczos refinement for climbing
 climb_lanczos_rms: 0.0005 # Lanczos RMS threshold
 climb_fixed: false # Keep climbing image fixed
 scheduler: null # Optional scheduler backend
```

---

### `dmf`

Direct Max Flux（DMF）によるMEP最適化。

```yaml
dmf:
 max_cycles: 300 # DMF/IPOPT の最大反復数（--max-cycles で上書き）
 correlated: true # Correlated DMF propagation
 sequential: true # Sequential DMF execution
 fbenm_only_endpoints: false # Run FB-ENM beyond endpoints
 fbenm_options:
 delta_scale: 0.2 # FB-ENM displacement scaling
 bond_scale: 1.25 # Bond cutoff scaling
 fix_planes: true # Enforce planar constraints
 cfbenm_options:
 bond_scale: 1.25 # CFB-ENM bond cutoff scaling
 corr0_scale: 1.1 # Correlation scale for corr0
 corr1_scale: 1.5 # Correlation scale for corr1
 corr2_scale: 1.6 # Correlation scale for corr2
 eps: 0.05 # Correlation epsilon
 pivotal: true # Pivotal residue handling
 single: true # Single-atom pivots
 remove_fourmembered: true # Prune four-membered rings
 dmf_options:
 remove_rotation_and_translation: false # Keep rigid-body motions
 mass_weighted: false # Toggle mass weighting
 parallel: false # Enable parallel DMF
 eps_vel: 0.01 # Velocity tolerance
 eps_rot: 0.01 # Rotational tolerance
 beta: 10.0 # Beta parameter for DMF
 update_teval: false # Update transition evaluation
 k_fix: 300.0 # Harmonic constant for restraints
```

---

### `search`

再帰的経路探索（path-searchのみ）。

```yaml
search:
 max_depth: 10 # Recursion depth limit
 stitch_rmsd_thresh: 0.0001 # RMSD threshold for stitching segments
 bridge_rmsd_thresh: 0.0001 # RMSD threshold for bridging nodes
 max_nodes_segment: 10 # Max nodes per segment
 max_nodes_bridge: 5 # Max nodes per bridge
 kink_max_nodes: 3 # Max nodes for kink optimizations
 max_seq_kink: 2 # Max sequential kinks
 refine_mode: null # Refinement strategy: peak, minima, or null (auto)
```

---

### `stopt`

chain-of-states 経路最適化（`path-opt`, `path-search`）向けの StringOptimizer 設定。

```yaml
stopt:
 type: string # Optimizer type label
 thresh: gau_loose # StringOptimizer convergence preset
 stop_in_when_full: 300 # Early stop threshold when the string is full
 align: false # Alignment toggle (forced to False in path-opt/path-search; external Kabsch alignment is used instead)
 scale_step: global # Step scaling mode
 max_cycles: 300 # Maximum StringOptimizer iterations
 dump: false # Dump trajectory/restart data
 dump_restart: false # Dump restart checkpoints
 reparam_thresh: 0.0 # Reparameterization threshold
 coord_diff_thresh: 0.0 # Coordinate-difference threshold
 out_dir: ./result_path_opt/ # Output directory
 print_every: 10 # Logging stride
```

---

## TS 最適化セクション

### `hessian_dimer`

Hessian Guided Dimer TS 最適化（tsopt --opt-mode grad）。

```yaml
hessian_dimer:
 thresh_loose: gau_loose # Loose convergence preset
 thresh: baker # Main convergence preset
 update_interval_hessian: 500 # Hessian rebuild cadence
 neg_freq_thresh_cm: 5.0 # Imaginary-frequency detection threshold (cm⁻¹)
 flatten_amp_ang: 0.1 # Flattening amplitude (Å)
 flatten_max_iter: 50 # Flattening iteration cap
 flatten_sep_cutoff: 0.0 # Minimum distance between representative atoms
 flatten_k: 10 # Representative atoms sampled per mode
 flatten_loop_bofill: false # Bofill update for flatten displacements
 mem: 100000 # Memory limit for solver
 device: auto # Device selection for eigensolver
 root: 0 # Targeted TS root index
 dimer:
 length: 0.0189 # Dimer separation (Bohr)
 rotation_max_cycles: 15 # Max rotation iterations
 rotation_method: fourier # Rotation optimizer method
 rotation_thresh: 0.0001 # Rotation convergence threshold
 rotation_tol: 1 # Rotation tolerance factor
 rotation_max_element: 0.001 # Max rotation matrix element
 rotation_interpolate: true # Interpolate rotation steps
 rotation_disable: false # Disable rotations entirely
 rotation_disable_pos_curv: true # Disable when positive curvature detected
 rotation_remove_trans: true # Remove translational components
 trans_force_f_perp: true # Project forces perpendicular to translation
 bonds: null # Bond list for constraints
 N_hessian: null # Hessian size override
 bias_rotation: false # Bias rotational search
 bias_translation: false # Bias translational search
 bias_gaussian_dot: 0.1 # Gaussian bias dot product
 seed: null # RNG seed for rotations
 write_orientations: true # Write rotation orientations
 forward_hessian: true # Propagate Hessian forward
 lbfgs:
 # Same keys as lbfgs section
 thresh: baker
 max_cycles: 10000
```

---

### `rsirfo`

RS-I-RFO TS 最適化（tsopt --opt-mode hess）。

```yaml
rsirfo:
 thresh: baker # RS-IRFO convergence preset
 max_cycles: 10000 # Iteration cap
 print_every: 100 # Logging stride
 min_step_norm: 1.0e-08 # Minimum accepted step norm
 assert_min_step: true # Assert when steps stagnate
 roots: [0] # Target root indices
 hessian_ref: null # Reference Hessian
 rx_modes: null # Reaction-mode definitions
 prim_coord: null # Primary coordinates to monitor
 rx_coords: null # Reaction coordinates to monitor
 hessian_update: bofill # Hessian update scheme
 hessian_recalc_reset: true # Reset recalc counter after exact Hessian
 max_micro_cycles: 50 # Micro-iterations per macro cycle
 augment_bonds: false # Augment reaction path based on bond analysis
 min_line_search: true # Enforce minimum line-search step
 max_line_search: true # Enforce maximum line-search step
 assert_neg_eigval: false # Require negative eigenvalue at convergence
 # Also inherits rfo-like settings: trust_radius, trust_update, etc.
```

---

## IRCセクション

(ja-irc-section)=
### `irc` (section)

IRC積分設定。

```yaml
irc:
 step_length: 0.1 # Integration step length
 max_cycles: 125 # Maximum steps along IRC
 downhill: false # Follow downhill direction only
 forward: true # Propagate in forward direction
 backward: true # Propagate in backward direction
 root: 0 # Normal-mode root index
 hessian_init: calc # Hessian initialization source
 hessian_update: bofill # Hessian update scheme
 hessian_recalc: null # Hessian rebuild cadence
 displ: energy # Displacement construction method
 displ_energy: 0.001 # Energy-based displacement scaling
 displ_length: 0.1 # Length-based displacement fallback
 rms_grad_thresh: 0.001 # RMS gradient convergence threshold
 hard_rms_grad_thresh: null # Hard RMS gradient stop
 energy_thresh: 0.000001 # Energy change threshold
 imag_below: 0.0 # Imaginary frequency cutoff
 force_inflection: true # Enforce inflection detection
 check_bonds: false # Check bonds during propagation
 out_dir: ./result_irc/ # Output directory
 prefix: "" # Filename prefix
 max_pred_steps: 500 # Predictor-corrector max steps
 loose_cycles: 3 # Loose cycles before tightening
 corr_func: mbs # Corrector function choice
```

---

## 振動解析セクション

(ja-freq-section)=
### `freq` (section)

振動解析設定。

```yaml
freq:
 amplitude_ang: 0.8 # Displacement amplitude for modes (Å)
 n_frames: 20 # Number of frames per mode animation
 max_write: 10 # Maximum number of modes to write
 sort: value # Sort order: "value" or "abs"
 out_dir: ./result_freq/ # Output directory
```

---

### `thermo`

熱化学設定。

```yaml
thermo:
 temperature: 298.15 # Thermochemistry temperature (K)
 pressure_atm: 1.0 # Thermochemistry pressure (atm)
 dump: false # Write thermoanalysis.yaml
```

---

## DFTセクション

(ja-dft-section)=
### `dft` (section)

DFT計算設定。

```yaml
dft:
 func: wb97m-v # Exchange-correlation functional
 basis: def2-tzvpd # Basis set name
 func_basis: null # Combined "FUNC/BASIS" string (overrides func/basis)
 conv_tol: 1.0e-09 # SCF convergence tolerance (hartree)
 max_cycle: 100 # Maximum SCF iterations
 grid_level: 3 # PySCF grid level
 verbose: 0 # PySCF verbosity (0-9)
 out_dir: ./result_dft/ # Output directory root
```

---

## スキャン関連セクション

### `bias`

調和バイアス設定。

```yaml
bias:
 k: 300.0 # Harmonic bias strength (eV·Å⁻²)
```

---

### `bond`

MLIPベースの結合変化検出。

```yaml
bond:
 device: cuda # UMA device for bond analysis
 bond_factor: 1.2 # Covalent-radius scaling for cutoff
 margin_fraction: 0.05 # Fractional tolerance for comparisons
 delta_fraction: 0.05 # Minimum relative change to flag bond formation/breaking
```

---

## 例: 設定ファイルの全体例

```yaml
# pdb2reaction configuration example

geom:
 coord_type: cart
 freeze_atoms: []

calc:
 backend: uma
 charge: 0
 spin: 1
 model: uma-s-1p1 # uma-s-1p1 | uma-m-1p1
 device: auto
 hessian_calc_mode: Analytical # Recommended when VRAM permits
 solvent: none                 # Set to e.g. "water" for implicit solvent

gs:
 max_nodes: 12
 climb: true
 climb_lanczos: true

stopt:
 thresh: gau_loose
 max_cycles: 300
 dump: false
 out_dir: ./result_all/

opt:
 thresh: gau
 lbfgs:                     # トップレベルの `lbfgs:` としても記述可
 max_cycles: 10000
 rfo:                       # トップレベルの `rfo:` としても記述可
 max_cycles: 10000

bond:
 bond_factor: 1.2
 delta_fraction: 0.05

search:
 max_depth: 10
 max_nodes_segment: 10

freq:
 max_write: 10
 amplitude_ang: 0.8

thermo:
 temperature: 298.15
 pressure_atm: 1.0

dft:
 func: wb97m-v
 basis: def2-tzvpd
 grid_level: 3
```

---

## 参照

- [all](all.md) - 一気通貫ワークフロー
- [opt](opt.md) - 単一構造最適化
- [tsopt](tsopt.md) - 遷移状態最適化
- [path-search](path_search.md) - 再帰的 MEP 探索
- [freq](freq.md) - 振動解析
- [dft](dft.md) - DFT計算
- [uma_pysis](uma_pysis.md) - MLIP バックエンドの詳細
