Quantum Chaos Framework

Exact-diagonalisation and small-circuit tools for quantum chaos and information scrambling in the Sachdev–Ye–Kitaev (SYK) model and the Hubbard chain: symmetry-resolved level statistics checked against random-matrix theory, infinite- and finite-temperature OTOCs (exact and as a Hadamard-test circuit), Floquet quasi-energies, Trotter circuits with a physical T1/T2 noise model, and Hamiltonian-encoding quantum kernels.

Documentation: https://rasidi3112.github.io/quantum-chaos-framework/

Status

Version 0.4.0. See CHANGELOG.md and VALIDATION.md (what was tested, the results — including the negative ones — and what is not verified).

• Done: bug fixes (phase 0), symmetry-resolved spectral statistics (phase 1), packaging/tests/CI configuration/docs (phase 2), and the research features of phase 3: spectral form factor, finite-temperature OTOCs, Krylov complexity, operator size, ETH and Page curves (3B); sparse parity-sector SYK to N = 34, KPM and dynamical typicality (3A); Floquet high-frequency expansions and heating (3C); Trotter bounds, sparse SYK, noisy interferometric OTOCs with echo normalisation and ZNE (3D); kernel concentration and statistical comparison with an RBF baseline (3E).
• Main negative results: no Lyapunov exponent can be established at the accessible sizes — a finite-size rescaling analysis up to N = 34 cannot distinguish exponential growth from a power law, and the chaos bound is not tested; quantum kernels are significantly worse than a tuned RBF-SVM on the benchmarks used.
• CI (GitHub Actions) passes on Ubuntu and macOS for Python 3.11–3.13 (and 3.14).
• Open: citation metadata/DOI, the choice of the Floquet drive protocol.

Installation

git clone https://github.com/rasidi3112/quantum-chaos-framework.git
cd quantum-chaos-framework
pip install -e ".[test]"   # or ".[dev]" for lint, type checks and docs
pytest                     # fast suite (~30 s)
pytest -m slow             # long statistical tests (~1 min)
mkdocs build --strict      # documentation, executes the tutorials (needs ".[docs]")

Requires Python ≥ 3.11 and PennyLane 0.45.x (pinned), NumPy, SciPy, Matplotlib and scikit-learn.

Quick start

from quantum_chaos.hamiltonians import SYKHamiltonian, hubbard_level_statistics
from quantum_chaos.hamiltonians.syk_hamiltonian import disorder_average_lsr, syk_rmt_reference

# One SYK realisation: symmetry class from N mod 8, sector-resolved <r>
syk = SYKHamiltonian(n_majorana=14, seed=1)
print(syk.symmetry_class, round(syk.get_level_spacing_ratio(), 4))

# Disorder average vs. random-matrix theory with the same number of levels
stats = disorder_average_lsr(14, n_realizations=100, rng=0)
ref = syk_rmt_reference(14, n_samples=500, rng=1)
print(
    f"<r> = {stats['mean']:.4f} ± {stats['stderr']:.4f}  (RMT {ref['mean']:.4f}, "
    f"large-N {stats['reference']:.4f})"
)

# Hubbard ring, fully symmetry resolved: integrable (t'=0) vs t'=0.5
for tp in (0.0, 0.5):
    res = hubbard_level_statistics(n_sites=8, n_up=4, n_down=4, tp=tp, U=4.0)
    print(f"t'={tp}: <r> = {res['mean']:.4f} ± {res['stderr']:.4f}")

Output (macOS, Python 3.13, NumPy 2.5.4):

GUE 0.6502
<r> = 0.6010 ± 0.0034  (RMT 0.5992, large-N 0.5996)
t'=0.0: <r> = 0.3863 ± 0.0053
t'=0.5: <r> = 0.5173 ± 0.0048

python main.py prints a longer demonstration and regenerates the figure below (~30 s). make figures regenerates every figure from the YAML files in configs/figures/ (seeds included), each with a JSON sidecar holding the plotted numbers and provenance; make validate regenerates the validation tables (~40 min).

(a) SYK ⟨r⟩ per N (black) and random matrices with the same number of levels (open squares), with the large-N values of Atas et al.; the class follows N mod 8. (b) Hubbard ring L=8, N=4+4, U=4: integrable t'=0 vs t'=0.5 (at L=8 still below GOE; L=10 results in VALIDATION.md). (c) Infinite-temperature OTOC of one realisation (qualitative). (d) Numbers shown in (a) and (b).

Figures

Every figure is produced by make figures from the YAML file named below (configs/figures/); the plotted numbers and the provenance (git commit, library versions) are stored next to each image as a .json file. Details and error analysis are in VALIDATION.md.

