Skip to content

Carcará

v26.7.41

Fermionic quantum simulation, one API across three quantum backends.

A lightweight, high-performance Python framework for variational quantum algorithms — Hartree–Fock, VQE, ADAPT-VQE, VASQE and excited-state solvers — running unchanged on IBM Qiskit, Amazon Braket and Google Cirq, on noise-free simulators and on real NISQ-era quantum hardware.

From a molecular or periodic geometry, Carcará builds real-space grids, evaluates one- and two-body integrals on a C/OpenMP-accelerated engine, maps the fermionic Hamiltonian to qubits, and solves it variationally — all through a single ASE calculator, QuantumCalculator.

Install Source (opens in a new tab)
  • Python 3.11+
  • Backends Qiskit · Braket · Cirq
  • Core C + OpenMP
  • Tests 609 passing
  • License MIT
quantum backends
3 quantum backends Qiskit, Amazon Braket and Cirq behind one unchanged API
elements with native pseudopotentials
<90 elements with native pseudopotentials Troullier–Martins, generated by Carcará's own atomic LDA solver
tests passing
609 tests passing integrals, mappings, drivers, backend-provider equivalence
licensed
MIT licensed source on GitHub, releases on PyPI

The cross-backend spread and the measurement-circuit count come from the project's own LiH validation run. See Hardware for the full table, and for what still doesn't work.

What Carcará does

Basis to Hamiltonian

Every basis generated, nothing tabulated

Localized orbitals — FAO, NAO, GTO/STO-nG and Pople split-valence — and norm-conserving Troullier–Martins pseudopotentials are built from scratch by an atomic LDA solver, not looked up in a basis-set library.

  • A C/OpenMP integral engine that never sees an orbital's analytic form — only its sampled grid values
  • The two-electron Coulomb integral solved via FFT, O(N log N)
  • Norm-conserving pseudopotentials with Kleinman–Bylander projectors for every element with Z < 90

One driver, many solvers

Ground state, excited states, and stochastic search

VQE and ADAPT-VQE — four operator pools — share a single VariationalDriver base; excited states plug in as composable mixins, deflation (VQD) and subspace search (SSVQE), with no duplicated setup code.

  • VASQE: a stochastic adaptive eigensolver with softmax operator sampling and temperature annealing
  • BlochCalculator for periodic systems — band structure and Born–von Kármán total energies
  • Exact circuits: no Trotter error — the same state vector to machine precision on all three SDKs
Basis Sets Algorithms Hardware

One calculator, every solver

QuantumCalculator is the only class a script needs to import. The method= argument picks the algorithm; the basis, mapping and backend arguments compose freely with it.

  1. 01

    Describe the system

    An ASE Atoms object or an XYZ file — molecular or periodic, the same entry point either way.

  2. 02

    Pick a method

    QuantumCalculator(method="adapt_vqe", basis="FAO", mapping="jordan_wigner") selects the solver; everything else has a sensible default.

  3. 03

    Run it — anywhere

    The same script runs on a NumPy state vector, on Qiskit, Braket or Cirq, or on a real QPU — swap one keyword argument.

One driver, every SDK and basis

The same QuantumCalculator call reaches three quantum-computing SDKs and every basis and mapping Carcará ships — no separate integration code per backend.

IBM

  • Qiskit
  • Qiskit Nature
  • Qiskit IBM Runtime

Amazon Braket

  • Local simulator
  • SV1
  • DM1
  • TN1
  • IonQ
  • IQM
  • Rigetti

Google

  • Cirq

Localized bases

  • FAO
  • NAO
  • GTO / STO-nG
  • Pople 6-31G(d)

Fermion → qubit mappings

  • Jordan–Wigner
  • Parity
  • Bravyi–Kitaev

ADAPT-VQE operator pools

  • Fermionic
  • Qubit
  • QEB
  • CEO

Build a Hamiltonian, solve it three ways

pip install carcara, or build the C backend from source. Three commands from a fresh environment to a first ground-state energy.

Get Carcará Read the docs