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

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

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

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

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

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

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

構築と確認#

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()   # 特殊原子

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

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

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

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

結果を読む#

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

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 は保留ノード;後は結果アクセサです。

ログと表示#

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

ログの章参照。

保存と読込#

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

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 を取り込み、現在の基底へ射影します — リスタートや、安い基底 → 大きい基底のステップアップ用（初期推定の章）。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.*`	ステップアクセサ	材料化された結果フィールド