Installation¶

vibe-qc is a Python package with a C++ core linked against libint (Gaussian integrals) and libxc (XC functionals). The C++ core is built from source once per checkout via CMake; Python dependencies come in through pip.

Requirements¶

Python ≥ 3.11
C++17 compiler (AppleClang 13+, GCC 10+, Clang 13+)
CMake ≥ 3.20 and Ninja
Eigen 3 (any 3.4+ or 5.x)
Boost (header-only usage)
GMP with C++ support (required by libint’s code generator)
libxc ≥ 6.0
FFTW3 (double precision) — reciprocal-space Poisson solver for the Ewald long-range Hartree piece
OpenMP (libomp on macOS; built into GCC on Linux)
git (for cloning libint)

Python dependencies (pybind11, scikit-build-core, numpy, pytest, pyscf, ase) are installed automatically by pip from pyproject.toml.

macOS¶

Install the system packages via Homebrew:

brew install eigen cmake ninja libomp boost gmp libxc fftw git

Apple Silicon note. Homebrew lives at /opt/homebrew on ARM Macs. vibe-qc’s CMake configuration runs brew --prefix and adds that to CMAKE_PREFIX_PATH automatically, so no manual path setup is needed.

Then build vibe-qc itself:

git clone <repo-url> vibeqc
cd vibeqc
./scripts/build_libint.sh            # 10-30 min, one-time
./scripts/setup_basis_library.sh     # seconds
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'

Linux — Debian / Ubuntu¶

Install system packages:

sudo apt update
sudo apt install \
    build-essential cmake ninja-build git \
    libeigen3-dev libboost-dev libgmp-dev libgmpxx4ldbl \
    libxc-dev libfftw3-dev \
    python3 python3-dev python3-venv

Note on libxc-dev: Debian / Ubuntu ship libxc 6.x in most recent releases, which is fine (our find_package(Libxc 7.0 ...) requires 7.0+). If your distribution ships an older libxc, build from source:

git clone --branch 7.0.0 https://gitlab.com/libxc/libxc.git
cd libxc && mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/.local -DBUILD_TESTING=OFF
make -j && make install
export CMAKE_PREFIX_PATH=$HOME/.local:$CMAKE_PREFIX_PATH

Then build vibe-qc:

git clone <repo-url> vibeqc
cd vibeqc
./scripts/build_libint.sh
./scripts/setup_basis_library.sh
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'

Linux — Fedora / RHEL-family¶

sudo dnf install \
    gcc gcc-c++ cmake ninja-build git \
    eigen3-devel boost-devel gmp-devel gmp-c++-devel \
    libxc-devel fftw-devel \
    python3 python3-devel
./scripts/build_libint.sh
./scripts/setup_basis_library.sh
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'

Linux — Conda / Mamba (any distro)¶

If you don’t have root, grab everything from conda-forge:

mamba create -n vibeqc -c conda-forge \
    python=3.12 compilers cmake ninja git \
    eigen libboost-headers gmp libxc fftw \
    numpy pybind11 scikit-build-core pytest pyscf ase
mamba activate vibeqc
./scripts/build_libint.sh
./scripts/setup_basis_library.sh
pip install -e '.[test]' --no-deps

The --no-deps flag avoids pulling pip wheels of things conda already provides.

What each step does¶

Step	Purpose
`brew install` / `apt install` / etc.	System libraries: Eigen, Boost, GMP, libxc, OpenMP.
`./scripts/build_libint.sh`	Clones libint 2.13.1, runs its code generator with `max_am=5` and 1st-order derivatives enabled, compiles, installs into `third_party/libint/install/`. Idempotent — re-running after a successful install is a no-op.
`./scripts/setup_basis_library.sh`	Copies libint’s 90 standard `.g94` basis files plus anything you’ve put in `basis_library/custom/` into `basis_library/basis/`. Re-run after adding a custom basis.
`python3 -m venv .venv`	Isolates vibe-qc from your system Python.
`pip install -e '.[test]'`	Drives CMake via scikit-build-core, compiles the pybind11 module, installs the Python package in editable mode plus test dependencies (pyscf, ase).

Verifying¶

.venv/bin/python -c "import vibeqc; print(vibeqc.hello(), vibeqc.libint_version())"

Should print:

vibeqc core alive 2.13.1

Then run the regression suite:

.venv/bin/python -m pytest tests/

131 tests should pass in about 10 seconds on a recent machine.

Common issues¶

“Could not find Libxc” (or Libint2) CMake can’t find one of the system packages. Check find_package(...) directives in cpp/CMakeLists.txt and the root CMakeLists.txt. If you installed via conda, make sure the conda env is activated when you run pip install. If you installed libxc to a custom prefix, add that prefix to CMAKE_PREFIX_PATH.

“error: externally-managed-environment” on macOS You’re trying to pip install against Homebrew’s system Python. PEP 668 blocks this; always use a virtualenv:

python3 -m venv .venv && .venv/bin/pip install -e '.[test]'

libint build is slow The libint code generator produces a large amount of source for max_am=5 plus first derivatives (several thousand files). The compile phase uses Ninja which parallelizes; expect 10-30 min on a modern 8-core machine, longer on Mac minis / small VMs. Set CMAKE_BUILD_PARALLEL_LEVEL to restrict parallelism if you’re running out of RAM.

Old Eigen complains about Eigen 3.4 vs 5.x Harmless — vibe-qc’s CMake is set to accept any Eigen ≥ 3. If the package manager ships Eigen 3.3 or older, install a newer one manually.

Python 3.14 + some dependency refuses to build Most scientific packages have wheels for 3.11-3.13; 3.14 is bleeding edge and occasionally missing binary wheels. Stick to 3.12 or 3.13 if you hit this.

rm -rf + rebuild If everything goes sideways:

rm -rf third_party/libint .venv build basis_library/basis
./scripts/build_libint.sh
./scripts/setup_basis_library.sh
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'

Updating¶

git pull
./scripts/setup_basis_library.sh   # in case custom bases changed
.venv/bin/pip install -e '.[test]' --force-reinstall --no-deps

libint itself rarely needs rebuilding — only if you change scripts/build_libint.sh (e.g. to raise max_am or enable second derivatives).