vibe-qc

Quantum chemistry for molecules and solids.

Current release: 0.7.3 — Whitten’s Bridge

The site you’re looking at renders the release branch — the fast-forward-only public snapshot. main is at a higher X.Y.dev0 development version; see release_process for the branch model. Per-release codenames (Scientist + Animal, loosely tied to whatever shipped) are catalogued in the release-codenames roadmap entry.

💚 vibe-qc is funded by individual sponsors

vibe-qc is built and maintained by one person in evenings and weekends, on personal hardware, with no institutional backing. If the project is useful to you — or if you think the Cyclic Cluster Model reaching CCSD(T) on an open-source code is worth existing — please consider supporting it via GitHub Sponsors (recurring monthly, zero fees) or Ko-fi (one-time, no GitHub account required). Every sponsorship directly funds the Claude Max subscription that drives day-to-day development plus the self-hosted server behind vibe-qc.com. See the support page for the full pitch; public sponsors are listed on the sponsors page.

✅ Periodic-SCF gauge fix landed in v0.7.0

The v0.6.x Madelung self-image leak — periodic SCF systematically over-bound in the molecular limit by an α_M·(Q_n² + Q_e²)/(2L) shift — is fixed in v0.7.0 (codename Löwdin’s Compass). The root cause was the FFT-Poisson J build sampling AOs aperiodically on the grid; periodic AO image-summing (evaluate_ao_periodic) restored translation invariance to FFT precision (~5e-6 Ha on H₂/STO-3G in a 30-bohr box, vs +0.587 Ha drift before).

v0.7 also ships a comprehensive linear-dependence + screening program that detects non-PSD overlap matrices, recommends pob basis sets / exp_to_discard filtering / cutoff tightening, and auto-optimises lattice cutoffs jointly with Schwarz screening (auto_optimize_truncation=True default in all 8 periodic SCF drivers). See the linear-dependence chapter for the diagnostic + fix walk-through, and CHANGELOG for the full set of new APIs.

⚠️ Tight ionic crystals — known v0.7.x deliverable

Dense ionic-crystal SCF on tight cells (e.g. LiH conventional rocksalt at the experimental lattice constant with STO-3G) still shows residual absolute-energy issues after the v0.7 gauge + linear- dep fixes. The linear-dep diagnostic catches the symptom (critical-severity overlap) and the auto_optimize_truncation optimiser makes the SCF run, but the converged absolute energy on these cases is not yet within basis-set error of published references — there is a deeper bookkeeping issue in the multi-cell density formula that v0.7.x will close. Tracked in tests/test_periodic_dense_ionic_bug.py and the analysis at examples/debug/PERIODIC_SCF_BUG_ANALYSIS.md.

For tight ionic crystals today, prefer pob-TZVP / pob-DZVP-rev2 (designed for solids; ship in vibe-qc) over molecular bases like STO-3G, and validate against PySCF.pbc when absolute energies matter. The automated parity test suite landing alongside v0.7.x will catch regressions automatically.

vibe-qc is a Python + C++17 electronic-structure code. The molecular stack — Hartree-Fock, density-functional theory, Møller-Plesset theory, analytic gradients, D3(BJ) dispersion — is validated against PySCF to machine precision. The periodic stack delivers 1D / 2D / 3D Hartree-Fock and Kohn-Sham DFT with Monkhorst-Pack k-meshes, Ewald-summed Madelung, band structure and density of states, and is growing toward CRYSTAL-style crystalline-orbital calculations at full-SCF accuracy.

Built on libint (Gaussian integrals), libxc (500+ XC functionals), and spglib (crystal symmetry). Licensed MPL-2.0.

Install

git clone https://gitlab.peintinger.com/mpei/vibeqc.git
cd vibeqc
./scripts/setup_native_deps.sh       # one-time, 15–40 min, idempotent
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'

git clone lands you on the latest tagged release (the project’s default branch is release, which fast-forwards from each new tag). For active development against main, add git checkout main. To pin to a specific tag for reproducibility, git checkout v0.4.6 (or whichever version matches your needs).

