Getting started with vibe-view alone

You will learn: how to install only the viewer, without compiling vibe-qc, and open a .qvf archive three different ways: in a browser, in a terminal with no graphics at all, and headlessly to a PNG. Commands are given for both Linux and macOS.

This is the page for you if somebody sent you a .qvf file, if you want to look at the archives that ship with the repository, or if you work on another quantum-chemistry code and want to see what the format looks like from the consumer side before deciding whether to write it. You do not need to run vibe-qc calculations for any of that.

Note

vibe-view does not need vibe-qc. It is a pure-Python package that reads .qvf archives, so pip install is all it takes: no C++ compiler, no libint/libxc/FFTW build, no setup_native_deps.sh. If you do want to produce archives of your own, follow installation instead and you get both.

Prerequisites: git, and Python 3.11 or newer (python3 --version). Nothing else.

Time to complete: about five minutes, most of it the download.

1. Clone over HTTPS

vibe-view lives in the vibe-qc repository, under vibe-view/. Clone it anywhere you like:

git clone https://gitlab.peintinger.com/mpei/vibeqc.git
cd vibeqc

That URL needs no account and no SSH key. The clone also brings the sample archives you will open in step 4.

Tip

Skip the clone entirely if you only want the program and not the samples. pip can install straight from the subdirectory:

pip install 'vibeview[all] @ git+https://gitlab.peintinger.com/mpei/vibeqc.git#subdirectory=vibe-view'

Then jump to step 4 and point vibe-view at your own .qvf.

2. Make a virtual environment

Keep the viewer out of your system Python. Same two commands on Linux and on macOS:

python3 -m venv .venv-viewer
source .venv-viewer/bin/activate

Your prompt now shows (.venv-viewer). Everything below assumes it is active; if you open a new shell, run the source line again.

3. Install the viewer

One command, identical on Linux and macOS:

pip install -e 'vibe-view/[all]'

[all] is the “give me everything” extra: the browser viewer, the terminal viewer, and the extra structure-format readers. It is the right choice while you are finding your feet. Nothing here compiles: the heaviest download is VTK, at roughly 200 MB, so the install takes a minute or two.

Check it landed:

vibe-view --version

vibe-view 2.11.2  -- Roothaan's Roadrunner
Python    3.14.6
PyVista   0.48.4
VTK       (9, 6, 2)

Installing less

The extras are tiered, so you can install only what you need:

Install

Gets you

Needs

pip install -e vibe-view/

reading archives, show, info, capture, export, diff

NumPy, VTK, matplotlib, Plotly

... 'vibe-view/[tui]'

the interactive terminal viewer, vibe-view tui

adds Textual

... 'vibe-view/[viewer]'

the browser viewer, vibe-view open

adds Trame and uvicorn

... 'vibe-view/[ase]'

VASP POSCAR, .extxyz, .traj and the rest of the ASE formats

adds ASE

... 'vibe-view/[all]'

all of the above

A headless capture box, a CI job, or a compute node needs no extra at all: rendering a PNG and reading an archive are in the base install. If you run a command whose extra is missing, vibe-view says which one and how to install it rather than failing obscurely.

4. Open a sample archive

Three archives ship in the clone, so you have something to look at before you have run anything:

File

What is in it

examples/vibe_view/runs/qvf_showcase/water.qvf

H2O RHF/6-31G*, 13 sections: structure, density, an orbital, the wavefunction, an optimisation trajectory, vibrations, an IR spectrum, charges, bond orders, SCF history, citations

examples/vibe_view/runs/h2co_showcase/h2co.qvf

formaldehyde, same shape without the trajectory

examples/vibe_view/output-nacl-showcase.qvf

periodic NaCl RKS/STO-3G: structure, density, total and projected DOS

Open the first one in your browser:

vibe-view open examples/vibe_view/runs/qvf_showcase/water.qvf

The viewer starts a small local web server and opens http://127.0.0.1:8080 in your default browser. The section browser is on the left, the 3D viewport in the middle, and the panels for the active section on the right. Click through the sections to see each one render. Press Ctrl+C in the terminal to stop the server.

Useful flags:

vibe-view open water.qvf --port 9876          # if 8080 is taken
vibe-view open water.qvf --no-browser         # start the server, open no browser
vibe-view open water.qvf -s vol_dens_0        # start on a named section
vibe-view open a.qvf b.qvf                    # a Files dropdown switches between them
vibe-view open a.qvf b.qvf --auto-compare     # ... and overlay them straight away

For the panel-by-panel tour of what you are looking at, read vibe-view: an end-to-end walkthrough.

5. Look at an archive without any graphics

You do not need a browser, a display, or an OpenGL context. Terminal mode renders the same scenes as Unicode braille:

