Tools for stabilizer-rank bounds on magic states.

Install

git clone https://github.com/unitaryfoundation/stabrank.git
cd stabrank
uv venv
uv pip install -e .

Quickstart

A two-term decomposition of |𝕊⟩^⊗2 via the simulated-annealing engine.

import numpy as np
from stabrank.target_functions import qutrit_strange_state
from stabrank.stabrank_core import run_sa_pauli_expansion

# 9-dim |S>^2
target = qutrit_strange_state(2)
n, p, chi = 2, 3, 2

initial_basis = [
    np.ones(p**n, dtype=complex) / np.sqrt(p**n)
    for _ in range(chi)
]

_, basis, coeffs, residual, *_ = run_sa_pauli_expansion(
    target=target,
    n_orig=n,
    p_prime=p,
    k_subset_size=chi,
    initial_basis=initial_basis,
    num_chains=16,
    early_exit_threshold=1e-12,
)

print(f"|S>^2 ≈ sum of {chi} stabilizer states, residual = {residual:.2e}")

A successful search terminates at machine precision, well below the 1e-12 early-exit threshold (the exact residual varies with the seed):

|S>^2 ≈ sum of 2 stabilizer states, residual = 1.88e-16

State of the art

Best known exact-rank upper bounds on χ_R(|M⟩^⊗m). Bold cells are tight (equality); other cells are one-sided bounds. Tightness comes either from an exhaustive lower-bound certificate or from projection monotonicity (χ(|M⟩^⊗m) ≥ χ(|M⟩^⊗m-1), by projecting one factor onto a computational-basis state of nonzero overlap) applied to a certified smaller-m value.

Qubit H-type orbit

Phase-state representative |T⟩ = (|0⟩ + e^iπ/4|1⟩)/√2, Clifford-equivalent to cos(π/8)|0⟩ + sin(π/8)|1⟩ (edge center of the stabilizer octahedron). The cells below are the standard literature values for the “qubit T-state” in the magic-state-distillation sense.

Qubit Bravyi–Kitaev T-type orbit

BK T-type representative |T⟩ = cosβ |0⟩ + e^iπ/4 sinβ |1⟩, cos(2β) = 1/√3 (face center of the stabilizer octahedron, Bloch vector (1,1,1)/√3). Distinct from the H-type orbit above.

Conjectured optimal low-rank approximations

For three targets just past the certified small-m frontier, extensive annealing (dense warm-started and cyclic-orbit symmetric searches) terminates at an exact algebraic residual and never below it. In each case an explicit stabilizer span achieving the value is verified in exact arithmetic by a standalone certificate script under stabrank/examples/, and we conjecture the value is optimal, which would make the sub-multiplicative construction tight:

The |T⟩^⊗6 witness is three cyclic shifts of |+i⟩|+⟩|0⟩|+i⟩|+⟩|0⟩ plus two shift-related graph states on the complement of a hexagon; the |𝕊⟩^⊗6 witness is any 7 of the 8 products built from the m = 2 Strange identity, all of which achieve the same residual.

Qutrits

Status of the T₃ cells

