vibe-view

Open a quantum-chemistry result and look at it. In a browser, a native desktop window, a terminal over SSH, a headless figure pipeline, or Python.

vibe-view reads QVF calculation archives and a set of common structure and volume formats. It is a standalone tool: installing it does not install or build vibe-qc. vibe-qc is one QVF producer among others, and none of them is required to run the viewer.

ORCA calculations open as one dataset with a shared structure, supported orbitals, spectra and properties from their companion result files.

Tip

This manual describes the current source, with package version 2.20.16, Levoy’s Lemur. Source updates may precede packaged installers; see the roadmap and changelog for released scope.

Open the built-in water demo in the quickstart.

Start here

Install

Python 3.11+, one script, no compiler. Which optional extra buys you what.

Installation

Quickstart

A first successful view, with a bundled molecule, expected output and commands you can run in sequence.

Quickstart

A tour of the viewer

Panel by panel: structures, densities, orbitals, spectra, bands, and the same file in the terminal and from Python.

A tour of the viewer

CLI reference

Every command, grouped by what you are trying to do.

CLI reference

Choose how to use the viewer

Choose a surface for the task and the machine you have. They read the same archive, but differ in interaction, rendering and export support. Browser and desktop use the interactive 3-D scene; the terminal uses a text rasterizer; PNG capture uses an offscreen renderer. Camera and material settings need to be matched when comparing images.

Surface	Command	Needs	Good for
Browser	vibe-view open FILE	[viewer] extra	Interactive exploration, editing, the vq job panel
Desktop	vibe-view desktop FILE	[viewer] + Electron, source checkout	A native window with the OS menu bar
Terminal	vibe-view tui FILE / vibe-view show FILE	[tui] extra (show needs nothing)	A login node with no display server, GL or X forwarding
Headless	vibe-view capture / batch / export	Core install only	Figures for a paper, CI artifacts, batch pipelines
Python	from vibeview import ...	Core install only	Notebooks, scripts, anything programmatic

vibe-view show is worth singling out: it renders a real 3-D view, atoms, bonds and isosurfaces, as Unicode braille, needs no OpenGL context at all, and therefore works anywhere a shell does.

What are you trying to do?

Task	Start here	What you will produce
Try the viewer without running a calculation	Quickstart	A water archive and its browser or terminal view
Turn an XYZ file into a result you can share	Worked workflows	A validated QVF, image and exported geometry
Explore an ORCA calculation	ORCA step by step	One dataset with structure, orbitals, spectra and properties, plus a shareable QVF
Run water through ORCA and vq	Worked ORCA water example	Tested inputs, downloadable results, orbitals, animated vibrations, IR and reference values
Understand a density or orbital	Guided tour	A view with a chosen section, sign and contour
Inspect a result on a remote machine	Terminal mode	A text view or an interactive terminal session
Inspect a protein or crystal	Biomolecules, periodic controls	Chain, residue or unit-cell views
Automate a directory of results	Python SDK, headless rendering	Metadata, tables and reproducible exports
Diagnose missing data or a blank view	Troubleshooting	The distinction between absent data and a rendering problem

Documentation

Getting started

• Installation
  • What you need
  • Install from a checkout
  • Source archives and downloads
  • Installation profiles
  • Optional extras
  • Windows
  • Desktop integration (macOS)
  • Updating
  • Repair and removal
  • Building a wheel locally
  • Comparing lifecycles across the toolset
  • Launcher records
• Quickstart
  • 1. Clone and install
  • 2. Check the installation
  • 3. Make a file to look at
  • 4. Look at it
  • 5. Ask it questions without opening anything
  • Already have data?
  • A figure, headlessly
  • From Python
  • Where to go next
• From input to a shareable result
  • 1. Copy a real input and import it
  • 2. Inspect before opening a window
  • 3. Export the right result
  • 4. Inspect the same archive from Python
  • Continue with an ORCA calculation
  • Continue with a calculated archive
  • Work remotely
  • Next workflows
• ORCA: from calculation to one viewer dataset
  • 1. Prepare the viewer and ORCA results
  • 2. Open the whole calculation
  • 3. Inspect the structure and properties
  • 4. View molecular orbitals
  • Harmonic vibrations, IR, Raman and VCD
  • 5. Explore electronic spectra and MCD
  • 6. Save a reusable QVF
  • 7. Work on a compute node or make a figure
  • Build and pre-optimise an ORCA starting geometry
  • Prepare, save and submit an ORCA input
  • Several calculations and Compound jobs
  • Troubleshooting and current limits
• Worked example: water through ORCA and vq
  • Get the example
  • 1. Prepare and save the input
  • 2. Submit, fetch and open
  • 3. Inspect the structure
  • 4. Render the HOMO and LUMO
  • 5. Compare energy, dipole and charges
  • 6. Keep and share your result
  • 7. Extend the example to vibrations and IR
