Skip to content

Mandacaru

v26.10.11

Everything you need for fermionic quantum simulation

A Python framework for variational quantum algorithms — VQE, ADAPT-VQE and excited states — on IBM Qiskit, Amazon Braket, Google Cirq and real quantum hardware.

Install Source (opens in a new tab)
  • Python 3.14+
  • Backends Qiskit · Braket · Cirq
  • Core C + OpenMP
  • Tests 53 passing
  • License MIT

A first calculation

H₂ from geometry to energy

from ase import Atoms from mandacaru import Mandacaru h2 = Atoms("H2", positions=[[0, 0, 0], [0, 0, 0.74]], cell=[8.0] * 3) h2.calc = Mandacaru(method="adapt-vqe", basis="HAO", pool="fermionic", h=0.20) energy = h2.get_potential_energy() # eV

Geometry in, energy and forces out: real-space integrals on a C/OpenMP engine, a fermionic Hamiltonian mapped to qubits, solved variationally — all through the ASE calculator interface.

Binding-energy curve of H2 from ADAPT-VQE against the hydrogen–hydrogen distance, referenced to two separated hydrogen atoms: a minimum near 0.9 angstrom, returning to zero beyond 2.5 angstrom.
H₂ dissociation, ADAPT-VQE in the FAO basis, referenced to two isolated atoms. examples/22_H2_dissociation.py
quantum SDKs
3 quantum SDKs Qiskit, Braket and Cirq — one keyword apart
basis families
12 basis families seven localized, four pseudopotential, one plane-wave — every one generated at run time
pools × mappings
4 × 4 pools × mappings any operator pool, in any fermion-to-qubit encoding
tests
53 tests integrals, mappings, solvers, forces and both hardware paths

What one call does

Mandacaru is the only class a script imports. Everything below happens inside get_potential_energy().

  1. Geometry

    An ASE Atoms object — molecular or periodic

  2. Basis & grid

    Orbitals generated, then sampled on a real-space box

  3. Integrals

    One- and two-body, C/OpenMP, Coulomb by FFT

  4. Fermionic H

    Second-quantized, frozen core optional

  5. Qubit H

    Jordan-Wigner, parity, parity-reduced or Bravyi-Kitaev

  6. Solve

    ADAPT-VQE or VQE → eV and eV/Å

What Mandacaru does

Basis to Hamiltonian

Every basis generated, nothing tabulated

Orbitals are built at run time — by analytic formula, least-squares fit or an atomic LDA solver — and sampled onto a real-space grid. No basis-set library is shipped or downloaded.

  • An integral engine that never sees an orbital's analytic form, only its sampled values
  • The two-electron Coulomb integral by FFT, O(N log N)
  • A frozen core — or a pseudopotential — to cut the qubit count

One calculator, every solver

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

ADAPT-VQE (the default), VQE and two excited-state methods share one driver and one entry point. Changing the algorithm is changing one string.

  • A dry run sizes the qubit register before a single integral is computed
  • Analytic forces from the run's own density matrices — atoms.get_forces()
  • Periodic systems through BlochCalculator: band structure and total energies
Basis Sets Algorithms Providers

Everything you can pick

Each row is one keyword argument, and they compose freely — there is no separate integration path per backend or per basis.

Quantum SDKs
  • Qiskit
  • Amazon Braket
  • Cirq
Devices
  • AER_simulator
  • IBM Quantum
  • fake_*
  • SV1 / DM1 / TN1
  • IonQ
  • IQM
  • Rigetti
Localized bases
  • FAO
  • NAO
  • NAO-AE
  • STO-nG
  • Pople
  • cc-pVXZ
  • def2
Pseudopotentials
  • NCPP
  • ONCVPSP
  • PAW
  • UPAW
Fermion → qubit
  • Jordan–Wigner
  • Parity
  • Parity-reduced
  • Bravyi–Kitaev
Operator pools
  • fermionic
  • qubit
  • qeb
  • ceo
Optimizers
  • COBYLA
  • SPSA
  • Nelder–Mead
  • SLSQP
  • Adam
  • L-BFGS-B

Build a Hamiltonian, solve it three ways

Get Mandacaru Read the docs