setup_native_deps.sh builds and installs every native dependency (libint, libxc, spglib, FFTW3, libecpint) into third_party/ and populates the bundled basis library. Re-running is a no-op if everything’s already built. Full per-platform dependency lists (macOS / Arch / Manjaro / Debian / Ubuntu) are in installation.

Your first calculation

Make a working directory outside the repo — vibe-qc writes its outputs into the current working directory, and you don’t want .out / .molden / .traj files landing inside the source tree:

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

Save the following as water.py in that directory (any filename works — vibe-qc just runs whatever Python you point it at):

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]),
])

run_job(
    mol,
    basis="6-31g*",
    method="rks",
    functional="PBE",
    dispersion="d3bj",
    optimize=True,
    output="water",
)

Run it with the virtual-env’s Python (the one pip install populated above, not your system python3). Since you’re no longer in the repo, give the full path:

~/path/to/vibeqc/.venv/bin/python water.py

Replace ~/path/to/vibeqc/ with wherever git clone landed. That ~3-second run produces three files in ~/vibeqc-runs/water/:

  • water.out — banner, SCF trace, energy breakdown, orbital table, HOMO-LUMO gap, Mulliken / Löwdin charges, Mayer bond orders, dipole, and wall-clock timings.

  • water.molden — molecular orbitals for Avogadro / Jmol.

  • water.traj — ASE trajectory for the optimization, viewable with ase gui water.traj.

Tip

Skip the path prefix. Activate the venv once per shell session and the path resolves automatically — works from any directory:

source ~/path/to/vibeqc/.venv/bin/activate    # bash / zsh
python water.py                                # uses the venv's python

Deactivate with deactivate when you’re done.

Common mistake: ModuleNotFoundError: No module named 'vibeqc' means you ran the wrong Python. Either give the full ~/path/to/vibeqc/.venv/bin/python path or activate the venv first. The bare .venv/bin/python shorthand only works when your shell is sitting inside the repo.

See quickstart for a 30-minute end-to-end walkthrough (HF, periodic SCF, orbital cube), running for the full “how to invoke vibe-qc scripts” reference (venv, threading, output capture, SSH workflows), good practices for the working conventions nobody tells you (file layout, naming, when to trust a number), the tour for the wider API surface (run_job, ASE Calculator, logging, custom basis sets, tests), or dive into the tutorials for worked examples.

Capabilities today

Molecular. Restricted and unrestricted HF / KS-DFT. Analytic nuclear gradients. Second-order Møller-Plesset (MP2 / UMP2). Grimme’s D3(BJ) dispersion wired through run_job, with analytic forces for optimization. 90 standard basis sets plus the solid-state pob-* family. All validated against PySCF to machine precision.

Periodic. 1D / 2D / 3D PeriodicSystem geometry, Monkhorst-Pack k-meshes with IBZ reduction, Γ-only and multi-k RHF, multi-k KS-DFT with LDA and GGA functionals. Ewald summation for point-charge Madelung and Ewald-screened nuclear attraction. Band structure and density-of-states plotters. Gaussian cube + XSF / BXSF writers for molecular and periodic volumetric data.

Tooling. OpenMP parallelism throughout. Pre-flight memory budget estimator. ASE Calculator integration for geometry optimization and vibrational frequencies.

See the feature matrix for details and the roadmap for what’s next.

Where to go next

Getting started

User guide

Reference

Project

Status

vibe-qc is pre-release software. Molecular HF/DFT/MP2 is stable and production-ready for small-to-medium systems; periodic calculations converge cleanly in the molecular-limit regime and are being hardened for tight-cell bulk work. Follow the roadmap for what’s shipping next.

Licensed under the Mozilla Public License 2.0. Source at gitlab.peintinger.com/mpei/vibeqc.

Feedback and bug reports

Found a bug, have a feature request, or want to send a patch? The decision tree lives in CONTRIBUTING.md. The short version: