vibe-qc

Quantum chemistry for molecules and solids.

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 is growing toward CRYSTAL-style crystalline-orbital calculations at full-SCF accuracy. COOP/COHP bonding analysis and periodic Mayer bond orders are available for 1D/2D/3D systems.

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

Current release: 0.15.42 - Neese’s Cheetah

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, the self-hosted server behind vibe-qc.com, and - most urgently - bigger hardware: the project currently develops on a single Apple M2 laptop, and that’s what caps every regression test, CI benchmark, and CRYSTAL-Tutorial port to small systems. Smallest single actionable item right now: the NIST Crystal Data SRD 3 single-user subscription at $200/year - fully fundable by one sponsor for a year, and unlocks programmatic access to a curated crystallographic database for the CCM reference work. See the support page for the full pitch and the near-/long-term hardware goals; public sponsors are listed on the sponsors page.

🖥️ macOS desktop auto-update is donation-gated

The vibe-view desktop app already checks the update feed and notifies you when a newer build ships - but on macOS it cannot install the update by itself. Apple only lets an app self-update if it’s signed with a paid Apple Developer ID (~USD 99/year); until that certificate is funded, the macOS app detects the new version and offers a manual Download… button instead of a hands-off restart-to-install. A single USD 100 donation - via GitHub Sponsors or Ko-fi - covers the certificate for a year and flips macOS to real auto-update, with no code change needed. (Linux and Windows self-update without any such certificate.)

✅ New in v0.15 (Neese’s Cheetah)

AI-generated Neese's Cheetah codename artwork for vibe-qc v0.15

v0.15’s headline features:

  • DLPNO local correlation – DLPNO-MP2 local density fitting, sparse pair lists, the DLPNO-CCSD per-pair solver, DLPNO-(T1), open-shell U-DLPNO-MP2 / U-DLPNO-UCCSD(T) pilots, and CCM DLPNO routes for the AICCM work.

  • TD-DFT engine – Casida + Tamm-Dancoff approximation for RHF/RKS/UHF/UKS, with Natural Transition Orbitals and UV/Vis spectrum reconstruction.

  • Production CASSCF analytic gradients – FD-tight to ~1e-7 (default compute_wz=False path); geometry optimization now uses the analytic gradient for state-specific closed-shell CASSCF.

  • Exact IC-CASPT2 analytic gradients – coupled orbital/CI response for unshifted, state-specific closed-shell CASSCF references on the explicit engine, FD-pinned on H2 and core-containing LiH.

  • Eigensolver framework – Davidson (iterative Fock diagonalization), LOBPCG (3-12x faster), plus experimental Jacobi-Davidson and GPLHR; selectable by solver= keyword.

  • Periodic-DFT accuracy fix – cross-cell XC density now correct on dense ionic crystals (MgO/STO-3G within ~1 mHa of CRYSTAL23).

  • COOP/COHP bonding analysis (C++ kernels, QVF, plotters, vibeqc coop CLI), QTAIM topological analysis (critical-point search, bond-path tracing), periodic Mayer bond orders (k-space generalization).

  • QVF v1.2 – localized orbitals, bond orders, fat bands, and QTAIM sections; vibe-view consumption; runner auto-population.

Also new: the basis_toolkit import/export system, periodic COSX and Mixed Density Fitting (MDF), the geometry-optimizer framework, the AICCM cyclic cluster model (Γ-CCM + χ-CCM, experimental), GAPW experimental warning gating, and more.

See CHANGELOG for the full notes.

🔜 Current focus: v0.15.x release-paper hardening

The 0.15.x line is the release-paper hardening series: gate-red fixes, periodic accuracy cleanup, complete reproducibility artifacts, and visualization-ready QVF outputs for the AICCM/CCM work. New minor-version feature promises stay off the homepage until the paper is submitted.

See the roadmap for the full plan.

For the current open-issues list (workarounds, regression-test pointers, status of each known bug), see troubleshooting and the issue tracker.

Install

git clone https://gitlab.peintinger.com/mpei/vibeqc.git
cd vibeqc
./scripts/install.sh                 # native deps + venv + pip install + banner

install.sh accepts --dev (main), --branch NAME (any branch or tag), and other knobs, see installation.md for the full surface and the manual setup_native_deps.sh recipe. git clone lands you on the latest tagged release (the project’s default branch is release, which fast-forwards from each new tag); add --dev for bleeding-edge main or --branch vX.Y.Z to pin a specific tag for reproducibility.

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 with analytic nuclear gradients. The full libxc functional library, LDA, GGAs, hybrids, the τ-dependent meta-GGA family (TPSS, M06-2X, SCAN, r²SCAN, r²SCAN01), range-separated hybrids (ωB97X, ωB97X-D, and the VV10-paired ωB97X-V / ωB97M-V), and the PW1PW weighted-sum functional, all supported. Møller-Plesset theory (MP2 / UMP2 / RI-MP2 / SCS-MP2 / SOS-MP2 / open-shell UMP2) and the B2PLYP / DSD-PBEP86 / revDSD-PBEP86-D4 double hybrids. Density fitting with the RIJK and RIJCOSX Fock-build kernels (RIJCOSX validated to 0.13 mHa vs ORCA 6.1.1). Effective core potentials for heavy-element chemistry. CPCM / COSMO implicit solvation via the SolutePotentialProvider seam. Grimme D3(BJ) / D4 dispersion. 239 bundled Gaussian basis files, including the solid-state pob-* family. All validated against PySCF and ORCA.

Wavefunction methods. Canonical CCSD(T), the gold-standard molecular correlation reference: closed-shell, plus open-shell (UCCSD / UCCSD(T) on a UHF reference, ROHF-reference CCSD / CCSD(T)) and frozen natural orbitals for cheaper (T). DLPNO-CCSD(T), the near-linear-scaling local CCSD(T) accurate to ~1 kcal/mol vs canonical, plus open-shell DLPNO-UMP2 and DLPNO-UCCSD(T) pilot. The DLPNO-(T1) scaling-preserving exact triples. Multi-root CASCI with state-averaged CASSCF (analytic nuclear gradient FD-tight to ~1e-7, shipped in v0.15.0). TDDFT via the Casida linear-response formalism and the Tamm-Dancoff approximation (RHF/RKS/UHF/UKS), with Natural Transition Orbitals and FD excited-state gradients. Eigensolver framework: Davidson, LOBPCG (GF2 / OVGF, renormalised GF2). The vibeqc.solvers family, Full CI, selected CI, DMRG, variational 2-RDM, via vibeqc.solvers. General atomisation energies and RRHO thermochemistry.

Semiempirical + MLIP. The MSINDO semiempirical engine covers elements H-Br (Z 1-35, including 3d and 4th-row p-block), supports NDDO mode, molecular geometry optimisation, implicit solvation (COSMO), NEB, velocity-Verlet molecular dynamics, well-tempered metadynamics, and penalty-function MECI conical-intersection optimisation. The MACE machine-learning interatomic potential (method="mace") is available as an alternative energy surface. GFN2-xTB rounds out the semiempirical roster.

Periodic. 1D / 2D / 3D PeriodicSystem geometry, Monkhorst-Pack k-meshes with IBZ reduction. Native Gaussian density fitting (GDF, Γ-point RHF / RKS + hybrids, multi-k KRHF / KRKS; µHa parity vs PySCF on LiH) and the production GPW (Gaussian Plane Waves) route through run_periodic_job (Γ-only RHF / UHF / RKS / UKS, multi-k pure-DFT RKS; the MPI grid overlay is experimental). The BIPOLE route covers Γ + multi-k RHF / UHF / RKS / UKS: multi-k KS analytic gradients with space-group symmetry and multipole L=3, closing the BIPOLE analytic gradient gate. 3D Ewald with CRYSTAL-α gauge unification. Fermi-Dirac, Methfessel-Paxton, and Marzari-Vanderbilt smearing for metals, with Anderson / Broyden / Kerker density mixers and an AUTO k-point and smearing recommender. MSINDO periodic CCM through bulk MgO (Wigner-Seitz, periodic INDO, Ewald Madelung). Experimental ab-initio CCM: two independent lines, Γ-CCM (union-and-weight/Wigner-Seitz integral weighting, HF→CCSD(T)) and χ-CCM (finite-character, 3D SCF + finite-torus correlation). They are under active side-by-side study on a 28-system benchmark, but no cross-approach delta is currently reportable. Band structure and density-of-states plotters. COOP/COHP bonding analysis (Crystal Orbital Overlap/Hamilton Population; C++ kernels, QVF, plotters, vibeqc coop CLI). Periodic Mayer bond orders (k-space generalisation). Fat bands (Mulliken-projected band weights). QTAIM topological analysis (critical-point search + bond-path tracing). Gaussian cube + extended-XYZ + POSCAR + XSF / BXSF writers, plus POSCAR and Extended-XYZ readers and CIF readers with opt-in geometry symmetrisation.

Tooling. OpenMP parallelism throughout; optional mpi4py substrate for future MPI parallelism (GPW grid overlay experimental; production strategy in MPI Parallelization). Pre-flight memory budget estimator. ASE Calculator integration for geometry optimization, vibrational frequencies, and NEB. Automatic per-job citation files (.bibtex / .references). The vibe-view interactive 3D viewer for structure / orbitals / densities / bands / COOP/COHP / spectra / trajectories out of every .qvf archive (QVF v1.2, 40 canonical writer kinds: 39 first-class viewer kinds plus bonds via the structure renderer). The basis_toolkit for basis-set import/export (BSE, CRYSTAL, G94, NWChem, ORCA). The vq queue for remote job submission.

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

Where to go next

Getting started

Tutorial

User guide

Design documents

Reference

vibe-view

QVF format toolkit

vq

Project

Status

vibe-qc is pre-release software heading toward a 1.0 feature-complete milestone. The molecular stack (HF/DFT/MP2/CCSD(T)/DLPNO-CCSD(T)/ TDDFT/CASSCF) is stable and production-ready. The periodic stack supports three production routes: GDF (µHa parity vs PySCF), GPW (Gaussian Plane Waves with Γ-point analytic gradients; MPI grid overlay experimental), and BIPOLE (Ewald-J with multi-k KS analytic gradients). The eigensolver framework (Davidson / LOBPCG + experimental Jacobi-Davidson / GPLHR) is selectable by keyword. Analysis tools (COOP/COHP, QTAIM, Mayer bond orders, fat bands) and the basis_toolkit import/export system shipped in v0.15.0. The ab-initio CCM (Γ-CCM and χ-CCM) ships as experimental. Follow the roadmap for what’s 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: