# チェックポイント:状態・アクセサ・保存と読込

**チェックポイント**は qc-rs の中心オブジェクトです — あらゆる計算は、構築・拡張・実行・問い合わせするチェック
ポイントです。[中核概念](../00-intro/concepts.md) がモデルを導入しました;本ページは、チェックポイントが何を保持し、
それを読み・永続化する API のリファレンスです。

## チェックポイントが保持するもの

チェックポイントは次を束ねます:

- **分子入力** — 幾何、基底（`ao`）、`charge`、`spin`、`ao_rep`、解決済みの `iop` マップ;
- **現在の電子状態** — `current_mo`（行 MO 係数）+ `current_density`、推定・SCF・CASSCF が更新;
- **材料化された結果** — SCF/LCT/opt/物性のレコード;
- **ワークフローのメタデータ** — 保留グラフ、トレース/リスタートのメタデータ、キャッシュのメタデータ。

現在の MO/密度は*単一*の現在集合です（推定・SCF・CASSCF がその場で更新、ステージごとのコピーではない）。座標は
**bohr** で保存されます。

## 構築と確認

```python
import qc
m = qc.chk.new(atom="O 0 0 0.117; H 0 0.757 -0.469; H 0 -0.757 -0.469",
               ao="cc-pvdz", unit="angstrom")

# 分子アクセサ（プロパティのものとメソッドのものがある — () に注意）
m.natom                 # 3            （プロパティ）
m.symbols               # ['O','H','H']
m.charge, m.spin        # (0, 1)
m.nelectron()           # 10           （メソッド）
m.coordinates()         # (natom, 3) 配列、bohr
m.nuclear_energy()      # スカラー、hartree
m.dummy_atoms(), m.translation_vectors()   # 特殊原子
```

## ステップの追加:関数形式とメソッド形式

あらゆるワークフロー動詞は両方の形で存在し — 挙動は同一です:

```python
qc.scf(m, ref="r")      # 関数
m.scf(ref="r")          # メソッドチェーン — 同じ保留ステップ
```

動詞:`guess`, `ints`, `scf`, `casscf`, `fci`, `dmrg`, `lct`, `td`, `.opt()`、および `qc.grad`。ステップの追加は
重い計算を**しません** — 保留ノードを持つ新しいチェックポイントを返します。**`.run()`** が結果を材料化します。

## 結果を読む

`.run()` の後、ステップアクセサが材料化されたレコードを公開します:

```python
m = m.scf(ref="r").run()
m.scf.energy            # -76.026794
m.scf.converged         # True
m.scf.ncycle            # 9
m.scf.energy_components # {'core':..., 'coulomb':..., 'exchange':...}
m.scf.gradient          # 力（勾配/最適化の後）

m.lct.energy, m.lct.e_corr        # lct(method="mp2") の後
m.opt.converged, m.opt.energy     # .opt() の後
m.prop.chrg.hirshfeld()           # 物性（qc.prop 名前空間）
```

`.run()` の前、`m.scf` は*保留*ノード;後は*結果*アクセサです。

## ログと表示

```python
m.run(log="stdout")   # 実況トランスクリプトを流す
m.log(format="text")  # 保存トランスクリプトを再生（"text"/"markdown"/"jsonl"）
m.show("result")      # 状態/結果のスナップショットを描画
m.run_events()        # 生イベントストリーム:JSON 文字列のリスト
```

[ログの章](../20-guide/logging-output.md) 参照。

## 保存と読込

チェックポイントは **HDF5 `.qch5`** ファイルに永続化され、問い合わせ・拡張可能なチェックポイントとして読み戻せ
ます:

```python
m.save("water.qch5")            # 状態 + 結果 + 保留メタデータ + トランスクリプトを永続化
r = qc.chk.load("water.qch5")   # 復元

r.scf.energy                    # -76.026794   結果は往復で保持される
r.scf(xc="b3lyp").run()         # 読み込んだチェックポイントにさらにステップを追加
```

`save`/`load` は作業を**中断・再開**する方法です:高価なステップを一度走らせ、保存し、後で読み込んで物性計算・
最適化・再開する — 再計算なしです。（`run(nthread=/nmpi=)` のセッション固定の並列設定は保存**されません**。）

## 軌道の取り込み:`guess("read")`

`guess("read", source="other.qch5", irreps=...)` は別のチェックポイントから MO を取り込み、現在の基底へ射影します
— リスタートや、安い基底 → 大きい基底のステップアップ用（[初期推定の章](../20-guide/initial-guess.md)）。`irreps` は
`"auto"`（対称性が一致するときのみラベル保持）、`"preserve"`（不一致はエラー）、`"ignore"`（ラベル破棄）。
`qc.chk.load(path)` は既に*全*チェックポイントを復元するので、`qc.chk.load(path).guess("read")` は通常冗長です。

## リファレンス:よく使うアクセサ

| アクセサ | 形式 | 返すもの |
|---|---|---|
| `natom`, `charge`, `spin` | プロパティ | int |
| `symbols` | プロパティ | 元素記号のリスト |
| `nelectron()`, `nuclear_energy()` | メソッド | int / float |
| `coordinates()` | メソッド | `(natom,3)` 配列、bohr |
| `density`, `density_alpha`, `density_beta` | プロパティ | `(nao,nao)` 配列（状態が存在後） |
| `overlap`, `kinetic`, `nuclear_attraction` | プロパティ | 1 電子行列（`ints` 後） |
| `orbitals`, `mo` | プロパティ | 軌道テーブル / MO 係数 |
| `scf.*`, `lct.*`, `opt.*` | ステップアクセサ | 材料化された結果フィールド |