Skip to content

Mandacaru

v26.9.33

Fermionic quantum simulation made simple

A lightweight, high-performance Python framework for variational quantum algorithms: VQE, ADAPT-VQE and excited-state solvers. The framework is SDK-agnostic (IBM Qiskit, AWS Braket, Google Cirq) and runs on real quantum hardware as well as local simulations.

From a molecular or periodic geometry, Mandacaru 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 — energies in eV, forces in eV/Å, through the ASE calculator interface.

Install Source (opens in a new tab)
  • Python 3.14+
  • Backends Qiskit · Braket · Cirq
  • Core C + OpenMP
  • Tests 1358 passing
  • License MIT
quantum providers
3 quantum providers IBM Qiskit, AWS Braket and Google Cirq
basis families, all generated
10 basis families, all generated FAO, NAO, NAO-AE, STO-nG, Pople, Dunning cc-pVXZ and Karlsruhe def2, plus the NCPP, ONCVPSP and PAW pseudopotential families — built at run time, never tabulated
operator pools
4 operator pools fermionic, qubit, qeb, ceo — every one built in the encoding you ask for
fermion-to-qubit mappings
4 fermion-to-qubit mappings Jordan-Wigner, parity, parity-reduced (two qubits tapered away) and Bravyi-Kitaev

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 Mandacaru does

Basis to Hamiltonian

Every basis generated, nothing tabulated

Localized orbitals — FAO, NAO, all-electron NAO-AE, STO-nG and the named Pople, Dunning (cc-pVXZ) and Karlsruhe (def2) Gaussian families — are built from scratch at run time, by analytic formulas, least-squares fits or an atomic LDA solver, not looked up in a basis-set library. So are the three pseudopotential families, NCPP, ONCVPSP and PAW, selected as a basis name.

  • 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)
  • A frozen-core approximation that removes the chemically inert core orbitals from the qubit count — or a pseudopotential (basis="PAW") that removes the core and the -Z/r cusp altogether

One driver, many solvers

Ground state, excited states, and a qubit budget up front

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

  • A dry run — Mandacaru.dry_run() or mandacaru --dry-run — reports the qubits a system needs, and whether it fits a device, without computing an integral
  • Analytic forces from the run's own density matrices — atoms.get_forces(), on all-electron and pseudopotential bases alike
  • 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

Mandacaru 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

    Mandacaru(method="adapt-vqe", basis="FAO", mapping="jordan_wigner") selects the solver — ADAPT-VQE is the default; everything else has a sensible default too.

  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 Mandacaru call reaches three quantum-computing SDKs and every basis and mapping Mandacaru 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
  • NAO-AE
  • STO-nG
  • Pople 3-21G … 6-311+G(2df,2p)
  • cc-pVXZ / aug-cc-pVXZ / cc-pCVXZ
  • def2-SV(P) … def2-QZVPPD

Pseudopotentials

  • NCPP (Troullier–Martins)
  • ONCVPSP (Hamann)
  • PAW (Blöchl)

Fermion → qubit mappings

  • Jordan–Wigner
  • Parity
  • Parity-reduced
  • Bravyi–Kitaev

ADAPT-VQE operator pools

  • Fermionic
  • Qubit
  • QEB
  • CEO

Build a Hamiltonian, solve it three ways

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

Get Mandacaru Read the docs