Variational Quantum Simulation of Antiferromagnetic Hamiltonians
Part of ARPA Quantum Logical Systems — QONDRA · qondra@arpacorp.net
spinq-vqe simulates the quantum many-body physics of Mn₃Sn — a Kagome antiferromagnet that demonstrated 40-picosecond spin-orbit torque switching (UTokyo, 2026). We use Variational Quantum Eigensolvers (VQE) to approximate its ground state and compare directly to spectroscopic data.
Two parallel research threads:
- VQE on the Kagome lattice: ground-state energy, entanglement structure, barren plateau diagnostics, exact diagonalization benchmarks.
- SOC material screening via QAOA: classical MLP surrogate on spin Hall angle data, used as oracle for a QAOA composition optimizer.
Important
NB04 scientific scope. The committed data/mp_theta_sh.csv combines
Materials Project descriptors with a fixed, illustrative θ_SH oracle (32
Phase-A materials). Surrogate diagnostics report train / CV / hold-out metrics;
QAOA / greedy / SA still select k=3 from a fixed N=12 pool with
oracle=in_sample (pool LOOCV RMSE reported alongside). A screening
split (#23) trains on the hold-out complement and is reported separately;
it does not replace the published table. Targets reproduce this
workflow — they are not row-wise verified measurements. See
data/theta_sh_sources.md and
data/theta_sh_provenance.csv.
spinq-vqe/
├── src/spinq_vqe/
│ ├── kagome.py # Kagome lattice graph + Heisenberg Hamiltonian
│ ├── ansatz.py # HVA, HEA, MERA variational ansatze
│ ├── vqe.py # COBYLA (primary) + Adam (diagnostic) VQE runners
│ ├── entanglement.py # Von Neumann entropy, mutual information
│ ├── utils.py # Publication-quality plot helpers
│ ├── surrogate.py # MLP surrogate for spin Hall angle prediction
│ ├── qaoa.py # QAOA circuit + optimizer for material selection
│ ├── dmrg.py # TeNPy DMRG reference energies (NB06)
│ └── nqs.py # NetKet Neural Quantum State baselines (NB07)
├── notebooks/ # Executable research notebooks
├── figures/ # Generated plots
├── data/ # ED/VQE/QAOA/DMRG/NQS CSVs, mp_theta_sh.csv, surrogate_metrics.csv
├── scripts/ # Benchmarks, fetch_mp_theta_sh.py, evaluate_surrogate.py, run_qaoa_sweep.py, evaluate_qaoa_screening.py
├── docs/ # Guides and API reference → docs/README.md
├── OVERVIEW.md # Full program description + research context
└── REFERENCES.md # Full bibliography (50+ references)
python -m venv .venv
.venv\Scripts\activate # Windows
source .venv/bin/activate # Linux / macOS
pip install -e ".[dev]"Conda users:
conda env create -f environment.yml
conda activate spinq-vqeRequires Python ≥ 3.11. Core: pennylane ≥ 0.39, numpy, scipy, networkx, matplotlib.
The [dev] extra (install command above) adds pytest, ruff, Jupyter, and scikit-learn (surrogate MLP tests).
Optional: pip install -e ".[data]" adds mp-api, pandas, matminer (Materials Project refresh).
Optional: pip install -e ".[dmrg]" adds physics-tenpy (for DMRG comparison, NB06).
Optional: pip install -e ".[nqs]" adds netket (for Neural Quantum State comparison, NB07).
SOC QAOA data (NB04): uses committed data/mp_theta_sh.csv (no API key needed).
Surrogate train/CV/hold-out metrics: data/surrogate_metrics.csv (regenerate with
python scripts/evaluate_surrogate.py). To refresh Materials Project descriptors:
cp .env.example .env # add MP_API_KEY from materialsproject.org/api
pip install -e ".[data]"
python scripts/fetch_mp_theta_sh.py| # | Notebook | Notes |
|---|---|---|
| 01 | 01_kagome_hamiltonian.ipynb |
lattice, ED baseline, figures |
| 02 | 02_vqe_run.ipynb |
COBYLA seed stats (mean ± std), 9.66% best error, Adam barren plateau |
| 03 | 03_entanglement.ipynb |
entropy profile, MI matrix, sublattice correlations |
| 04 | 04_soc_qaoa.ipynb |
surrogate train/CV/hold-out, QAOA p=1/2/3, λ/budget sweep, screening split, ranking, landscape |
| 05 | 05_scaling_analysis.ipynb |
N=9/12/18 scaling, gradient variance, barren plateau |
| 06 | 06_dmrg_comparison.ipynb |
TeNPy DMRG vs ED/VQE, χ convergence, entanglement profile |
| 07 | 07_nqs_comparison.ipynb |
NetKet NQS (complex RBM / RBMModPhase) vs ED/DMRG/VQE |
DMRG (TeNPy) is the primary classical reference for system sizes beyond sparse ED. VQE errors are quoted relative to DMRG E₀.
| N | Seeds | Mean E₀ | Std E₀ | Best E₀ | Error vs DMRG | Notes |
|---|---|---|---|---|---|---|
| 9 | 5 | −1.23572 | 0.02852 | −1.28456 | 9.66% | HEA d=3, 27 params |
| 12 | 3 | −1.21520 | 0.02026 | −1.23859 | 16.33% | HEA d=2, 24 params |
| 9 | — | — | — | −1.42190399 | — | DMRG = ED, gap Δ ≈ 0 |
| 12 | — | — | — | −1.48041803 | — | DMRG reference |
| 18 | — | — | — | −1.49962859 | — | DMRG = ED, gap Δ = 0.037 |
| 24 | — | — | — | −1.50936790 | — | DMRG only (beyond ED) |
Same normalized strip Hamiltonian as ED/DMRG/VQE. Complex RBM recovers the ground state; VQE remains ansatz-limited. Full figure set lives in docs/notebooks.md and NB07.
| N | NQS RBM E₀ | err vs ED | NQS ModPhase err | VQE best err |
|---|---|---|---|---|
| 9 | −1.42183147 | 0.005% | 0.006% | 9.66% |
| 12 | −1.48015452 | 0.018% | 1.99% | 16.33% |
Adam / HEA d=3 at N=9 stalls at +0.141 (barren plateau). COBYLA mean ± std and per-seed
distributions are in data/vqe_results.csv, data/vqe_seeds_n9.csv, and
figures/vqe_seed_distribution.png (regenerate via NB02).
Why COBYLA, not Adam: The |0⟩⊗N initial state is a Z-basis eigenstate — all IsingXX/YY/ZZ gradients cancel to exactly zero by SU(2) symmetry. COBYLA uses function evaluations directly and is immune to this.
 |
 |
 |
 |
| Metric | Value | Interpretation |
|---|---|---|
| Mean single-site entropy | 0.9066 bits | Near-maximal → strong quantum fluctuations |
| Max single-site entropy | 1.000 bits | 7 of 9 sites maximally entangled |
| Sublattice I(A:B) | 3.689 bits | Strong inter-sublattice correlations |
| Sublattice I(A:C), I(B:C) | 2.235 bits | C sublattice also correlated |
| Mean pairwise MI | 0.227 bits | Non-local correlations (spin liquid signature) |
Published NB04 totals (λ=6, 300 evals) on the frozen N=12 in-sample pool:
| Method | Total θ_SH | Selected | Notes |
|---|---|---|---|
| QAOA p=1 | 3.049 | W, Ta, Bi₂Se₃ | Best QAOA depth — still sub-optimal |
| QAOA p=2 | 3.049 | W, Ta, Bi₂Se₃ | Same selection as p=1 |
| QAOA p=3 | −0.451 | W, Ta, Pd | Deeper circuit — worse on this oracle |
| Greedy (classical) | 4.259 | Bi₂Se₃, CrTe₂, Mn₃Sn | Optimal on surrogate oracle |
| Sim. annealing | 4.259 | Mn₃Sn, CrTe₂, Bi₂Se₃ | Matches greedy |
p=1 (γ, β) landscape and θ_SH vs depth, pinned to the table above:
Hold-out / CV metrics (data/surrogate_metrics.csv; regenerate with
python scripts/evaluate_surrogate.py). Numbered scatter is a
train vs hold-out diagnostic, not a discovery claim:
| Split | n | RMSE | R² | Notes |
|---|---|---|---|---|
| Train (in-sample) | 25 | 0.116 | 0.93 | Fit set after 20% hold-out |
| 5-fold CV | 25 | 0.458 | −0.03 | Leakage-free Pipeline |
| Hold-out | 7 | 1.200 | 0.08 | W, Pd, MnPt, Bi₂Se₃, Ag, Sb₂Te₃, Mn₃Ga |
| QAOA pool in-sample | 12 | 0.006 | — | Oracle used for published totals |
| QAOA pool LOOCV | 12 | 1.71 | — | Honesty check; not the QAOA weights |
A λ / budget / depth sweep on the same frozen oracle
(data/qaoa_sweep.csv; python scripts/run_qaoa_sweep.py) does not
replace the table. Best QAOA in the grid is 3.570 (p=1, λ=5;
W / CrTe₂ / Bi₂Se₃), still 0.69 below greedy 4.259. Extra COBYLA
budget at λ=6 does not close the gap; a p=4 probe reaches 3.40. Points are
θ_SH of the best-cost seed (same rule as the table).
A screening evaluation (#23) trains on the #20 25-row complement and
optimizes over the same N=12 pool (data/qaoa_screening.csv;
python scripts/evaluate_qaoa_screening.py). Four pool members
(W, Pd, MnPt, Bi₂Se₃) were never in the fit. The published in-sample
table above is unchanged.
| Method | Pred θ_SH | Label θ_SH | Selected | Unseen in sel |
|---|---|---|---|---|
| QAOA p=1 | 0.981 | 1.000 | Mn₃Sn, Fe₃Sn, CrTe₂ | 0 |
| QAOA p=2 | 2.154 | 0.900 | Mn₃Sn, CrTe₂, MnPt | 1 |
| QAOA p=3 | 2.505 | 3.320 | W, MnPt, Bi₂Se₃ | 3 |
| Greedy (pred) | 2.900 | 4.050 | MnPt, Bi₂Se₃, CrTe₂ | 2 |
| Sim. annealing | 2.900 | 4.050 | CrTe₂, MnPt, Bi₂Se₃ | 2 |
| Greedy (labels) | 1.782 | 4.250 | Bi₂Se₃, CrTe₂, Mn₃Sn | 1 |
On the screening oracle, greedy/SA still win (2.900 vs QAOA 2.505 at p=3). Post-hoc labels of that greedy triple are 4.050; the label-optimal triple is still Bi₂Se₃ / CrTe₂ / Mn₃Sn at 4.250 (raw CSV labels, not the in-sample 4.259).
pip install -e ".[dev]"
pytest tests/ -vCore suite covers kagome/ansatz/VQE/entanglement/surrogate/QAOA (under ~90 s on CPU). Optional [dmrg] / [nqs] modules skip when those extras are not installed. See docs/testing.md.
→ OVERVIEW.md — research narrative, key results, and literature context.
→ docs/README.md — physics background, ansatz guide, API reference, notebook guide.
→ docs/testing.md — test suite guide, coverage map, extending tests.
See REFERENCES.md for the full bibliography.
Key: Sachdev (1992), Yan/Huse/White (2011), Carleo/Troyer (2017), Wiersema et al. (2020), Kandala et al. (2017), Cerezo et al. (2021), Farhi et al. (2014).
If you use this software, please cite CITATION.cff:
Peilivanidis, V., & ARPA Quantum Logical Systems (QONDRA). (2026). spinq-vqe: Variational Quantum Simulation of Antiferromagnetic Hamiltonians (v0.1.6). https://doi.org/10.5281/zenodo.21628505
Use the concept DOI above for the code artifact (always resolves to the latest archived version). Cite any related paper DOI separately once the manuscript is published.
License: MIT · Contact: qondra@arpacorp.net