The QVF format toolkit

QVF (.qvf, Quantum Visualization Format) is a ZIP-based container that keeps one calculation’s structure, wavefunction, scalar fields, spectra, bands, trajectories, provenance, and viewer hints in a single random-access file. It is the format vibe-qc writes and vibe-view reads, but it is designed for the whole quantum-chemistry ecosystem, not just vibe-qc.

This section is for developers of other codes who want to emit QVF from their own program. It hosts the normative specification, the reference writer libraries, and integration guidance.

Note

The source of truth is the independent, Apache-2.0 QVF repository: specification, JSON schema, registry, conformance corpus, and reference implementations. GitLab requires authorized access. The public GitHub snapshot can be cloned anonymously with git clone https://github.com/vibe-qc/qvf.git.

vibe-qc implements QVF independently and is validated against the published specification and corpus. It does not import or link the reference toolkit. The viewer and reference toolkit are independent implementations too; their agreement through the corpus is the interoperability check.

vibe-qc pins one QVF release, v0.4.0 (commit 702c1b602beb30972874e6d336b082d6a0b691e4), as QVF_TAG in .gitlab-ci.yml. The QVF repository is the single master of the format: vibe-qc carries only byte-identical copies of that tag’s files, no derived or edited schema. Its manifest schema python/vibeqc/output/formats/qvf_manifest.schema.json is the tag’s spec/qvf_manifest.schema.json. The six included reference pages are vendored from the same tag. scripts/ci/check_qvf_schema.py checks all seven files byte for byte. The source paths for the pages are:

Vendored filename

Path in QVF

qvf-format-spec.md

spec/qvf-format-spec.md

GOVERNANCE.md

GOVERNANCE.md

README.md

conformance/README.md

integration_guide.md

docs/integration_guide.md

library_guide.md

docs/library_guide.md

orca_integration.md

docs/orca_integration.md

Keep provenance here so the copies remain identical to upstream. Do not edit docs/qvf/_vendored/ or the schema copy; change QVF upstream, then deliberately re-vendor and bump the pin. The snapshot builds without a sibling QVF checkout.

For reference-toolkit distributions, use the QVF release page. The legacy pre-split writer archive is preserved in the maintainer’s external private archive and is no longer distributed from this source tree.

What’s here

  • Format specification: the normative QVF v1 spec: archive model, manifest, the full section-kind catalog, units, extension governance, and the producer/consumer conformance checklists. Ships with the machine-readable qvf_manifest.schema.json.

  • Integration guide: start here if you write another QC code. The code-agnostic how-to: the two integration models, the data-mapping table, the wavefunction contract, and how to become an officially supported producer.

  • Library guide: build, link, and call the Python and C++ reference writers/readers; the section-kind cheat sheet.

  • ORCA integration guide: a complete worked mapping from a production code’s data (GBW-style wavefunction, spectra, EPR, scalar properties) onto QVF sections.

  • Conformance suite: the compliance target. A frozen corpus of reference archives paired with expected-value files, plus a language-agnostic runner, so you can prove your reader or writer is correct rather than that it happens to agree with one other implementation.

  • Governance: how QVF is stewarded, versioned, and evolved: an open standard created and stewarded by vibe-qc, producer-neutral by design, with a public registry and a vendor→canonical promotion process.

  • Tutorial: Adopting QVF: how to implement a writer in your own code.

Why adopt QVF

  • One artifact. A calculation travels as one file instead of a scatter of Cube / XYZ / Molden / XSF / log / sidecar files.

  • Typed and checksummed. Every member declares its dtype, shape, and a sha256; consumers verify integrity before use.

  • Partial support is safe. A consumer understands the kinds it knows and reports the rest; unknown vendor sections are never misinterpreted.

  • Extensible. The x_<vendor>.* namespace lets you ship data QVF doesn’t yet standardize, with a clear path to promotion.

Reference consumer

Anything the toolkit writes opens in vibe-view, the reference GPU viewer, and validates against vibe-qc’s validate_qvf(). To write your own reader, start from the consumer reference.