vibe-view show examples/vibe_view/runs/qvf_showcase/water.qvf
vibe-view tui  examples/vibe_view/runs/qvf_showcase/water.qvf

show prints one frame and exits, so it pipes into a log or a file. tui is the interactive full-screen version; press ? for the key map and q to quit. This is the mode to use over SSH on a machine with no display server, which is usually where a .qvf is produced in the first place. Details in Terminal mode, worked through in reading a .qvf in the terminal, over SSH.

Before opening anything, you can also just ask what an archive holds:

vibe-view info examples/vibe_view/runs/qvf_showcase/water.qvf
vibe-view info examples/vibe_view/runs/qvf_showcase/water.qvf --short

6. Render a figure without opening anything

The base install can write images and other formats directly, which is what you want on a headless machine or in a script:

vibe-view capture water.qvf -o structure.png
vibe-view export  water.qvf -f xyz -o water.xyz
vibe-view batch   ./results -o gallery/          # a PNG per archive in a directory

If a capture fails complaining about a display or a GL context, set PYVISTA_OFF_SCREEN=True in the environment:

PYVISTA_OFF_SCREEN=True vibe-view capture water.qvf -o structure.png

Platform notes

Both. Everything above is pure pip. There is no compiler step, no conda, and no JavaScript build, so the commands are the same on Linux and macOS.

Linux. The browser viewer and PNG capture render through VTK, which wants a working OpenGL stack; on a minimal server or container image you may need your distribution’s Mesa/GL runtime (libGL.so.1) before open or capture will work. Terminal mode has no such requirement: it is a pure-NumPy rasteriser, so vibe-view show and vibe-view tui work on a bare compute node. If you are on a remote machine and want the browser UI anyway, forward the port:

ssh -L 8080:127.0.0.1:8080 you@remote-host
# then, on the remote host:
vibe-view open results.qvf --no-browser

and open http://127.0.0.1:8080 in the browser on your own machine.

macOS. Nothing extra is needed on either Apple silicon or Intel; the VTK and PyVista wheels are prebuilt. If you would rather double-click a .qvf than type a command, the packaged desktop app registers the file extension.

Coming from another quantum-chemistry code

You do not need vibe-qc to get value out of the viewer, and you do not need a .qvf to start. Point vibe-view open at files you already have and it converts them to an in-memory archive as it reads them:

vibe-view open geometry.xyz          # xyz -> qvf, done in memory
vibe-view open density.cube          # a scalar field on its grid
vibe-view open complex.pdb           # chains and residues, so the cartoon works

Read directly: .xyz, .cif, .cube, .pdb, .mol2, .gro, .sdf / .mol, and Gaussian input (.gjf / .com). With the [ase] extra you also get VASP POSCAR / CONTCAR, .extxyz, .traj and the rest of the ASE formats.

Two honest limits. .molden is not among them, so orbitals from a code that writes Molden files do not open directly today; for those, MolTUI reads loose .molden / .cube / .xyz in a terminal. And a converted file only carries what the file carries: a .cube has no wavefunction, no spectra, and no provenance, so most of the viewer’s panels stay empty.

That gap is the point of the format rather than a missing importer. Anything inside one archive gets a panel; anything scattered across sidecars does not. If you maintain a code and want its results to open with the full surface, the writer side is deliberately easy to adopt:

  • Adopting QVF in your own code, the tutorial: container model, the wavefunction normalization contract, the vendor namespace, and certification against the conformance corpus.

  • The QVF format toolkit, the normative specification plus reference writers in Python and in zero-dependency C++17, distributed under Apache 2.0 so it can be vendored into any code, including a proprietary one, independently of vibe-qc’s own MPL-2.0 licence.

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

A conforming producer is a few dozen lines on top of the reference library, and the archives it writes open in vibe-view with no viewer-side changes at all.

Getting your own .qvf files

Three routes, depending on where the data comes from:

  • From vibe-qc. Every run_job / run_periodic_job call already writes one, since output_qvf defaults to True. That needs the full vibe-qc install, so follow installation. vibe-view quickstart also runs a demo calculation and opens it, and it likewise needs vibe-qc present.

  • From the queue. vibe-view from-vq JOB_ID fetches a finished vq job straight into the viewer, and the vq Job Manager panel does it by clicking.

  • From another program. QVF is an open format with a standalone, Apache-2.0 reference writer, so a code that is not vibe-qc can emit archives vibe-view opens. See Adopting QVF in your own code.

vibe-view also opens ordinary structure files directly (.xyz, .cif, .pdb, .mol2, .gro, .sdf, .cube, Gaussian input, and with the [ase] extra the long tail), converting them to an in-memory archive as it reads them.

Next steps