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 a standalone viewer and conversion tool that reads it in a browser, in a terminal, as a desktop app, or headlessly from Python. It also opens selected structure and volume formats from Gaussian, ORCA, VASP, molecular-dynamics tools, and other producers.

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.

Choose your route

Everything below is also in the sidebar. Start with the row that describes what you already have:

Goal	Start here
Try the viewer with no calculation or input file	Install the current checkout, then run vibe-view demo in Getting started with vibe-view alone.
Open a QVF in a browser	vibe-view open job.qvf; use the browser walkthrough for the panels.
Work over SSH with no display	vibe-view show job.qvf or vibe-view tui job.qvf; see Terminal mode.
Open a file from another chemistry code	Check Input formats and interoperability, then use vibe-view open INPUT; current checkout/next-wheel installs can persist it with import.
Use a native desktop window	Follow the desktop app guide.
Add QVF output to another code	Start with Adopting QVF in your own code.
Inspect or automate QVF from Python	Use the QVF consumer reference.

The product and shell command are spelled vibe-view. Its Python distribution and import package are spelled vibeview.

Learn the format and its tools

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	base install ([tui] extra for the interactive half); no display or GL context
Desktop app	vibe-view desktop job.qvf	[viewer] plus a source checkout; packaged artifacts are separate
Headless / Python	vibe-view capture, render_terminal, QVFReader	base install

• Only want the viewer? Getting started with vibe-view alone installs it without building vibe-qc, on Linux or macOS, and opens one of the sample archives that ship in the clone.

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

• Every command in one table, and which install extra each one needs: vibe-view command reference.

• Loose-file imports, data-preservation limits, and routes from other codes: Input formats and interoperability.

• 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.ao section design, the contract for a single atomic orbital sampled on a grid.

• QVF-Basis design, the canonical basis-set representation behind vibe-qc’s basis-set library.

• 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

• Getting started with vibe-view alone
• 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
• vibe-view command reference
• vibe-view Python API
• Input formats and interoperability
• 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