Start here

Use this page to choose the shortest correct route. vibe-qc and vibe-view are related, but they solve different problems:

• vibe-qc is the calculation engine. It has a compiled C++ core and needs the native build prerequisites described in Installation.

• vibe-view reads .qvf calculation archives. It can be installed by itself and does not need the vibe-qc C++ core.

Choose your route

I want to…	Install	First destination
Run molecular or periodic calculations	vibe-qc	Engine installation
Open a .qvf somebody sent me	vibe-view only	Viewer-only installation
Calculate and inspect results on one machine	vibe-qc and vibe-view	Install both
Learn molecular quantum chemistry	vibe-qc	Molecular learning path
Model crystals, slabs, or wires	vibe-qc	Periodic learning path
Read results over SSH without graphics	vibe-view core or TUI	Terminal mode
Submit and monitor remote work	vibe-qc, vq, optionally vibe-view	Remote-job tutorial

The repository currently requires access to the private GitLab project. If you do not already have access, follow Request repository access. A downloaded vibe-view wheel can be installed without cloning the repository.

Install the calculation engine

The recommended installer owns the entire bootstrap: it checks the host, builds the pinned native libraries, creates .venv, installs the Python package, and prints a verification banner.

git clone ssh://git@gitlab.peintinger.com:26/mpei/vibeqc.git
cd vibeqc
./scripts/install.sh

The first native build normally takes 15 to 40 minutes. Later runs reuse the finished dependency trees. Choose a different source line explicitly when needed:

./scripts/install.sh --release       # latest tagged public snapshot
./scripts/install.sh --dev           # rolling main development branch
./scripts/install.sh --branch <tag-or-branch>

Do not reuse .venv from another checkout. An editable installation records the checkout and native-library paths it was built against.

Verify the engine

Run the interpreter from the environment you just created:

.venv/bin/python -c "from vibeqc import print_banner; print_banner()"
.venv/bin/python -c "import vibeqc; print(vibeqc.__file__)"

The first command should print the vibe-qc version and the linked libint, libxc, spglib, libecpint, FFTW, and BLAS versions. The second path should point into this checkout. If it points elsewhere, stop and repair the environment before running calculations.

The complete platform package lists, manual build, BLAS choices, cluster notes, and failure messages live in Installation.

Install only the viewer

vibe-view needs no local compiler or native build. Its Python package installs compiled VTK as a prebuilt wheel; CMake, libint, and the vibe-qc engine are not required.

From the hosted wheel

Download the wheel linked from Getting started with vibe-view alone, then create a dedicated environment:

python3 -m venv .venv-viewer
source .venv-viewer/bin/activate
python -m pip install './vibeview-2.15.1-py3-none-any.whl[all]'
vibe-view --version

The wheel provides the Python command, browser viewer, terminal modes, and headless tools. The source-backed Electron launcher and repository sample archives require a checkout.

From a source checkout

git clone ssh://git@gitlab.peintinger.com:26/mpei/vibeqc.git
cd vibeqc
./vibe-view/scripts/install.sh
source vibe-view/.venv/bin/activate
vibe-view --version

Add --with-electron to download the reviewed Electron runtime during installation instead of at first desktop launch. The standalone viewer installer does not build or install vibe-qc.

Install both

Two environments are the easiest arrangement to understand and update:

<vibe-qc-checkout>/.venv/             calculation engine
<vibe-qc-checkout>/vibe-view/.venv/   viewer

Install each with its own script, then activate the one needed for the current command. The .qvf file is the interface between them, so the two processes do not need to share a Python environment.

If one combined environment is important, activate the vibe-qc environment and install the local viewer package into it:

source .venv/bin/activate
python -m pip install -e 'vibe-view[viewer,tui]'
vibe-view --version
python -c "import vibeqc; print('vibe-qc import: ok')"

This pip route is written as two package installations because pip does not use the repository’s uv-only local source mapping. With uv, the combined extra is available directly:

uv pip install -e '.[viewer-gpu]'

Run the first calculation

Keep calculations outside the source checkout. This separates source files from output archives and makes git status meaningful.

mkdir -p ~/vibeqc-runs/water
cd ~/vibeqc-runs/water

Save this as water.py:

from vibeqc import Atom, Molecule, run_job

mol = Molecule([
    Atom(8, [0.0,  0.00,  0.00]),
    Atom(1, [0.0,  1.43, -0.98]),
    Atom(1, [0.0, -1.43, -0.98]),
])

result = run_job(
    mol,
    basis="6-31g*",
    method="rhf",
    output="water",
    output_qvf=True,
)

print(f"converged = {result.converged}")
print(f"energy    = {result.energy:.10f} Ha")

Run it with the engine environment’s interpreter:

<vibe-qc-checkout>/.venv/bin/python water.py

Check three things before moving on:

1. converged = True appears.

2. water.out contains the version banner, SCF trace, and final energy.

3. water.qvf exists and passes vibe-view info water.qvf when the viewer is installed.

Then follow Quickstart for open-shell, periodic, and orbital examples, or Planning a calculation before choosing a production method and basis.

A result is ready to use when

Installation success and scientific success are different checks. Before using a number in a report or paper, verify:

• the SCF and any post-SCF method converged;

• the charge, multiplicity, geometry units, basis, and method are the ones intended;

• the basis and numerical grid are converged for the quantity being compared;

• the memory estimate fits the actual job allocation;

• the .system, .references, and .bibtex provenance files are retained;

• energy differences compare like with like, including dispersion, solvation, frozen-core, smearing, and reference-state choices.

Good practices turns this checklist into a repeatable working convention. Troubleshooting starts from the exact error or numerical symptom when a check fails.

Where to go next

Goal	Continue with
Learn what the first script does	Molecular Hartree-Fock
Choose a method, basis, and resource budget	Planning a calculation
Browse runnable inputs by task	Examples
Understand every output file	Output files
Explore a QVF visually	QVF and vibe-view
Use the API as a reference	User guide and API