Last Updated: Sept. 2, 2025
CoQuí (Correlated Quantum ínterface) is a software project designed for ab initio electronic structure beyond density functional theory (DFT). It provides scalable implementations of correlated methods based on the tensor hypercontraction (THC) representation of Coulomb integrals for both molecular and solid-state systems.
CoQuí can be used in two interfaces:
- Python interface
Build with-DCOQUI_PYTHON_SUPPORT=ON, then import CoQUí as a module to prepare inputs, launch runs, and post-process results. - Input-file interface
Provide an input toml file and run CoQuí from the command line.
CoQui utilizes distributed linear algebra to enable high-performance ab-initio calculations applicable to:
- Both k-point (periodic) and molecular systems
- Generic single-particle basis sets, such as Kohn-Sham (KS) orbitals, Gaussian-type orbitals, and their mixtures.
Currently, CoQuí interfaces with the following backends (see examples/dft_converter for input preparation):
Below are some key features of CoQuí. For more detailed examples, please visit our examples page.
- THC representation for two-electron Coulomb integrals [ref1, ref2].
- Cholesky decomposition for two-electron Coulomb integrals.
- Hartree-Fock [ref]
- RPA correlation energy [ref]
- GW approximation [ref]
- Second-order exchange (SOX) diagram with bare interactions [ref]
- Second-order screened exchange (SOSEX, 2SOSEX) diagram with statically and dynamically screened interactions [ref]
- Vertex-corrected GW self-energy (G3W2) diagram with statically screened interactions [ref]
- Self-consistency with quasiparticle approximation
- Self-consistency with full frequency dependence
- Maximally localized Wannier functions via Wannier90 interface
- Constrained RPA to calculate screened interactions [ref]
- Local effective low-energy Hamiltonian for further correlated calculations [ref]
- C++ compiler that supports at least C++20.
- CMake >= 3.2.0.
- MPI Library: openmpi >= 4.
- HDF5 >= 1.8.2 for checkpoint file I/O.
- BLAS Library: OpenBLAS or Intel MKL.
- LAPACK Library: OpenBLAS or Intel MKL.
- SLATE Library for distributed linear algebra.
- Boost >= 1.68.0
- FFTW >= 3.2
CoQuí uses CMake to configure the build process. Follow
the instructions below step-by-step, and replace the placeholders in
square brackets ([]) with your local settings.
# Step 1: Clone the git repository of CoQui
git clone https://github.com/AbInitioQHub/coqui.git coqui.src
# Step 2: Create working directory for CMake to build in
mkdir -p coqui.build && cd coqui.build
# Step 3: Configure with CMake
# Replace `[YOUR_INSTALL_PREFIX]` with the directory where you want CoQui installed.
# Replace `[NCORES]` with the number of cores you want to use for the test processes.
# Replace `[SLATE_INSTALL_PATH]` with your SLATE installation path.
# Add `COQUI_PYTHON_SUPPORT=ON
export slate_ROOT=[SLATE_INSTALL_PATH]
cmake \
-DCMAKE_INSTALL_PREFIX=[YOUR_INSTALL_PREFIX] \
-DCTEST_NPROC=[NCORES] \
-DCOQUI_PYTHON_SUPPORT=ON \ # Optional: enable Python bindings
../coqui.src
# Step 4: Build, test and install
# Replace `[NCORES_MAKE] with the number of cores you want to use for the build processes.
# The ctests will be executed in parallel using `[NCORES]` processors.
make -j[NCORES_MAKE] && ctest && make install
# Verify: the 'coqui' executable should be in [YOUR_INSTALL_PREFIX]/bin
ls -l [YOUR_INSTALL_PREFIX]/bin/coqui
# Step 5: Set CoQui environment
# You would need to source this in every new shell, or add
# this line to your ~/.bashrc or ~/.zshrc to make it persistent.
source [YOUR_INSTALL_PREFIX]/share/coqui/coqui_env.sh- Quick start: See the step-by-step notebooks in the coqui tutorial.
- Reference inputs: Browse runnable cases in examples.
If you use CoQui in your research, please cite the relevant papers listed in REFERENCES.md.