A hardware-efficient ansatz (HEA) builder that constructs a Clifford frame
mapping the dominant terms of a qubit operator onto single qubits, then
interleaves Clifford layers with single-qubit RY rotations to build a compact
variational ansatz. Given a qubit Hamiltonian or cost operator, build_hea_circuit
automatically searches for this Clifford frame, runs short VQE passes to grow
it layer by layer, and returns a ready-to-optimise variational circuit — no
hand-designed ansatz required. This repository accompanies the Q-Cliff
manuscript (Q-Cliff.pdf, https://arxiv.org/abs/2607.18404).
The three notebooks are independent worked examples of the same method applied to different problems — a linear-algebra cost function, a molecular ground-state Hamiltonian, and a benchmark against classical methods.
1. VQLS on a Lorenz system — examples/vqls_lorenz.ipynb
Builds a Variational Quantum Linear Solver (VQLS) cost operator from a
discretised Lorenz chaotic attractor, then uses build_hea_circuit to find a
Clifford-frame ansatz and optimise it with VQE.
2. VQE on LiH — examples/vqe_lih.ipynb
Builds the LiH (STO-3G) electronic Hamiltonian, maps it to qubits, rotates into the Hartree–Fock reference frame, and runs the same Clifford-frame HEA construction and VQE optimisation, comparing the result against the exact FCI energy. Finishes by compiling out redundant SWAP patterns to reduce the final circuit depth.
3. CP simulator on H4 — examples/h4_cp_vs_classical.ipynb
Scans the bond length of linear H4 (cc-pVDZ, CAS(4,4)) and compares the
Clifford-frame ansatz at n_layers=0 — a product state with no entangling
gates — against QMF, MP2, CISD and FCI. Optimisation runs on CPSimulator,
the package's rank-1 tensor-network backend.
Use the Launch on qBraid button on this tutorial's page in the qBraid Explore hub. It clones the repository into qBraid Lab and installs the required environment. Once it's ready, select the pre-configured environment as the notebook kernel and run the notebooks in any order.
Requirements (installed via the first cell of each notebook): Stim, Tangelo, OpenFermion, PySCF (the two chemistry notebooks), NumPy, SciPy, Matplotlib, pandas (H4 notebook only).
Exact energies and optimizer trajectories can shift slightly with the installed PySCF/Stim versions — this is expected; compare results against the manuscript by shape/order of magnitude rather than exact digits.
[1] Q-Cliff manuscript, Q-Cliff.pdf (this repository, https://arxiv.org/abs/2607.18404).
[2] Nature Scientific Reports 2023, doi:10.1038/s41598-023-40893-0 — VQLS reference used in the Lorenz-system notebook.