stabrank — 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.

m	1	2	3	4	5	6	7	8	asymptotic
χ_R(T^⊗m) ≤	2	2 [1]	3 [1]	4 [6]	6 [1]	6 [2]	12 [2]	12 [2]	2^αm, α = log₂(3)/4 ≈ 0.3963 [2][8]
χ_R(T^⊗m) ≥	2	2 [2]	3 [2]	4 [6]	4 [6]	4 [6]	4 [6]	4 [6]	m / 100 [7]

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.

m	1	2	3	4	asymptotic γ ≤
χ_R(T^⊗m) ≤	2	2 [6]	3 [6]	3 [6]	log₂(3)/4 ≈ 0.3963 [6]
χ_R(T^⊗m) ≥	2	2 [6]	3 [6]	3 [6]	—

Conjecture: six copies of the BK T-type state need rank 6

There is an explicit 5-dimensional stabilizer span whose least-squares distance to |T⟩^⊗6 is exactly √(5(2−√3)/24) = √(5/6) sin(π/12) ≈ 0.2363 (three cyclic shifts of the product state |+i⟩|+⟩|0⟩|+i⟩|+⟩|0⟩ together with two shift-related graph states on the complement of a hexagon; verified in exact arithmetic by stabrank/examples/ttype6_rank5_certificate.py). Eleven independent annealing campaigns across three unrelated search structures all terminated at this residual and never below it. We conjecture it is optimal, which would give χ_R(T^⊗6) = 6: sub-multiplicativity 3 × 2 tight at six copies.

Qutrits

orbit	m = 1	2	3	4	asymptotic γ ≤
Strange	2	2 [6]	4 [6]	4 [6]	log₃(2)/2 ≈ 0.316 [6]
H₃	2	3 [6]	4 [6]	≤8 [6]	log₃(4)/3 ≈ 0.421 [6]
Norrell	2	3 [6]	4 [6]	≤7 [6]	log₃(4)/3 ≈ 0.421 [6]
T₃	3	3 [3]	≤8 [3]	≤9	1/2 [3]

References

Bravyi, S., Smith, G., Smolin, J. A. Trading classical and quantum computational resources. Phys. Rev. X 6, 021043 (2016). arXiv:1506.01396 · DOI
Qassim, H., Pashayan, H., Gosset, D. Improved upper bounds on the stabilizer rank of magic states. Quantum 5, 606 (2021). arXiv:2106.07740 · DOI
Kocia, L., Sarovar, M. Improved simulation of quantum circuits by fewer Gaussian eliminations. Phys. Rev. A 103, 022603 (2021). arXiv:2003.01130 · DOI
Labib, F. Stabilizer rank and higher-order Fourier analysis. Quantum 6, 645 (2022). arXiv:2107.10551 · DOI
Jain, A., Prakash, S. Qutrit and ququint magic states. Phys. Rev. A 102, 042409 (2020). arXiv:2003.07164 · DOI
Labib, F., Russo, V. Stabilizer rank bounds for magic-state orbits. (2026). arXiv:2605.28586
Peleg, S., Shpilka, A., Volk, B. L. Lower bounds on stabilizer rank. Quantum 6, 652 (2022). arXiv:2106.03214 · DOI
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},
}

Tools for stabilizer-rank bounds on magic states.