QVF and vibe-view

A vibe-qc calculation does not have to leave behind a scatter of .cube, .molden, .xyz, .xsf and log files. It can leave behind one file: a .qvf archive carrying the structure, the wavefunction, scalar fields, spectra, bands, trajectories, the run’s provenance, and its citations, each member typed and checksummed.

QVF is that format. vibe-view is the reference viewer that reads it, in a browser, in a terminal, as a desktop app, or headlessly from Python.

This section is the whole story in one place: what a .qvf is, how to produce one, the four ways to read one, and how to emit QVF from a quantum-chemistry code that is not vibe-qc.

The reading order

Everything below is also in the sidebar. If you are starting cold, this is the path.

1. Understand the format. Start with The QVF file format, end to end: what the archive contains, the manifest, and the section-kind catalog group by group. Then Running a calculation as a QVF container for the other direction, a .qvf that carries the request as well as the result and settles in place when it runs.

2. Produce one. Every run_job / run_periodic_job call can write a .qvf directly; QVF job containers is the user-guide reference for the container lifecycle. If you want the archive without going through the runner, the writer API is covered in the format tutorial above.

3. Read one. Four routes, in rough order of how much you need on the machine you are sitting at:

Route	Command	Needs
Browser viewer	vibe-view open job.qvf	a GL context, the [viewer] extra
Terminal	vibe-view show / vibe-view tui	NumPy only ([tui] extra for the interactive half)
Desktop app	double-click a .qvf	the packaged app
Headless / Python	vibe-view capture, render_terminal, QVFReader	nothing beyond the base install

• The browser viewer, panel by panel: vibe-view: an end-to-end walkthrough, then vibe-view: interactive viewer as the reference.

• The terminal UI: Reading a .qvf in the terminal, over SSH for the worked example, Terminal mode for the full show / tui surface, key map and rendering modes.

• The desktop app: vibe-view desktop app.

• Headless capture, exports, compare mode and the scripted workflows: Working with vibe-view.

• Proteins and other biomolecules, cartoon rendering, chains, residues and b-factors: Biomolecules.

• Reading a .qvf from your own Python, with the verify-before-use contract: QVF consumer reference.

4. Watch a job as it runs. Live reload hot-reloads the scene as a running calculation rewrites its checkpoint, and the vq Job Manager turns the viewer into a cockpit for the vq queue: submit, monitor, fetch, open.

5. Emit QVF from your own code. Adopting QVF: how to implement a writer in your own code is the tutorial; The QVF format toolkit hosts the normative specification, the Apache-2.0 reference writers in Python and C++, the integration and library guides, a worked ORCA mapping, and the governance model.

Related pages elsewhere in the docs

• QVF format design, the design document behind the format (rationale, trade-offs, the full section-kind reference).

• QVF basis-section design, the basis.ao contract.

• Viewing geometries, orbitals, and vibrations with MolTUI, a format-agnostic terminal viewer for the loose .molden / .cube / .xyz files vibe-qc also writes.

• Orbital visualization and XSF / BXSF visualization, for the non-QVF output routes.

The QVF format

• The QVF file format, end to end
• Running a calculation as a QVF container
• QVF job containers: one file, whole lifecycle
• QVF consumer reference: reading a .qvf file in Python

Reading a QVF with vibe-view

• vibe-view: an end-to-end walkthrough
• vibe-view: interactive viewer
• Reading a .qvf in the terminal, over SSH
• Terminal mode
• Working with vibe-view
• Biomolecules: cartoon rendering, chains and residues
• vibe-view desktop app (macOS, Windows, Linux)

Live jobs

• vq Job Manager
• Live reload (auto-reload on file change)

Adopting QVF in another code

• Adopting QVF: how to implement a writer in your own code
• The QVF format toolkit

Other viewers

• Viewing geometries, orbitals, and vibrations with MolTUI