Mandacaru

Mandacaru is a Python framework for fermionic quantum simulation with variational quantum algorithms. From an ASE geometry it builds a real-space Hamiltonian, maps it to qubits, and solves it with VQE or ADAPT-VQE on a state-vector simulator or on quantum hardware (IBM Quantum, Amazon Braket).

Installation

pip install mandacaru

No pseudopotential data ships with the package. NCPP, ONCVPSP, PAW-LCAO and UPAW-LCAO each live in their own repository, and an environment variable names the checkout Mandacaru reads from:

git clone https://github.com/seixas-research/mandacaru-paw.git
mandacaru --set-paw mandacaru-paw     # writes ~/.zshrc or ~/.bashrc, asking before replacing
mandacaru --pseudo-status             # each variable, where it points, and how many datasets it serves

Datasets sit one directory per exchange-correlation functional inside each checkout (<checkout>/lda/<Symbol>.parquet today). The all-electron bases (HAO, NAO, NAO-AE, the Gaussian families) need none of this. See the pseudopotentials guide for the full setup and the installation guide for the numerical backend and the optional dependencies.

LiH with ASE

from ase import Atoms
from mandacaru import Mandacaru

atoms = Atoms("LiH",
              positions=[[0.0, 0.0, 0.0],           # Li
                         [0.0, 0.0, 1.6]],          # H
              cell=[10.0, 10.0, 10.0])

atoms.calc = Mandacaru(method="adapt-vqe",                   # also "rhf", "uhf", "vqe", "hva", subspace methods
                       basis="HAO",                          # Basis set
                       h=0.10,                               # real-space grid spacing (Å)
                       pool="fermionic",                     # "fermionic" | "qubit" | "qeb" | "ceo" | "ceo-ovp"
                       mapping="jordan_wigner",              # "jordan_wigner" | "parity" | "parity_reduced" | "bravyi_kitaev"
                       optimizer={"method": "SLSQP",         # "SLSQP" | "BFGS" | "L-BFGS" | "NLCG-PR" | "COBYLA" | "Nelder-Mead" | "SPSA"
                                  "maxiter": 2000,
                                  "tol": 1e-12},
                       max_iterations=300,                   # at most 300 operators
                       gradient_tolerance=1e-3,              # stop when every pool gradient is smaller
                       device="AER_simulator",               # or an IBM Quantum / Amazon Braket device
                       txt="output.txt")                     # the run log; without it the same blocks are printed

energy = atoms.get_potential_energy()                        # Energy (eV)
print(f"Energy = {energy:.4f} eV")

Potential energy surface

import numpy as np
import pandas as pd
from ase import Atoms
from mandacaru import Mandacaru

distances = np.arange(1.2, 3.101, 0.1)
energies = []
for d in distances:
    atoms = Atoms("LiH",
                  positions=[[0.0, 0.0, 0.0],
                             [0.0, 0.0, d]],
                  cell=[10.0, 10.0, 10.0],
                  magmoms=[1.0, -1.0])

    atoms.calc = Mandacaru(method="adapt-vqe",
                           basis={"name": "PAW-LCAO",
                                  "size": "DZP",
                                  "energy_shift": 0.1},
                           h=0.10,
                           pool="fermionic",
                           mapping="jordan_wigner",
                           optimizer={"method": "SLSQP",
                                      "maxiter": 2000,
                                      "tol": 1e-12},
                           max_iterations=300,
                           gradient_tolerance=1e-4,
                           txt=f"output_{d:.2f}.txt")
    energies.append(atoms.get_potential_energy())

df = pd.DataFrame({"distance": distances, "energy": energies})
df.to_csv("lih_dissociation.csv", index=False)

Theory

Classical mean field. method="rhf" and method="uhf" run restricted or unrestricted Hartree–Fock without building a circuit. Their results export the molecular-orbital Hamiltonian and reference occupation through result.as_quantum_problem(), ready for a direct Mandacaru(method="adapt-vqe", **options) run. See the mean-field and HVA guide.

VQE. The variational quantum eigensolver prepares a parameterized state |ψ(θ)⟩ = U(θ)|Φ_HF⟩ on a quantum processor, measures the energy ⟨ψ(θ)|H|ψ(θ)⟩, and lets a classical optimizer update θ to minimize it. By the variational principle the minimum is an upper bound to the ground-state energy, reached exactly when the ansatz can represent the ground state. Mandacaru starts from the Hartree–Fock determinant in the molecular-orbital basis; the fixed ansatz of method="vqe" is UCCSD.

HVA. method="hva" uses VQE optimization with fixed, ordered Hamiltonian-group layers. It supports exact local evolution and explicit first- or second-order product-formula circuits (evolution="trotter"), checkpoint/resume, Z₂ tapering, spin-resolved grouping, and actual UHF Slater references. See the mean-field and HVA guide for the distinct exact and finite-step states.

ADAPT-VQE. ADAPT-VQE builds the ansatz during the calculation instead of fixing it in advance. At each iteration it evaluates the energy gradient ⟨ψ|[H, A_k]|ψ⟩ of every generator A_k in an operator pool, appends exp(θ_kA_k) for the largest one, and re-optimizes all parameters. It stops when every gradient falls below gradient_tolerance, producing compact circuits tailored to the molecule.

Operator pools. The pool is the set of anti-Hermitian generators ADAPT-VQE chooses from, and it sets the trade-off between circuit depth and the number of iterations. fermionic holds spin-adapted single and double excitations; qubit splits them into individual Pauli strings (the shallowest gates, more iterations); qeb uses qubit excitations — the same occupation moves without the fermionic sign; ceo couples the qubit excitations that act on the same spin-orbitals, and ceo-ovp keeps that coupling to one parameter per step, roughly halving the two-qubit gate count of qeb. Every pool is built in the encoding you ask for (Jordan–Wigner, parity, reduced parity or Bravyi–Kitaev) and reaches the same ground state. The fermionic and qubit-excitation pools conserve the particle number; the individual Pauli strings of qubit do not, by design.

Classical optimization. The parameters are updated by the optimizer in optimizer= — a method name, a dict {"method": ..., "maxiter": ..., "tol": ...}. SLSQP (the default), BFGS, L-BFGS and NLCG-PR use gradients and stop in one to two orders of magnitude fewer steps on exact simulators; Nelder–Mead and COBYLA are gradient-free and more robust on a small, nearly-converged problem; SPSA (two energy evaluations per step, whatever the number of parameters) tolerates the statistical noise of shot-based hardware.

Beyond the ground state

Once a state is prepared — by VQE, ADAPT-VQE or a checkpoint loaded back in — Mandacaru can do more with it than report its energy. time_evolve propagates a Pauli Hamiltonian with a matrix-free Suzuki–Trotter product formula; QuantumEchoes applies a weak dipole kick between forward and backward evolution for a spectroscopy-style response; NestedOTOC evaluates the nested out-of-time-order correlator ⟨[B(t)M]^2k⟩ of repeated echoes with Pauli insertions B and M; and QuantumPhaseEstimation reads the energy of a prepared state off a phase-estimation register. See the quantum echoes and checkpoints and QPE guides.

License

Mandacaru is released under the MIT License.

Developer: Leandro Seixas Rocha (leandro.rocha@ilum.cnpem.br).

Documentation: mandacaru.readthedocs.io.

We thank financial support from INCT Materials Informatics (Grant No. 406447/2022-5).