Installation Guide

This guide details how to set up Carcará for development or direct simulation use.

Prerequisites

To run and build Carcará, you need:

Python: Version 3.11 or higher.
C++ Compiler: Supporting OpenMP (e.g., gcc on Linux/macOS or Apple Clang with libomp on macOS).
CMake: Version 3.15 or higher (required to compile the accelerated C integral backend).

Installation Methods

Method A: Install via pip (Stable Release)

You can install the stable version of Carcará directly from PyPI:

pip install carcara

This installs all core Python dependencies:

Numerical core

numpy (>= 2.0.0)
scipy
matplotlib — plotting helpers (expressibility, band structures)
ase (Atomic Simulation Environment) — geometries and the calculator interface

Hamiltonian cache

fastparquet — the default Apache Parquet engine
pandas — its table interface

Quantum SDKs (backend providers and the device registry)

qiskit — default circuit provider and gate-count profiling
qiskit-nature
qiskit-ibm-runtime — the reserved ibm-quantum device
amazon-braket-sdk — local simulator plus the AWS Braket devices and QPUs
cirq

Testing

pytest

Method B: Install from Source (Developer Setup)

To make changes to the source code, run the examples, or work on the C backend, clone the repository and install it in editable mode:

# Clone the repository
git clone https://github.com/seixas-research/carcara.git
cd carcara

# Install in editable mode
pip install -e .

Compiling the C Backend (Recommended)

Carcará features an OpenMP-parallelized C backend (libcarcara_integrals) for real-space integrals. If the compiled library is missing, the framework automatically falls back to a vectorized NumPy implementation, which is correct but substantially slower.

To compile the C shared library:

On Linux

cd src/carcara/integrals/csrc
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

On macOS (Apple Silicon or Intel)

macOS’s default Apple Clang does not ship with OpenMP. You must install libomp via Homebrew:

# Install OpenMP library
brew install libomp

# Configure with brew prefix path
cd src/carcara/integrals/csrc
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DOpenMP_ROOT=$(brew --prefix libomp)
cmake --build build

The compiled dynamic library (.so or .dylib) will be built under src/carcara/integrals/csrc/build/. Carcará’s loading system detects it automatically. You can verify that it is loaded in Python:

from carcara.integrals import HAS_C_BACKEND
print(f"C backend active: {HAS_C_BACKEND}")

Optional Dependency Groups

Extra	Installs	Purpose
`pyarrow`	`pyarrow`	An alternative Apache Parquet engine for the Hamiltonian cache.
`docs`	`sphinx`, `sphinx-rtd-theme`, `myst-parser`, `furo`	Building this documentation.
`dev`	everything above	Full development environment.

pip install "carcara[dev]"

A note on the `pyarrow` extra

The Hamiltonian cache reads and writes Parquet through either fastparquet (the default, installed with the package) or pyarrow. Both produce standard Parquet files, so they are interchangeable.

Warning

fastparquet is the default on purpose. On some platforms — reproduced on CPython 3.14 with qiskit 2.5 and pyarrow 25 — calling pyarrow.parquet.write_table in a process that has also run Qiskit’s transpile crashes the interpreter, since both ship their own native runtimes. Carcará transpiles circuits for gate-count profiling in the same process that saves the Hamiltonian, so the default engine avoids that combination.

If your environment is unaffected, pass engine="pyarrow" explicitly. If you would rather not depend on a Parquet engine at all, use hamiltonian_format="json", which needs only the standard library.

AWS Braket Credentials (Optional)

Running on the Amazon Braket service — the managed simulators or a real QPU — needs AWS credentials configured on your machine:

aws configure

Local Braket simulation (device="braket-local") needs no credentials and costs nothing. See Running on Amazon Braket (and real QPUs) for the details, including how to estimate the cost of a hardware run before submitting it.