Skip to content

Algorithms

Four solvers, one driver underneath

Ground state, excited states, exact eigenvalues, periodic systems — every solver inherits from one driver and reaches you through one ASE calculator, Mandacaru(method=...).

How ADAPT-VQE builds its ansatz

The ansatz is built during the calculation instead of fixed in advance, so the circuit is tailored to the molecule. VQE optimizes a fixed UCCSD ansatz instead — same call, different method=.

Mandacaru(method="adapt-vqe", pool="qeb", gradient_tolerance=1e-3)

The ADAPT-VQE loop: screen the operator pool, append the operator with the largest gradient, re-optimize every parameter, and stop when the largest gradient falls below the tolerance. no Screen the pool ⟨ψ|[H, Aₖ]|ψ⟩ for every generator Grow the ansatz append exp(θₖAₖ) for the largest Re-optimize θ every parameter, warm-started Largest gradient below tolerance? no — screen again yes — converged

The solvers

Ground state

ADAPT-VQE draws from a pool — fermionic, qubit, qubit-excitation (QEB) or coupled-exchange (CEO) — and adds only the generator that lowers the energy most. Every pool is built in whichever encoding you ask for.

Mandacaru(method="adapt-vqe", pool="fermionic") · method="vqe" for a fixed UCCSD ansatz

Four panels for ADAPT-VQE on LiH. Expressibility falls as operators are added; the energy error falls below chemical accuracy and then to 1e-10 eV; the fidelity distribution of the grown ansatz approaches the Haar distribution.
Expressibility — KL divergence from the Haar distribution of the number-conserving sector — and the energy error fall together as the ansatz grows on LiH.

Excited states

Variational deflation optimizes each new state orthogonal to the ones already found. Subspace search sends several orthogonal references through one shared unitary and minimizes a weighted sum, getting the whole spectrum in one optimization.

atoms.calc.energy_levels(num_states=3) · Mandacaru(method="subspace-adapt-vqe", num_states=3)

Exact eigenvalues — quantum phase estimation

A converged variational state can be handed to QPE rather than re-optimized: it reads a wavefunction checkpoint, evolves it under exp(2πi(H−Elo)/W) and inverse-QFTs the evaluation register. The 2ⁿ⁺ᵗ state vector is costed against free memory before a byte is allocated.

from mandacaru.algorithms import QuantumPhaseEstimation · QuantumPhaseEstimation(n_evaluation_qubits=10).run("state.json")

Two histograms of the phase-estimation outcome probability against energy for H2. Both show a single sharp peak on the exact ground-state energy; the right-hand panel uses a much narrower energy window and finer bins.
Phase estimation reading the eigenvalue off a checkpointed H₂ state with 10 evaluation qubits; a narrower energy window gives a narrower bin.

Periodic systems

BlochCalculator takes a primitive cell and solves the single-particle Bloch problem for a band structure, or the Born–von Kármán supercell for a total energy per cell over the whole k-mesh.

BlochCalculator(atoms, method="adapt-vqe").band_structure("GXG") · .total_energy(kmesh=(4, 1, 1))

The 1s Bloch band of a periodic hydrogen chain across the Brillouin zone, a smooth cosine-like curve with its minimum at gamma, with Monkhorst-Pack k-points marked and the Fermi level drawn as a dashed line.
The 1s Bloch band of a periodic hydrogen chain. examples/07_ADAPTVQE_H_chain_bands.py

Around the solvers

Open shells

An odd electron count — any radical or ion — is built in the natural-orbital basis of the unrestricted solution, one spatial basis shared by both spins, so the solvers, pools and mappings run unchanged. The spin state comes from the geometry's magnetic moments.

Sparse pools and particle-number sectors

From ten qubits up the pool stays sparse and only selected operators are densified. From sixteen, the Hamiltonian and the pool are restricted to the (n~α~, n~β~) sector — LiH in PAW-DZP is 20 qubits but 100 states.

Forces from the run's own density matrices

atoms.get_forces() differentiates the energy the solver actually computed, contracting its density matrices against displaced integrals on the same frozen grid. The neglected orbital-response term is measured rather than assumed.

Checkpoints and resuming

checkpoint="state.json" writes the reference, the generators, the angles and the Hamiltonian as the run proceeds; resume= continues where it stopped. The same file is what QPE reads, and what warm-starts the next geometry of a relaxation.

Dry run and the command line

mandacaru geometry.xyz --dry-run reports the register a calculation needs — after the frozen core or the plane-wave cutoff — and whether it fits the target device, without computing an integral.

Quenching

By default every parameter is re-optimized each ADAPT iteration. quenching=False freezes the earlier ones and optimizes only the newest: a one-dimensional line search per step, far cheaper and variationally weaker.

How it is put together

algorithms/
The driver base, the solvers, excited-state mixins, RDM forces, QPE, the dry run and the Mandacaru entry point
core/
Fermionic operators, the PauliSum type, the four qubit mappings, the particle-number sector, checkpoints
basis/
FAO, NAO, NAO-AE and Gaussian basis functions, the named-set recipe engine, the atomic LDA solver
pseudopotentials/
NCPP, ONCVPSP, PAW and UPAW generation, and the family registry that turns a name into a basis
integrals/
The real-space grid, the FFT Poisson solver, the C/OpenMP backend and its NumPy fallback
circuits/
The Ansatz protocol, UCCSD and the growable ADAPT ansatz, operator pools, circuit profiling
backends/
Qiskit, Braket and Cirq execution, the device registries, shot-based measurement

Keep reading

Basis Sets

Twelve families of orbitals generated at run time, the frozen core, and the integral engine underneath.

Providers

Qiskit, Braket and Cirq, the registered devices, and what a real QPU actually returned.