Mandacaru is a Python framework for simulating fermionic systems with variational quantum algorithms. Starting from an atomic geometry, it builds a molecular Hamiltonian, maps it to qubits and optimises a quantum circuit to estimate its energy. The Atomic Simulation Environment (ASE) provides the geometry and calculator interface.

Start with lithium hydride (LiH)

The introductory tutorials follow one molecule from a single energy calculation to a potential-energy curve:

1. Install Mandacaru and check your Python environment.

2. Run VQE for LiH and understand the basis, electron count, integration grid and energy units.

3. Build an adaptive circuit and compare operator pools on the same molecular problem.

4. Scan the Li–H distance and compare basis sets and operator pools in a reproducible PNG figure.

How a calculation works

1. Atomic geometryASE Atoms: elements and positions in ångströms
2. Basis and integration gridSpatial orbitals sampled on a real-space grid
3. Molecular HamiltonianIntegrals, Hartree–Fock orbitals and optional frozen core
4. Qubit HamiltonianJordan–Wigner, parity, reduced parity or Bravyi–Kitaev mapping; optional cache
5. Variational calculationVQE or ADAPT-VQE; circuit evaluation and classical optimisation
6. ResultsEnergy, convergence information and circuit parameters

A cached Hamiltonian lets you restart at the variational stage when comparing solvers. Rebuild it whenever the geometry, basis, integration grid or electronic problem changes. See Caching the Hamiltonian (Parquet / JSON).

Choose the right controls

Control	What it changes	Learn more
Basis set	The spatial functions used to represent the electrons	Basis sets: multiple zeta, polarisation, and the named Gaussian families
Integration grid	The numerical accuracy of the molecular integrals	LiH potential-energy curves: basis sets and operator pools
Frozen core	Which occupied orbitals remain fixed during the correlated calculation	Your first LiH calculation: VQE
Operator pool	The circuit generators available to ADAPT-VQE	Adaptive ansatz construction: ADAPT-VQE
Backend	How circuits are constructed and evaluated	Backend Providers: Qiskit, Braket and Cirq

Changing a basis changes the approximate Hamiltonian. Changing a pool changes the variational search within that Hamiltonian. These are separate sources of error, so the LiH tutorial compares them separately.

Units and interpretation

The introductory examples use ångströms (Å) for distances and electronvolts (eV) for reported energies. The integral, mapping and Hamiltonian-cache layers use atomic units internally. A result’s in_units("Ha") method gives a Hartree view; atomic_units=True changes the driver output convention. Keep the default convention when following the ASE examples.

The molecular total energy includes nuclear repulsion. It is different from a binding energy, which requires a separately defined fragment reference. Converging a variational optimiser does not establish convergence with respect to the basis or integration grid.

Mandacaru generates its Gaussian basis functions internally. Named families reproduce the intended shell structure, but do not use the published exponent tables. Consult Basis sets: multiple zeta, polarisation, and the named Gaussian families before comparing with literature values.

Explore further

The How-To Guides covers open shells, pseudopotentials, Hamiltonian caches and execution backends. The Variational Quantum Algorithms Theory explains the equations behind the tutorials, and the API Reference documents the Python interfaces.

Source code and issue reports are hosted on GitHub. Releases are available from PyPI. Mandacaru is distributed under the MIT licence.