The m = 2 value is tight: an exhaustive sweep over all 85,491 row pairs of the parametrized two-qutrit dictionary (covering all 360 distinct stabilizer states) leaves a minimum least-squares residual of 0.4645 (stabrank/examples/t3m2_rank3_certificate.py), so no two-term decomposition of |T₃⟩^⊗2 exists. The m = 3 bound of [3] was stated there as a quadratic-Gauss-sum rank with the stabilizer-rank value marked uncertain (“8?”, supported by a possibly unconverged Monte Carlo search). It is now backed by an explicit eight-term stabilizer decomposition found with the annealing engine (supports 3, 3, 9, 27, 27, 27, 27, 27), each state matched against the exhaustive three-qutrit dictionary and the identity verified in exact arithmetic (stabrank/examples/t3m3_rank8_certificate.py). The m = 4 bound has an explicit nine-term product witness built from the carry decomposition of |T₃⟩^⊗2 (stabrank/examples/t3m2_rank3_certificate.py). At m = 3, no k = 7 decomposition was found across more than forty searches spanning fast and slow dense anneals, symmetric-ansatz searches, warm-started squeezes of the exact eight-term basis, and anneals from every prune position of that basis. All runs terminate at nonzero local minima (a recurring basin at residual 0.120393331639 was hit by five independent seeds to twelve digits); the deepest minimum found has residual 0.0821265100, and its basis snaps to exact stabilizer states whose least-squares residual squared is the smallest root of 466277476977288x³ − 258557391262152x² + 19913013136890x − 122689385209, an exact algebraic critical point of the search landscape. A structural exhaustion supports this: splitting F₃³ by the residue of x₁+x₂+x₃ mod 3, each of the three carry states of |T₃⟩^⊗3 has certified in-class rank 3, so a seven-term decomposition needs at least one state whose support crosses the classes. Enumerating all 29,160 class-crossing stabilizer states shows none can serve as the sole crossing state (zero survivors, nearest miss failing consistency by a relative 0.35), and a second exhaustion over all 1,431 ways a two-crossing-state decomposition could close its single-class-state class (4.6 million state pairs, both admissible class-state distributions) also leaves zero survivors. Any seven-term decomposition must therefore contain at least three class-crossing states (the exact eight-term witness uses five). We conjecture χ_R(T₃^⊗3) = 8.

Floors below the m = 4 cells

Slow-schedule searches one rank below the m = 4 bounds also terminate at exact algebraic floors, verified in exact arithmetic. For the Norrell orbit at k = 6, five of six independent anneals reach the identical residual √(211/4043) ≈ 0.2284, and the deepest basin found has the rational value √(419/8559) ≈ 0.2213; for H₃ at k = 7 the deepest captured basin has residual squared (3349 − 1418√3)/7280 ≈ 0.3502², with all runs ending in 0.344–0.358. No search reached zero, supporting the conjectures χ_R(N₊^⊗4) = 7 and χ_R(H₃^⊗4) = 8.

References

1. Bravyi, S., Smith, G., Smolin, J. A. Trading classical and quantum computational resources. Phys. Rev. X 6, 021043 (2016). arXiv:1506.01396 · DOI
2. Qassim, H., Pashayan, H., Gosset, D. Improved upper bounds on the stabilizer rank of magic states. Quantum 5, 606 (2021). arXiv:2106.07740 · DOI
3. Kocia, L., Sarovar, M. Improved simulation of quantum circuits by fewer Gaussian eliminations. Phys. Rev. A 103, 022603 (2021). arXiv:2003.01130 · DOI
4. Labib, F. Stabilizer rank and higher-order Fourier analysis. Quantum 6, 645 (2022). arXiv:2107.10551 · DOI
5. Jain, A., Prakash, S. Qutrit and ququint magic states. Phys. Rev. A 102, 042409 (2020). arXiv:2003.07164 · DOI
6. Labib, F., Russo, V. Stabilizer rank bounds for magic-state orbits. (2026). arXiv:2605.28586
7. Peleg, S., Shpilka, A., Volk, B. L. Lower bounds on stabilizer rank. Quantum 6, 652 (2022). arXiv:2106.03214 · DOI
8. Kissinger, A., van de Wetering, J., Vilmart, R. Classical simulation of quantum circuits with partial and graphical stabiliser decompositions. TQC 2022, LIPIcs 232, 5:1–5:13. arXiv:2202.09202 · DOI. Sharpens the H-type bound to a finite-rate χ_R(H^⊗t) ≤ (4/3)·2^0.3963 t via a partial-decomposition technique (|H⟩^⊗5 → 3 terms, each retaining a single |H⟩; iterated to remove four |H⟩s at the cost of tripling terms).

Cite the tool

@misc{labib2026stabilizer,
  title={Stabilizer rank bounds for magic-state orbits},
  author={Farrokh Labib and Vincent Russo},
  year={2026},
  eprint={2605.28586},
  archivePrefix={arXiv},
  primaryClass={quant-ph},
  url={https://arxiv.org/abs/2605.28586},
}