vibe-viewer

For renamed products, supported legacy commands, and unchanged package/state identities, see the naming compatibility guide.

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-viewer 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 users: an ORCA calculation opens as one dataset: the structure, orbitals, vibrations with IR, Raman and VCD, the UV-Vis, ECD and MCD spectra and the properties from its companion result files. The viewer also prepares an ORCA input from an edited structure and submits it through vq, and two worked tutorials ship with it: water end to end and Raman and VCD along normal modes.

Tip

This manual describes the current source, with package version 3.0.2, Levinthal’s Lynx. 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.12+, 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

Build, inspect and present

Build a structure, set its geometry exactly, inspect surfaces and interactions, make a figure and prepare the calculation.

Build, inspect and present

CLI reference

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

CLI reference

ORCA step by step

Open a calculation with its companions, view orbitals, vibrations and spectra, then prepare and submit the next input.

ORCA: from calculation to one viewer dataset

Clusters and calculations

Install on a login node, run vq with no queue, SLURM or PBS, and submit calculations from the viewer.

Clusters and remote machines

Headless and Python

Figures, tables and exports for a directory of results, with no window.

Figures without a display

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-viewer open FILE	[viewer] extra	Interactive exploration, editing, the vq job panel
Desktop	vibe-viewer desktop FILE	[viewer] + Electron, source checkout	A native window with the OS menu bar
Terminal	vibe-viewer tui FILE / vibe-viewer show FILE	[tui] extra (show needs nothing)	A login node with no display server, GL or X forwarding
Headless	vibe-viewer 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-viewer 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 TD-DFT excited states	Excited states	A table of states with their energies, strengths and orbital contributions, and the transition orbitals they link to
Set up the viewer and vq on a cluster, with or without SLURM or PBS	Clusters and remote machines	A working viewer on the login node and a queue that submits to the batch system
Prepare and submit a calculation, or add a program	Supported programs and calculations	A registered program, a submitted job and its results in the viewer
Use vibe-viewer with vibe-sketcher and vibe-qc	vibe-viewer with vibe-sketcher and vibe-qc	A drawn molecule calculated with vibe-qc and inspected in 3-D
Draw a molecule and open it in 3-D	Sketching in vibe-sketcher	A structure with its charge and multiplicity, ready to edit or calculate
Build a molecule, peptide, nucleic acid or metal complex	Molecular construction, tutorial	A starting geometry with explicit connectivity, ready to refine
Set a bond length, angle or dihedral exactly, or edit coordinates as numbers	Exact geometry, coordinate editor	A prepared geometry, a Z-matrix or a coordinate block
Show surfaces, hydrogen bonds and contacts	Molecular surfaces and interactions	Surfaces with area and volume, and an interaction table
Look at an experimental density map	Experimental maps	A map at a sigma level, zoned around a ligand
Make a labelled figure or a morph movie	Publication figures	A figure with labels, overlays and a colour key, or a movie
Compare and align several models	Model scenes, selection language	An aligned scene with measurements and a replayable script
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
  • Choose an installation route
  • What you need for a source installation
  • 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
• Correlated reaction endpoint analysis
  • Select and review
  • Walk through the scientific evidence
  • QVF representation and compatibility
• 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
• Build, inspect and present
  • 1. Start a structure
  • 2. Set the geometry exactly
  • 3. Inspect surfaces and interactions
  • 4. Present the result
  • 5. Compare models in one scene
  • 6. Prepare the calculation
  • 7. The same steps in Python
  • Where next
• What vibe-viewer 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

Calculations and clusters

• Supported programs and calculations
  • What each program supports
  • Choose the submission route
  • Register a program with vq
  • Submit a calculation: a worked example
  • vibe-qc jobs for a cluster
  • Add a program the viewer does not know
• Preparing native calculation inputs
  • Program capabilities and defaults
  • Queue submission
  • SDK
  • Recorded syntax references and acceptance
• Clusters and remote machines
  • 1. Install the viewer on a cluster
  • 2. Install vq
  • 3. A machine with no queue
  • 4. A SLURM or PBS/Torque cluster
  • 5. Watch a running job
  • 6. Figures as batch jobs
  • Troubleshooting
• vibe-viewer with vibe-sketcher and vibe-qc
  • Install them side by side
  • Draw in vibe-sketcher, continue in 3D
  • Get results from vibe-qc
  • Features that use vibe-qc
  • A complete round trip

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, inspecting and presenting
• Building and editing structures
  • Edit mode
  • Set exact distances, angles and dihedrals
  • Edit bonds explicitly
  • Drag atoms and selections
  • Detect molecular symmetry
  • Save coordinates and break symmetry
  • Displace along a normal mode
  • Fragments and hydrogens
  • Sketching a molecule in vibe-sketcher
  • 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-viewer show
  • vibe-viewer 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
  • Opening files and quitting
  • First run: the setup screen
  • macOS: double-click a .qvf
  • Linux
  • Windows
  • Troubleshooting
  • Self-contained Linux desktop
  • Python console
• Figures without a display
  • Setting up a headless host
  • vibe-viewer capture
  • Keep a figure reproducible
  • vibe-viewer batch
  • vibe-viewer animate
  • Export
  • Tables and data
  • The capture API
  • The animation API
  • Recipes

Building, inspecting and presenting

• Molecular construction
  • Builder panel
• Nanotubes and tube–metal interfaces
  • Building a tube
  • Adding a metal or a linker
  • Seeing a large structure
  • Interface analysis
  • Growth and reaction-path playback
  • Figure cues and capture
  • Terminal scale
• Internal-coordinate API
  • Coordinate editor
• Molecular surfaces and geometric interactions
  • Selection
  • Surfaces, colours and numerical meaning
  • Interaction definitions
  • Python use
• Atom selection language
  • Measurements in Python
• Experimental map coordinates
  • Map control panel
• Publication figures and morph movies
  • Scriptable stored-field recipes
  • Interactive figures
  • Morph export
  • Acceptance checks
• Multi-model scene API
  • Save and replay
  • Command interpreter
  • Browser working scene

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
  • Native formatted checkpoint and Molden wavefunctions
• Database structures, ensembles and sequences
  • Files, models and alternate locations
  • Residue selection and secondary structure
  • Sequence-based superposition
  • Reproducible source checks
• Cartoon display and producer metadata
  • 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-viewer 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-viewer
  • Full surface
  • Specialised modules
  • 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
  • Which queue and files are used?
  • It is not in [all]
  • 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
  • Validation says NOT CHECKED
  • error, sha256 mismatch or ManifestValidationError
  • Headless capture fails
  • Nothing works over SSH
  • vibe-viewer desktop will not launch
  • The installation is in a strange state
  • Reporting a bug
• Client performance
  • Which renderer your browser uses
  • What is measured
  • The measured matrix
  • The limits
  • Measuring your machine
  • Large structures

The project

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

Where things live

vibe-viewer 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-viewer	This viewer	you are here
vibe-qc	The quantum-chemistry program; one QVF producer	vibe-qc.com/docs/
vibe-scheduler (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