Skip to content

Install

Get Carcará 26.7.41

MIT licensed. pip install carcara gets a released version; from source is what you want if you intend to change anything or compile the C integral backend yourself.

Requirements

  • Python 3.11 or newer
  • A C compiler with OpenMP support (GCC or Clang)
  • CMake 3.15 or newer, to compile the integral backend
  • pip

Install, then build the C backend

Pick pip or an editable checkout — not both. The C backend step is optional either way: everything still runs on the NumPy fallback without it, just without OpenMP parallelism.

  1. Install from PyPI

    $ pip install carcara

  2. Or install from source, editable

    $ git clone https://github.com/seixas-research/carcara.git $ cd carcara $ pip install -e .

  3. Compile the C integral backend (recommended)

    # macOS — requires Homebrew libomp $ cd src/carcara/integrals/csrc $ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DOpenMP_ROOT=$(brew --prefix libomp) $ cmake --build build

There is no separate CLI to learn — everything above is a Python import. A run is a script that builds an ASE Atoms object, attaches a QuantumCalculator, and calls get_total_energy() or get_potential_energy().

Confirm the C backend compiled

HAS_C_BACKEND is False until the CMake step above succeeds — everything still runs, on the pure-NumPy fallback, just without OpenMP parallelism.

$ python -c "from carcara.integrals import HAS_C_BACKEND; print(HAS_C_BACKEND)"

True means libcarcara_integrals loaded; False means every integral routes through the slower NumPy path in _backend.py.

Running the test suite

609 tests cover integrals, basis definitions, operators, the Hartree–Fock solvers, VQE/ADAPT-VQE/VASQE, the Hamiltonian cache, backend-provider equivalence and the Braket shot-based measurement path.

# from the project root $ pytest

Compiling the C backend first (previous step) is optional for this — the suite falls back to the NumPy integral path automatically when it isn't built.

Stuck on something?

The installation guide on Read the Docs covers the same ground in more detail, including platform-specific notes for the CMake step.

Documentation