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-viewer 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 on GitHub: specification, JSON schema, registry, conformance corpus, and reference implementations. Clone it anonymously with git clone https://github.com/vibyverse/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.6.0 (commit 9d6b4effc3e3ebb05f5eb53acfdbce11a0a34fb6), 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-viewer, the reference GPU viewer, and validates against vibe-qc’s validate_qvf(). To write your own reader, start from the consumer reference.

Supplied transition-density grids

vibeqc.output.formats.qvf.write_qvf and qvf_bytes accept transition_density_data={label: {"data": grid, "origin": origin, "span": voxels}}. The real, three-dimensional grid is the spin-summed transition density in e/bohr³. Origin and the three row voxel vectors are in bohr. Values retain their sign and scale; this interface serializes an already computed density and does not generate one or substitute an excited-minus-reference difference density.

Each record may add excited_states_ref="excited_states" and state_index=1 when the corresponding state is supplied in excited_states_data. The writer rejects unresolved references, invalid indices, malformed grids and nonfinite values. An index requires the reference. Both links may be omitted for a standalone grid. Default volume storage is float32; use volume_dtype="float64" to preserve float64 data. The emitted canonical volume.transition_density section is checked against the pinned QVF schema and uses the viewer’s scalar volume reader. The format definition and state-link rules are in sections 5.2 and 6 of the specification.