Tutorial 29: Reproducing a reference output

You’ll learn: how to compare a calculation you just ran against the bundled reference output for the same input — so you know whether your numbers match, and whether your wall-time is in the expected range for your hardware.

Why: every example in docs/example_outputs.md ships with a reference .out (the SCF log) and a .system manifest pinning the runtime environment that produced it. Without the manifest, an .out says “SCF total: 0.015 s” with no indication whether that’s an Apple M2 Pro at 12 OpenMP threads or an 8-year-old Xeon at 1 thread. The manifest closes that gap.

Prerequisites: vibe-qc installed; one of the bundled examples under docs/_static/examples/.

The .system file

run_job(output="x") writes three sibling files: x.out (the SCF log), x.molden (the orbitals), and x.system (the runtime manifest). The manifest is plain TOML:

[vibeqc]
version       = "0.5.1"
codename      = "Wilson's Otter"
git_sha       = "c90398f"
git_branch    = "main"
is_release    = true

[host]
hostname      = "<redacted>"
os            = "Darwin"
os_release    = "23.4.0"
os_pretty     = "macOS 14.4"
arch          = "arm64"

[cpu]
model         = "Apple M2 Pro"
physical_cores = 10
logical_cores  = 16
omp_threads_used = 12

[memory]
total_gb      = 32.0
available_gb  = 24.0

[python]
version       = "3.14.0"
implementation = "CPython"
executable    = "/path/to/.venv/bin/python"

[libraries]
libint    = "2.13.1"
libxc     = "7.0.0"
spglib    = "2.7.0"
libecpint = "1.0.7"

[run]
timestamp_iso  = "2026-04-29T21:42:14-04:00"
wall_seconds   = 0.084
basename       = "input-h2o-rhf"

Bundled docs runs ship with hostname = "<redacted>" — the regen script (scripts/regenerate_doc_examples.py) sets VIBEQC_NO_HOSTNAME=1 so engineering’s machine name doesn’t leak into the public bundle. Your own runs record the live hostname unless you opt out the same way.

Compare your run against the bundled reference

Pull one detail at a time — say, the CPU model — with grep:

grep -E '^model' docs/_static/examples/h2o-rhf/output-h2o-rhf.system

Or get the whole [cpu] block:

sed -n '/^\[cpu\]/,/^$/p' docs/_static/examples/h2o-rhf/output-h2o-rhf.system

Diff your .system file against the bundled one to see what’s different on your box:

diff docs/_static/examples/h2o-rhf/output-h2o-rhf.system \
     ./output-h2o-rhf.system

The interesting lines are usually the ones in [cpu] (model + thread count) and [run] (wall_seconds). The [vibeqc].git_sha / [vibeqc].version lines tell you which build produced each result — if those don’t match, expect numerical differences across releases.

Read the manifest from Python

The manifest is plain TOML, so you can parse it with the stdlib:

import tomllib
from pathlib import Path

with open("output-h2o-rhf.system", "rb") as f:
    manifest = tomllib.load(f)

print(manifest["cpu"]["model"])           # "Apple M2 Pro"
print(manifest["run"]["wall_seconds"])    # 0.084
print(manifest["libraries"]["libint"])    # "2.13.1"

If your script wants to write the manifest without going through run_job — say you’re driving the SCF drivers directly and want the same provenance for your own outputs — use the public API:

from vibeqc import write_system_manifest
import time

t0 = time.perf_counter()
# ... your calculation ...
write_system_manifest(
    "output-mycalc.out",
    wall_seconds=time.perf_counter() - t0,
    basename="output-mycalc",
)

write_system_manifest writes alongside the .out path you pass (replacing the suffix with .system), so calling it after your calculation pairs the manifest with your output file.

Disable hostname recording

For runs you plan to share publicly (issue reports, presentations, attached as supplementary information to a paper), pass record_hostname=False to run_job:

run_job(mol, basis="6-31g*", method="rhf",
        output="output-h2o-rhf",
        record_hostname=False)

Or set VIBEQC_NO_HOSTNAME=1 once for the whole shell — useful in batch scripts that loop over many calculations:

export VIBEQC_NO_HOSTNAME=1
.venv/bin/python input-h2o-rhf.py
.venv/bin/python input-h2o-dft.py
# ... all .system files emit `hostname = "<redacted>"`

The [host] block still appears in full (OS, architecture, etc.) — only the hostname field is redacted, so a reader still gets enough context to interpret the wall-time.