# IOP:詳細オプション

公開シグネチャ（`chk.new`, `scf`, `ints`, …）は一般的な制御に集中しています。まれで低レベルの**数値ノブ**は、
単一の **`iop={...}`** 辞書にまとめられます — Gaussian の `IOp` に着想を得た横断的なチャネルですが、数値 ID の
代わりに読みやすい名前空間つきの名前と型付きの値を使います。

## IOP キーの設定

`qc.chk.new(...)` に `iop=` を渡すか、計算ごとに `mychk.with_iop({...})`（新しいチェックポイントを返す）で
重ねます:

```python
import qc
m = qc.chk.new(
    atom="O 0 0 0; H 0 0.76 0.59; H 0 -0.76 0.59",
    ao="def2-svp",
    iop={"ri.metric_cutoff": 1e-10, "integral.screen.schwarz_tol": 1e-12},
)

m2 = m.with_iop({"scf.conv_tol_grad": 1e-7})   # 重ね、新しいチェックポイントを返す
m2.scf(ref="r").run()
```

キーはドット区切りの **`<area>.<subsystem>.<knob>`** 名で、中央レジストリに対して検証されます。**未知のキーは
エラー**（候補提示つき）で、静かに無視されません:

```python
m.with_iop({"not.a.real.key": 1})
# ValueError: unknown iop key "not.a.real.key"
```

## キーの発見:`qc.iop`

レジストリは内省可能で、キーやその既定を推測する必要はありません:

```python
qc.iop.list()                       # 全 47 キー（ドット名の集合）
qc.iop.defaults()                   # 全キーの {key: default_value}
qc.iop.describe("scf.conv_tol_grad")
# {'type': 'float', 'default': 1e-06, 'min': 0.0, 'max': 1.0,
#  'consumer': 'scf', 'scientific': False,
#  'doc': 'Commutator-RMS convergence threshold (the SCF gradient tolerance).'}
```

`describe(key)` は値の型、既定、許容範囲、どのサブシステムが消費するか、1 行のドキュメントを返します。

## 分野別キーレジストリ

**9 分野**に **47 キー**があります。最もよく使うもの:

### `scf.*` — SCF ソルバ

| キー | 意味 |
|---|---|
| `scf.conv_tol_grad` | 交換子 RMS 勾配収束しきい値（既定 `1e-6`） |
| `scf.diis.variant` / `.max_vectors` / `.start_cycle` | DIIS の種類、部分空間サイズ、開始サイクル |
| `scf.incremental` / `.incremental.reset` | 増分 Fock 構築の on/off、リセット周期 |
| `scf.qc_start` / `scf.soscf_start` | 2 次ラダー / SOSCF の作動時点 |
| `scf.qc.max_conventional` / `.max_nr` / `.full_linear` | QC ファミリのラダー制御 |
| `scf.trah.max_step`, `scf.yqc.stabilize_tol` | TRAH / YQC の調整 |
| `scf.symmetrize_fock`, `scf.salc_cutoff`, `scf.orbital_ordering`, `scf.orthogonalization_cutoff` | 対称性 / 直交化 |
| `scf.adaptive_screening` | SCF 内の適応的積分スクリーニング |

### `integral.*` — 積分の組み立てとスクリーニング

| キー | 意味 |
|---|---|
| `integral.screen.schwarz_tol` | Cauchy–Schwarz 四重項スクリーニング許容差（既定 `1e-12`、損失なし） |
| `integral.screen.density_tol` / `.nuclear_tol` / `.qqr` / `.qqr_extent_tau` | 密度 / 核 / QQR スクリーニング |
| `integral.precision` | 積分精度目標 |
| `integral.disk.sparse_layout` / `.io_mode` / `.restart` | アウトオブコア（`4c-disk`）レイアウト、I/O、リスタート |
| `integral.screen.disk_block_tol` / `.disk_int_tol` | ディスクバックエンドのドロップ許容差 |
| `integral.incore.*` (`k_kernel`, `rank_balance`, `s4_max_gb`, `screened_fill`) | incore-4c の調整 |

### `ri.*` — RI / 密度フィッティング

| キー | 意味 |
|---|---|
| `ri.metric_cutoff` | RI メトリック固有値カットオフ（既定 `1e-10`） |
| `ri.ram.kdist` | `ri-ram` store-`B` の K 分散（`p-transpose` / `mu-stream`） |
| `ri.recomp.occ_batch` / `.kcomm` / `.resort_max_mb` | `ri-recomp` の occ バッチ、交換通信、resort 予算 |
| `ri.store.sparse` | 疎 store-`B` |

### `lct.*` — 相関（RI-MP2）

| キー | 意味 |
|---|---|
| `lct.frozen_core` | 相関和で内殻軌道を凍結 |
| `lct.rohf_mp2` | ROHF-MP2 の慣習（`"pyscf"` / `"qcrs"`） |
| `lct.rimp2_fp32` | 単精度 RI-MP2 |
| `lct.laplace_points` | Laplace 求積点（SOS-MP2） |

### その他の分野

| キー | 意味 |
|---|---|
| `guess.gwh.scale` | GWH 推定のスケーリング係数 |
| `pcm.discretization` | PCM 空洞の離散化 |
| `parallel.strict` | オーバーサブスクリプション方針（`True` = エラー、`False` = 警告） |
| `log.timing` | タイミングスパンを出力 |

任意のキーの正確な既定・型・範囲は `qc.iop.describe(key)` を呼びます。レジストリが唯一の真実の源
（`crates/qc-workflow/src/iop.rs`）で、この一覧はそれを反映します。

## IOP と公開 kwarg のどちらか

いくつかのノブは、主要シグネチャを集中させるため公開キーワード引数から IOP キーへ移りました — 例えば
`scf.conv_tol_grad`, `scf.symmetrize_fock`, `scf.salc_cutoff`, `scf.orbital_ordering`,
`integral.screen.nuclear_tol`, `integral.precision` は IOP キーで、`scf(...)` / `ints(...)` がチェックポイントの
`iop` から読みます。日常の制御（`ref`, `xc`, `grid`, `conv_tol`, `algorithm`, `pcm`, …）は直接のキーワード引数
のまま（[SCF の章](../20-guide/scf.md)）です。