• Worked example: Raman and VCD through ORCA and vq
  • 1. Get the example
  • 2. Prepare and submit
  • 3. Inspect Raman and VCD
  • 4. Compare the calculated results
  • 5. Interpret the example
  • 6. Compare both datasets and export spectra
  • 7. Resolve missing or unexpected spectra
• A tour of the viewer
  • 1. Something to look at
  • 2. Open it
  • 3. The structure
  • 4. Density and difference density
  • 5. Orbitals: stored and on demand
  • 6. Charges
  • 7. Vibrations and the IR spectrum
  • 8. Trajectories and reaction paths
  • 9. Convergence and provenance
  • 10. A periodic file
  • 11. Two files at once
  • 12. Save the views you found
  • 13. The same archive, elsewhere
  • Where next
• What vibe-view can show you
  • Structure and geometry
  • QTAIM topology
  • Volumetric fields
  • Wavefunctions, evaluated on demand
  • Periodic systems
  • Spectra
  • Things that change over a coordinate
  • Provenance
  • Which surface renders what
  • Import and export

The surfaces

• The browser viewer
  • Launch options
  • The startup banner
  • What is on screen
  • The Display card
  • Measuring
  • Clip plane
  • Section by section
  • Bookmarks, sessions and presentation mode
  • Screenshots, video and high-quality renders
  • viewer_defaults: hints from the producer
  • Opening files from inside the viewer
  • When something looks wrong
• Building and editing structures
  • Edit mode
  • Drag atoms and selections
  • Save coordinates and break symmetry
  • Displace along a normal mode
  • Fragments and hydrogens
  • Sketching a molecule in vibe-sketch
  • Building from a name or a SMILES string
  • Live optimisation while you build
  • Periodic structures
  • From structure to calculation
  • What the file on disk sees
• Terminal mode
  • Two commands
  • vibe-view show
  • vibe-view tui
  • What each section kind shows
  • Biomolecules
  • Rendering modes
  • Consistency with the other surfaces
  • From Python
  • Limits
• The desktop app
  • What is available today
  • Installing
  • First run: the setup screen
  • macOS: double-click a .qvf
  • Linux
  • Windows
  • Troubleshooting
• Figures without a display
  • Setting up a headless host
  • vibe-view capture
  • Keep a figure reproducible
  • vibe-view batch
  • vibe-view animate
  • Export
  • Tables and data
  • The capture API
  • The animation API
  • Recipes

Data and formats

• Input formats and interoperability
  • Open now, or import once
  • What this installation reads
  • Element identities
  • ORCA results
  • TREXIO wavefunctions
  • Routes from other programs
  • Writing an importer plugin
  • Before blaming the file
• Biomolecules
  • Getting the metadata into an archive
  • Drawing the cartoon
  • Outside the browser
• The QVF format, from the consumer’s side
  • The shape of a file
  • Optional geometry, orbital kinds and camera hints
  • Several structures, and which one is shown
  • What vibe-view refuses to open
  • Why an archive and not a directory of files
  • Vendor extensions
  • Which schema a file is checked against
  • Producing QVF files

Reference

• CLI reference
  • Getting started
  • Looking at a file
  • Asking questions
  • Figures, without a display
  • Building and reshaping archives
  • Queue
  • Configuration
  • Exit codes
  • Errors and debugging
• Python SDK
  • Numerical conversion convention
  • One argument type for every function
  • Inspecting
  • The structure
  • Volumes: summary or voxels
  • Tables
  • Comparing
  • Rendering
  • Slicing
  • Reading a file repeatedly
  • Launching the viewer
  • Jupyter
  • Release codename
  • Extending vibe-view
  • Full surface
  • API reference
• Jobs and live results
  • Live reload
  • The vq Job Manager
  • Submitting from the viewer
  • From Python
• Queue integration — the [queue] extra
  • What it gives you
  • Installing it
  • Without the extra
• Troubleshooting
  • Start here
  • A section, table or orbital is missing
  • Opening ORCA results
  • A mode will not start, or “No module named …”
  • The browser viewer
  • error, sha256 mismatch or ManifestValidationError
  • Headless capture fails
  • Nothing works over SSH
  • vibe-view desktop will not launch
  • The installation is in a strange state
  • Reporting a bug

The project

• Roadmap
• vibe-sketch and vibe-view: responsibilities
• Release codenames
• Release process
• Tests, builds and fast feedback
• Changelog
• Contributing
• Project history and internals

Where things live

vibe-view is one of the repositories split out of the private vibe-qc monorepo on 2026-09-08. Each is independently installable and separately versioned.

Project	What it is	Documentation
vibe-view	This viewer	you are here
vibe-qc	The quantum-chemistry program; one QVF producer	vibe-qc.com/docs/
vibe-queue (vq)	Job scheduler; the [queue] extra talks to it	its repository
qvf	The normative QVF specification and conformance corpus	its repository

Public source · Issues · Licence: MPL 2.0