Level-spacing-ratio distributions — ratio_distributions.yaml

Histograms of r̃ for SYK N = 16 (GOE), 18 (GUE), 20 (GSE) and for the Hubbard ring (L = 8, t' = 0 and 0.5), against the Wigner-like surmises of Atas et al. (dashed).

Spectral form factor — sff.yaml

(a) Disorder-averaged SFF at β = 0 with dip, ramp and plateau; dotted lines are the exact plateaus 1/L (N mod 8 = 0) and 2/L (otherwise). (b) Unfolded, sector-resolved connected form factor against the GOE/GUE/GSE predictions.

Scrambling and operator growth — chaos_dynamics.yaml

(a) Regularised Majorana OTOC for interacting SYK4 and the free SYK2 control. (b) Lanczos coefficients: the Krylov space of the free model ends after N − 1 steps. (c) Mean Majorana size of χ₀(t). (d) Entanglement of mid-spectrum eigenstates (N = 20) against the Page curve. No Lyapunov exponent is extracted: the early-time growth is ∝ t² at these sizes.

Finite-size rescaling of the OTOC — syk_lyapunov.yaml

Regularised OTOC for N = 20–34 at βJ = 0 and 10, analysed with the crossing-time rescaling of Kobrin et al. (PRL 126, 030602). (a) 1 − F(t)/F(0) with the thresholds 0.25 and 0.16. (b) Crossing time against ln N. (c) Exponents from neighbouring sizes and the bias-corrected global fit. At βJ = 0 the corrected fit gives λ ≈ 0.6 ± 0.3, but a power law t ∝ N^0.37 fits equally well; at βJ = 10 no bias-free estimate is possible. Exponential growth and the chaos bound are therefore not established (VALIDATION.md §3.6). The figure is built from results/syk_lyapunov.json, which scripts/syk_lyapunov.py produces in about 3 h on an Apple M1.*

Floquet heating and high-frequency expansion — floquet_heating.yaml

Driven Hubbard ring J(t) = 1 + cos ωt, t' = 0.5, U = 4. (a) Absorbed energy versus the number of periods. (b) Time-averaged absorbed fraction versus ω for L = 6 and 8. (c) Error of the van Vleck effective Hamiltonian at orders 0 and 2 (slopes ≈ −2 and −4).

Quantum circuits and noise — nisq.yaml

(a) Trotter error against the first-order commutator bound of Childs et al. (b) CNOTs per Trotter step for dense and sparse (k = 4) SYK. (c) Sparse-SYK ⟨r⟩ versus k. (d) Noisy interferometric OTOC (N = 6, depolarizing p = 0.005): raw, echo-normalised and zero-noise-extrapolated, for SYK4 and SYK2.

Quantum kernels — qml.yaml

(a, b) Variance of the fidelity kernel versus system size for the SYK and Hubbard Hamiltonian encodings, with Haar references. (c) Test accuracy over 20 seeds against a cross-validated RBF-SVM; both quantum kernels are significantly worse (Wilcoxon p ≤ 0.013).

Conventions

• SYK: H = Σ_{i<j<k<l} J_ijkl χ_i χ_j χ_k χ_l with ⟨J²⟩ = 3! J²/N³. The Majoranas are Jordan–Wigner Pauli strings with χ² = 1; Maldacena–Stanford and Cotler et al. use {χ_a, χ_b} = δ_ab (χ² = ½), whose Hamiltonian is H/4 — use SYKHamiltonian(..., chi_squared=0.5) when comparing energies.
• Symmetry classes (per fermion-parity sector): GOE for N mod 8 = 0, GUE for 2 and 6 (the two sectors are then degenerate), GSE for 4 (Kramers pairs inside each sector, one level per pair is kept). Spectra of different sectors are never merged, and no "small spacing" filter is applied.
• Hubbard ring: H = −t Σ (c†{j+1}c_j + h.c.) − t′ Σ (c†{j+2}c_j + h.c.) + U Σ n_{j↑}n_{j↓} with periodic boundary conditions; levels are resolved by N↑, N↓, momentum, reflection (K = 0, π), total spin and — for t′ = 0 and even L — η-spin.
• Noise: T1/T2 relaxation with 1/T_φ = 1/T2 − 1/(2T1) for the physical duration of each step; depolarizing error ρ → (1−p)ρ + p I/2 per gate layer (PennyLane parameter 3p/4).

Validation summary

Full tables, tolerances and open items: VALIDATION.md.

Check	Result
SYK ⟨r⟩, N = 10…22, all three classes	agrees with same-size RMT, |z| ≤ 1.1
Particle-hole operator P: [P,H]=0, P² = (−1)^{n(n−1)/2}	exact (1e-12)
Hubbard ED: U=0 free fermions, t=0 limit, union of blocks, JW cross-check	exact (1e-10)
Hubbard ring L=10, N=5+5, U=4: t′=0 vs t′=0.5	0.3857(14) vs 0.5287(13): Poisson 0.3863 vs GOE 0.5307 (−1.5σ); smaller/dilute sectors still below GOE
OTOC Hadamard-test circuit vs exact OTOC	1e-8
Noise model: |ρ01| ∝ exp(−t/T2), P1 ∝ exp(−t/T1)	1e-10

Limitations (honest list)

• System sizes are those of exact diagonalisation on a laptop (SYK N ≤ 24, Hubbard L ≤ 10); no claim is made about the thermodynamic limit.
• For the non-integrable Hubbard ring (t′ = 0.5), ⟨r⟩ is consistent with GOE only for L = 10 at N = 4+4 and 5+5; at L = 8 and in dilute sectors it is still below GOE (finite-size effect). Only t′ = 0.5, U = 4 were studied.
• The integrable chain (t′ = 0) keeps 0.2–1.7 % exactly degenerate spacings after all resolved symmetries; their origin is not analysed.
• No Lyapunov exponent, butterfly velocity or scrambling time is established: the finite-size rescaling analysis up to N = 34 (VALIDATION.md §3.6) cannot separate exponential from power-law growth, and the chaos bound is not tested.
• No advantage of any quantum kernel is claimed; against a tuned RBF-SVM the quantum kernels are significantly worse on the benchmarks used (VALIDATION.md §7).
• The Floquet effective Hamiltonian is implemented only at leading order.

Project structure

quantum-chaos-framework/
├── pyproject.toml
├── src/quantum_chaos/
│   ├── hamiltonians/   # SYK (sparse, symmetry classes), Hubbard ring ED, driven Hubbard (Floquet)
│   ├── spectral/       # spacing ratios, RMT references and samplers
│   ├── chaos/          # moments, SFF, OTOC/Lyapunov, Krylov, operator size, ETH, KPM, typicality
│   ├── floquet/        # van Vleck / Magnus expansions, propagators, heating
│   ├── circuits/       # Trotter circuits and bounds, gate counts, (noisy) interferometric OTOC, ZNE
│   ├── noise/          # Kraus channels, T1/T2 model, noisy Trotter circuits
│   ├── qml/            # Hamiltonian-encoding kernels, concentration, RBF comparison
│   ├── experiments/    # YAML configs -> figures with provenance
│   ├── utils/          # partial trace, fidelity, Jordan-Wigner, RNG helpers
│   └── visualization/
├── configs/figures/    # one YAML file per figure (seeds included)
├── figures/            # generated figures + JSON sidecars (make figures)
├── docs/               # MkDocs site, tutorials (jupytext .py)
├── scripts/            # make_figures.py, validate_level_statistics.py, large_n_syk.py, syk_lyapunov.py
├── benchmarks/         # time and memory vs N
├── results/            # validation numbers (JSON)
├── tests/
└── main.py

References

Checked against the arXiv/journal record (†) or cited from memory and still to be verified:

1. Y. Y. Atas, E. Bogomolny, O. Giraud, G. Roux, Distribution of the ratio of consecutive level spacings in random matrix ensembles, PRL 110, 084101 (2013). †
2. J. S. Cotler, G. Gur-Ari, M. Hanada, J. Polchinski, P. Saad, S. H. Shenker, D. Stanford, A. Streicher, M. Tezuka, Black holes and random matrices, JHEP 05 (2017) 118. †
3. J. Maldacena, D. Stanford, Comments on the Sachdev-Ye-Kitaev model, PRD 94, 106002 (2016). †
4. S. Sachdev, J. Ye, Gapless spin-fluid ground state in a random quantum Heisenberg magnet, PRL 70, 3339 (1993) †; A. Kitaev, KITP talks (2015).
5. V. Oganesyan, D. A. Huse, Localization of interacting fermions at high temperature, PRB 75, 155111 (2007) (spacing ratio). †
6. B. Swingle, G. Bentsen, M. Schleier-Smith, P. Hayden, Measuring the scrambling of quantum information, PRA 94, 040302 (2016). †
7. J. Maldacena, S. H. Shenker, D. Stanford, A bound on chaos, JHEP 08 (2016) 106. †
8. F. H. L. Essler et al., The One-Dimensional Hubbard Model (CUP, 2005); C. N. Yang, PRL 63, 2144 (1989) (η-pairing).

License

MIT — see LICENSE.

Maintainer

@rasidi3112