ログと出力

ログと出力#

本ガイドのあらゆる実行は、静かにトランスクリプト — システム要約、SCF サイクル表、収束チェック — を生んできました。本章はその出力を見る・再生する・保存することについてです:実況で流す、事後に描画する、機械可読のデータとして得る、そして計算全体をディスクに永続化する方法です。

すべての背後にある 1 つのイベントストリーム#

qc-rs のログと表示は単一の構造化イベントストリームを共有します。実行が進むにつれ型付きイベント — System 要約、plan、サイクルごとの SCF レコード、result — を出し、出力を見るあらゆる方法は、その 1 つのストリームの異なる描画にすぎません。だから実況ログ・再生トランスクリプト・生 JSON はすべて同じ情報を示します:同じイベントを違う形式にしただけです。構造化されている（自由テキストの print ではない）ので、人間向けトランスクリプトとしても データとしても扱えます。

実況ログ:`run(log=...)`#

.run() は既定で沈黙します — 計算して返します。実行の進行に合わせてトランスクリプトを流すには log= を渡します（クイックスタートで導入）:

import qc
water = "O 0 0 0.117; H 0 0.757 -0.469; H 0 -0.757 -0.469"

m = qc.chk.new(atom=water, ao="cc-pvdz", unit="angstrom").scf(ref="r").run(log="stdout")

log= の対象は次のいずれか:

`log=`	効果
`"stdout"`	実行進行に合わせてターミナル / ノートブックセルに流す
ファイルパス	描画したトランスクリプトをそのファイルに書く
ファイル様オブジェクト	渡した任意のストリームに書く

さらに 2 つの制御が実況出力を整えます:

log_style="modern"（既定）または "orca" — トランスクリプトの見た目のスタイル（コンパクトなモダンレイアウト、または ORCA 出力を思わせるもの）。
plot=True — 実行中に SCF 収束プロットをインライン描画（matplotlib が必要;可視化参照）。

Tip

MPI 実行並列実行では、log_rank="root"（既定）はランク 0 だけをログします;"all", "gather"、またはランクのリストでどのランクが報告するかを制御します。多ランク実行が出力で溢れるのを防ぎます。並列性そのものは Part IV です。

完了した実行を再生する:`log()` と `show()`#

トランスクリプトはチェックポイントに保存されるので、再計算なしに実行後に描画できます:

m.log()                    # トランスクリプトをテキストで再生
m.log(format="markdown")   # … Markdown で（ノートブックで見やすい）
m.log(format="jsonl")      # … 1 行 1 JSON オブジェクトで
m.show("result")           # 現在の状態 + 結果の描画スナップショット

log(format=...) は保存されたイベントストリームを再描画します — "text"（既定）, "markdown", "jsonl"。
show(...) は実行中のトランスクリプトではなくスナップショット（状態と結果）を描画します — 「このチェックポイントは今何を持っているか」を手早く見るのに便利です。

これらは保存されたイベントを読むので、呼び出しにコストはかからず、毎回同一のトランスクリプトを返します — 出力をもう一度見るために log="stdout" で再実行する必要はありません。

データとしての出力:`run_events()`#

プログラム的な用途 — テスト、ダッシュボード、数値の収集 — には run_events() が、生のイベントストリームを JSON 文字列のリスト（1 イベント 1 つ）として返します:

import json
events = m.run_events()             # list[str]、各々 JSON オブジェクト
len(events)                         # 18

first = json.loads(events[0])       # System 要約イベント
first["event"]                      # 例 "system"
first["nao"], first["nuclear_repulsion"]   # 構造化フィールド、そのまま使える
[json.loads(e).get("kind") for e in events]   # 例 自動挿入された 'sad' 推定がここに現れる

各イベントは型を表す event フィールドと、その型の構造化ペイロード（原子リスト、基底サイズ、サイクルごとのエネルギー…）を持つ dict です。これが人間向けトランスクリプトを描画する元のストリームなので、ログに表示されるものはデータからも隠されていません。

計算の保存と読み込み#

チェックポイント — 分子、現在の電子状態、結果、トランスクリプト — は HDF5 .qch5 ファイルに永続化され、問い合わせや拡張ができるチェックポイントとして読み戻せます:

m.save("water.qch5")                 # チェックポイント全体を永続化
r = qc.chk.load("water.qch5")        # 復元

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

save()/load() は作業を中断・再開する方法です:高価な SCF を一度走らせ、保存し、後で読み込んで物性計算・最適化・再開する — 再計算なしです。（これは初期推定の章の guess("read", source=...) の背後のファイルでもあります。）

総合例:静かに実行し、後で確認する#

import qc, json
water = "O 0 0 0.117; H 0 0.757 -0.469; H 0 -0.757 -0.469"

m = qc.chk.new(atom=water, ao="cc-pvdz", unit="angstrom").scf(ref="r").run()   # 沈黙

m.log()                              # … 今トランスクリプトを描画
n_events = len(m.run_events())       # 18 個の構造化イベントがデータとして利用可能
m.save("water.qch5")                 # 次回のために保存
print("events:", n_events, "| E:", round(m.scf.energy, 6))

練習 9

m = chk.scf(ref="r").run()（log= なし）を実行し、今 SCF サイクル表を、もう一度 SCF を走らせる代償なしに見たいです。何を呼びますか。
自分でプロットを作るため、Python スクリプトでサイクルごとのエネルギーが必要です。どのメソッドがデータを与え、どんな形式ですか。
高価な最適化が終わりました。二度と繰り返さずに済ませる方法と、その収束軌道を後でより大きな基底の実行の初期推定として再利用する方法は。

解答練習 9

m.log() — チェックポイントに保存されたトランスクリプトを、計算コストなしで再生します（Markdown/JSONL なら log(format=...)）。
m.run_events() — JSON 文字列のリスト;各々を json.loads し、SCF サイクルイベント（scf_iteration）からサイクルごとのフィールドを取り出します。
m.save("opt.qch5") で永続化;後で qc.chk.load("opt.qch5") が結果を保ったまま復元します。軌道を再利用するには qc.chk.new(..., ao="<より大きい>").guess("read", source="opt.qch5").scf(...).run()。

これで日常のワークフローは完結です。Part III の残りは大規模な分子物性スイート — 収束した波動関数を、電荷・結合次数・トポロジー解析、そして可視化で出会った実空間場に変えます。