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.

Download the qvf-writer toolkit

A self-contained, Apache-2.0 distribution you can vendor into any code (including a proprietary one): the spec, the JSON Schema, reference writers in Python and zero-dependency C++17, a validator, and worked examples.

⬇ Download qvf-writer-0.1.0.tar.gz

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.

  • 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.