dense-evolution 8.3.0__py3-none-win_amd64.whl

dense_evolution/mitigation/magic_entropy_shadows.py

@@ -0,0 +1,262 @@
+"""Classical-shadows-based estimator for `magic_entropy` (see
+`magic_entropy.py` in this same subpackage) -- estimates the same
+single-qubit non-stabilizerness quantity from randomized measurement
+snapshots instead of requiring the exact density matrix.
+
+Originated from a Colab proposal for a `dense_evolution/circuits/shadows.py`
+module (following Huang, Kueng, Preskill 2020, "Predicting Many Properties
+of a Quantum System from Very Few Measurements") with a real bug in its
+purity estimator (a missing transpose in a U-statistic einsum contraction,
+silent whenever every snapshot happened to be real-valued). Fixed, then
+extended -- using the same multi-copy U-statistic trick the paper says
+"readily generalizes to higher order polynomials" -- to estimate
+`magic_entropy`'s reduced convolution matrix from shadow snapshots instead
+of the exact rho. Matured across Dense-Evolution-Discovery Experiment 31
+(three real gaps found and closed there before promotion: the purity
+estimator bug, missing median-of-means robustness, and no
+sample-complexity guidance):
+https://tatopenn-cell.github.io/Dense-Evolution-Discovery/quantum_shadows_magic_entropy/
+
+API SHAPE differs from every other function in this subpackage: sampling
+(`sample_classical_shadow`) and estimation (`magic_entropy_from_shadows`)
+are separate steps, matching how classical shadows work in general -- the
+snapshot data can come from this simulator (`sample_classical_shadow` uses
+oracle access to `rho`'s exact Born-rule probabilities, something only a
+simulator has) or, in principle, from real hardware measurement outcomes
+reconstructed the same way (`rho_hat = 3 U^dagger |b><b| U - I` per
+snapshot, from a recorded basis+outcome).
+
+Restricted to SINGLE-QUBIT density matrices, matching `magic_entropy`'s
+own scope.
+"""
+import functools
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+
+from .magic_entropy import _key_unitary_k3
+
+__all__ = [
+    "sample_classical_shadow", "magic_entropy_from_shadows",
+    "approx_shadow_std", "fit_shadow_sample_complexity",
+]
+
+# Single-qubit random-Pauli classical shadow protocol (Huang, Kueng,
+# Preskill 2020, eq. 2-3): the three diagonalizing unitaries for X, Y, Z.
+@functools.lru_cache(maxsize=1)
+def _basis_u() -> jnp.ndarray:
+    """Cached, lazily-built stack of the 3 diagonalizing unitaries -- same
+    "defer past the import-time x64 warning" fix as magic_entropy.py's
+    _key_unitary_k3(); see that function's docstring for why a bare
+    module-level `jnp.array(..., dtype=jnp.complex128)` here used to fire
+    a spurious UserWarning on every `import dense_evolution`."""
+    h = jnp.array([[1.0, 1.0], [1.0, -1.0]], dtype=jnp.complex128) / jnp.sqrt(2.0)
+    sdag = jnp.array([[1.0, 0.0], [0.0, -1j]], dtype=jnp.complex128)
+    return jnp.stack([h, h @ sdag, jnp.eye(2, dtype=jnp.complex128)])
+
+
+def sample_classical_shadow(rho: jnp.ndarray, n_snapshots: int, seed: int = 0) -> jnp.ndarray:
+    """Simulates the real single-qubit random-Pauli classical-shadow
+    measurement protocol against a known `rho` (2x2, pure or mixed): for
+    each of `n_snapshots` independent draws, picks a random Pauli basis
+    uniformly, samples a computational-basis outcome from the true
+    Born-rule probability under that basis (this simulator has oracle
+    access to `rho`, unlike real hardware), then reconstructs the
+    classical snapshot `rho_hat = 3 U^dagger |b><b| U - I`.
+
+    Returns an `(n_snapshots, 2, 2)` complex128 array -- feed this
+    directly into `magic_entropy_from_shadows`.
+
+    Each individual `rho_hat` is NOT a valid density matrix on its own
+    (can have negative eigenvalues) -- only the average over many
+    snapshots converges to the true `rho`. Verified directly in
+    Dense-Evolution-Discovery Experiment 31: the empirical mean over
+    200,000 snapshots matched the true state to within 0.004.
+    """
+    rho = jnp.asarray(rho, dtype=jnp.complex128)
+    key = jax.random.PRNGKey(seed)
+    key_basis, key_bit = jax.random.split(key)
+    bases = jax.random.randint(key_basis, (n_snapshots,), 0, 3)
+
+    basis_u = _basis_u()
+
+    def prob0(basis_idx):
+        u = basis_u[basis_idx]
+        rotated = u @ rho @ jnp.conj(u).T
+        return jnp.clip(jnp.real(rotated[0, 0]), 0.0, 1.0)
+
+    probs0 = jax.vmap(prob0)(bases)
+    uniforms = jax.random.uniform(key_bit, (n_snapshots,))
+    bits = (uniforms > probs0).astype(jnp.int32)
+
+    def snapshot_matrix(basis_idx, bit):
+        u = basis_u[basis_idx]
+        b_ket = jnp.array([1.0, 0.0], dtype=jnp.complex128) * (1 - bit) + \
+            jnp.array([0.0, 1.0], dtype=jnp.complex128) * bit
+        proj = jnp.outer(b_ket, jnp.conj(b_ket))
+        return 3.0 * (jnp.conj(u).T @ proj @ u) - jnp.eye(2, dtype=jnp.complex128)
+
+    return jax.vmap(snapshot_matrix)(bases, bits)
+
+
+@functools.lru_cache(maxsize=1)
+def _o_operators():
+    """O_ab = V^dagger (|b><a| (x) I_4) V such that R_ab = Tr[O_ab . rho^{(x)3}]
+    -- the same construction `magic_entropy.py`'s `_self_convolve_3_core`
+    applies to exact `rho`, here turned into fixed operators so each entry
+    is a LINEAR functional of `rho^{(x)3}` (the shape a shadow-snapshot
+    U-statistic estimator needs). Reuses this package's own
+    `_key_unitary_k3()` directly rather than duplicating it (unlike
+    Dense-Evolution-Discovery's per-script self-containment convention,
+    this library's internal modules import from each other freely). The
+    `|b><a|` (not `|a><b|`) projector is deliberate: a direct index-expansion
+    check (not just the cyclic-trace derivation, which looks right on paper
+    but hides the swap) showed `Tr[(|a><b| (x) I) M] = R_ba`, not `R_ab` --
+    caught in Discovery Experiment 31 by a unit test checking matrix
+    entries directly, not just the downstream entropy.
+
+    Cached/lazy (functools.lru_cache), not a bare module-level constant
+    -- same "defer past the import-time x64 warning" fix as
+    magic_entropy.py's _key_unitary_k3() and this module's _basis_u()."""
+    i4 = jnp.eye(4, dtype=jnp.complex128)
+    v = _key_unitary_k3()
+    ops = {}
+    for a in range(2):
+        for b in range(2):
+            proj_ba = jnp.zeros((2, 2), dtype=jnp.complex128).at[b, a].set(1.0)
+            ops[(a, b)] = jnp.conj(v).T @ jnp.kron(proj_ba, i4) @ v
+    return ops
+
+
+def _median_of_means(values: np.ndarray, n_groups: int) -> float:
+    """Split real-valued `values` into `n_groups` contiguous batches,
+    average each batch, then return the median of those batch means --
+    Huang et al.'s standard robustification for shadow-estimator
+    U-statistics. Unlike a single overall mean, the median tolerates up
+    to `n_groups // 2` entirely corrupted/outlier batches (e.g. a
+    systematic calibration fault affecting one contiguous stretch of a
+    measurement run) without being dragged toward them -- verified
+    directly in Dense-Evolution-Discovery Experiment 31: stays within 0.5
+    of the true value at 40% of samples corrupted, while a plain mean is
+    dragged from 1.0 to -19.4 under the same corruption."""
+    values = np.asarray(values, dtype=float)
+    n = len(values)
+    n_groups = max(1, min(n_groups, n))
+    group_size = n // n_groups
+    trimmed = values[: group_size * n_groups]
+    group_means = trimmed.reshape(n_groups, group_size).mean(axis=1)
+    return float(np.median(group_means))
+
+
+def magic_entropy_from_shadows(shadow_snapshots: jnp.ndarray, n_groups: int = 20) -> float:
+    """Estimates `magic_entropy(rho)` from classical shadow snapshots of
+    `rho` (from `sample_classical_shadow`, or real hardware measurement
+    data reconstructed the same way) instead of the exact density matrix.
+
+    Groups the snapshots into disjoint triples, estimates each entry of
+    the 3-copy self-convolution's reduced matrix `R` via median-of-means
+    over `Tr[O_ab . (rho_hat_i (x) rho_hat_j (x) rho_hat_k)]` (unbiased,
+    since each triple's three snapshots are independent unbiased
+    estimators of `rho`; real and imaginary parts of each entry are
+    median-of-means'd separately, the standard practical choice since a
+    complex median has no single definition), then computes the von
+    Neumann entropy of the (Hermitized, eigenvalue-clipped, trace-
+    renormalized) ESTIMATED `R` classically -- entropy itself is never
+    shadow-estimated directly, matching how Huang et al. handle their own
+    Renyi-2 entanglement entropy example.
+
+    Not `jax.jit`-compatible (unlike every other function in this
+    subpackage): median-of-means uses `numpy.median`, which has no
+    equivalent JAX primitive at this scale.
+
+    See `approx_shadow_std`/`fit_shadow_sample_complexity` for how many
+    snapshots this needs for a given error tolerance.
+    """
+    n = shadow_snapshots.shape[0]
+    n_triples = n // 3
+    if n_triples < 1:
+        raise ValueError(f"need at least 3 shadow snapshots to form one triple, got {n}")
+    triples = shadow_snapshots[: n_triples * 3].reshape(n_triples, 3, 2, 2)
+
+    def triple_kron(t):
+        return jnp.kron(jnp.kron(t[0], t[1]), t[2])
+
+    rho3_batch = jax.vmap(triple_kron)(triples)
+
+    r_hat = jnp.zeros((2, 2), dtype=jnp.complex128)
+    for (a, b), o_ab in _o_operators().items():
+        vals = np.array(jnp.einsum("ij,tji->t", o_ab, rho3_batch))
+        real_part = _median_of_means(vals.real, n_groups)
+        imag_part = _median_of_means(vals.imag, n_groups)
+        r_hat = r_hat.at[a, b].set(real_part + 1j * imag_part)
+
+    r_hat = 0.5 * (r_hat + jnp.conj(r_hat).T)  # enforce Hermiticity
+    ev = jnp.linalg.eigvalsh(r_hat)
+    safe_ev = jnp.clip(ev.real, 1e-9, None)
+    safe_ev = safe_ev / jnp.sum(safe_ev)  # renormalize (estimation noise can shift trace off 1)
+    return float(-jnp.sum(safe_ev * jnp.log2(safe_ev)))
+
+
+# Empirically fitted in Dense-Evolution-Discovery Experiment 31 (20 trials
+# per snapshot count on a |T> state, n_groups=20): std(n_snapshots) ~
+# _FIT_C / n_snapshots ** _FIT_P. The T-state is a standard maximally-magic
+# single-qubit state, a reasonable but NOT rigorously proven proxy for a
+# "hard" case -- this is a rough built-in guide, not a formal guarantee for
+# an arbitrary rho.
+_FIT_C = 11.751
+_FIT_P = 0.546
+
+
+def approx_shadow_std(n_snapshots: int) -> float:
+    """Rough approximate standard deviation (bits) of
+    `magic_entropy_from_shadows`'s estimate at a given snapshot count,
+    from an empirical fit (not a formal theorem) calibrated on a `|T>`
+    state in Dense-Evolution-Discovery Experiment 31: 20 independent
+    trials at each of 4 snapshot counts (3,000-100,000), a log-log linear
+    regression gave `std(n) ~ 11.75 / n^0.546` -- the fitted exponent
+    (0.546) is close to the ~0.5 ("error shrinks like 1/sqrt(n)") standard
+    shadow/median-of-means theory predicts.
+
+    This is a quick sanity-check fallback, not a guarantee for an
+    arbitrary state -- call `fit_shadow_sample_complexity` on YOUR
+    specific state if you need a real, state-calibrated error bound.
+    """
+    return _FIT_C / float(n_snapshots) ** _FIT_P
+
+
+def fit_shadow_sample_complexity(rho: jnp.ndarray, exact_value: float, n_snapshots_list, n_trials: int, seed_base: int = 0):
+    """Empirically measures `magic_entropy_from_shadows`'s standard
+    deviation across `n_trials` independent shadow samplings at each
+    snapshot count in `n_snapshots_list`, for the SPECIFIC state `rho`
+    (rather than trusting `approx_shadow_std`'s built-in T-state-derived
+    fallback), then fits `std(n) ~ C / n^p` via log-log linear regression
+    -- the same method used to derive `approx_shadow_std`'s constants in
+    the first place (Dense-Evolution-Discovery Experiment 31).
+
+    `exact_value` should be `magic_entropy(rho)` -- used only to also
+    report each snapshot count's mean estimation bias alongside the
+    fitted curve, not part of the fit itself.
+
+    Returns `(rows, fit_c, fit_p)`: `rows` is a list of per-snapshot-count
+    dicts (`n_snapshots`, `mean_estimate`, `std_estimate`,
+    `mean_abs_error`); `fit_c`/`fit_p` are the fitted constants for
+    `C / n^p`, usable the same way as `approx_shadow_std` (or pass them to
+    `approx_shadow_std`'s formula directly: `fit_c / n ** fit_p`).
+    """
+    rows = []
+    for n_snap in n_snapshots_list:
+        estimates = []
+        for trial in range(n_trials):
+            snaps = sample_classical_shadow(rho, n_snap, seed=seed_base + trial)
+            estimates.append(magic_entropy_from_shadows(snaps))
+        estimates = np.array(estimates)
+        rows.append({
+            "n_snapshots": n_snap, "n_trials": n_trials,
+            "mean_estimate": float(estimates.mean()), "std_estimate": float(estimates.std()),
+            "mean_abs_error": float(abs(estimates.mean() - exact_value)),
+        })
+    log_n = np.log([r["n_snapshots"] for r in rows])
+    log_std = np.log([r["std_estimate"] for r in rows])
+    slope, intercept = np.polyfit(log_n, log_std, 1)
+    return rows, float(np.exp(intercept)), float(-slope)

dense_evolution/mitigation/renyi.py

@@ -0,0 +1,168 @@
+"""Sandwiched Quantum Renyi Divergence for full density-matrix diagnostics
+(Muller-Lennert, Reeb, Wolf, Wilde, "On quantum Renyi entropies: a new
+generalization and some applications", arXiv:1306.3142, Definition 1).
+
+D_alpha(rho||sigma) = 1/(alpha-1) * log2 Tr[(sigma^e rho sigma^e)^alpha],
+e = (1-alpha)/(2*alpha), with the alpha->1 limit reducing to the standard
+quantum relative entropy and alpha=1/2 reducing to a fidelity-based form.
+
+Originated from a Colab proposal with a real bug in its case_general
+branch: `tr_inner = jnp.maximum(tr_inner, 1.0)` floors the inner trace at
+1.0 even when the true value is < 1 (the normal case for non-commuting
+rho, sigma), silently forcing every result to log2(1)=0 -- confirmed
+directly in the Colab's own printed output (alpha=1.5 gave exactly
+0.000000 across an entire rotation sweep). A second, deeper bug survived
+the floor-value fix alone: for alpha > 1, a trace below 1 is not a
+numerical artifact to clamp away, it is the genuine signature of a
+support mismatch (supp(rho) not contained in supp(sigma)), which the
+divergence must report as +inf, not a finite (and wrong-signed) number --
+verified by hand on two different pure states: Tr[Q^1.5] = 0.6759,
+matching the closed-form prediction (|<sigma|rho>|^2)^alpha exactly, and
+plugging that into the naive formula gives a finite NEGATIVE divergence,
+worse than the original bug's silent zero since it looks plausible
+instead of visibly wrong.
+
+Fixed and validated in Dense-Evolution-Discovery, Experiment 29
+(https://tatopenn-cell.github.io/Dense-Evolution-Discovery/sandwiched_renyi_density_matrix/):
+against the alpha->1 relative-entropy limit (matches an independent numpy
+reference to 4 decimal places), the commuting/diagonal case (reduces
+exactly to the classical Renyi divergence), and the support-violation
++inf case (verified at alpha>1, confirmed the branch does not fire
+spuriously at alpha<1).
+
+Its originally proposed use case -- replacing the JSD-based truncation
+criterion in dense_evolution.mps's bond-dimension search -- was
+independently disproven: on the diagonal singular-value spectrum used
+there, rho and sigma commute, so a non-commuting-aware divergence induces
+the exact same truncation ordering as JSD (5 benchmark configurations,
+byte-identical chi_used and truncation error every time) -- nothing for
+it to add in that setting. Promoted here instead for the genuinely
+non-commuting full-density-matrix diagnostic use case it WAS validated
+against: alongside uhlmann_fidelity, tracking a Bell state degraded by
+amplitude damping, where the two metrics' noise-sensitivity curves
+visibly diverge from each other.
+"""
+import jax
+import jax.numpy as jnp
+
+__all__ = ["sandwiched_renyi_divergence", "sandwiched_renyi_divergence_jit"]
+
+_EPS = 1e-12
+
+
+def _case_half(rho, sigma):
+    ev_r, ec_r = jnp.linalg.eigh(rho)
+    safe_ev_r = jnp.where(ev_r > _EPS, ev_r, 0.0)
+    sqrt_rho = (ec_r * jnp.sqrt(safe_ev_r)) @ jnp.conj(ec_r).T
+    uhlmann_mat = sqrt_rho @ sigma @ sqrt_rho
+    ev_u = jnp.linalg.eigvalsh(uhlmann_mat)
+    safe_ev_u = jnp.where(ev_u > _EPS, ev_u, 0.0)
+    fidelity = jnp.clip(jnp.sum(jnp.sqrt(safe_ev_u)), 0.0, 1.0)
+    return -2.0 * jnp.log2(jnp.maximum(fidelity, _EPS))
+
+
+def _case_one(rho, sigma):
+    ev_r, ec_r = jnp.linalg.eigh(rho)
+    safe_ev_r = jnp.where(ev_r > _EPS, ev_r, 1.0)
+    log_rho = (ec_r * jnp.where(ev_r > _EPS, jnp.log2(safe_ev_r), 0.0)) @ jnp.conj(ec_r).T
+    ev_s, ec_s = jnp.linalg.eigh(sigma)
+    safe_ev_s = jnp.where(ev_s > _EPS, ev_s, 1.0)
+    log_sigma = (ec_s * jnp.where(ev_s > _EPS, jnp.log2(safe_ev_s), 0.0)) @ jnp.conj(ec_s).T
+    return jnp.trace(rho @ (log_rho - log_sigma)).real
+
+
+def _case_general(rho, sigma, alpha):
+    exponent = (1.0 - alpha) / (2.0 * alpha)
+    ev_s, ec_s = jnp.linalg.eigh(sigma)
+    mask_s = ev_s > _EPS
+    safe_ev_s = jnp.where(mask_s, ev_s, 1.0)
+    pow_ev_s = jnp.where(mask_s, safe_ev_s ** exponent, 0.0)
+    sigma_pow = (ec_s * pow_ev_s) @ jnp.conj(ec_s).T
+
+    int_m = sigma_pow @ rho @ sigma_pow
+    v_int = jnp.linalg.eigvalsh(int_m)
+    mask_int = v_int > _EPS
+    safe_v_int = jnp.where(mask_int, v_int, 1.0)
+    pow_v_int = jnp.where(mask_int, safe_v_int ** alpha, 0.0)
+
+    tr_inner = jnp.sum(pow_v_int)
+
+    # For alpha > 1, D_alpha is finite only when supp(rho) subset supp(sigma);
+    # tr_inner < 1 there is the genuine signature of a support mismatch, not
+    # a numerical artifact -- see the module docstring's bug-history note.
+    is_support_violation = (alpha > 1.0) & (tr_inner < 1.0 - 1e-9)
+    tr_inner_safe = jnp.maximum(tr_inner, _EPS)
+    finite_result = ((1.0 / (alpha - 1.0)) * jnp.log2(tr_inner_safe)).real
+    return jnp.where(is_support_violation, jnp.inf, finite_result)
+
+
+def _sandwiched_renyi_divergence_core(rho: jnp.ndarray, sigma: jnp.ndarray, alpha: float = 1.5) -> jnp.ndarray:
+    # alpha must be a jnp value, not a raw Python float, before it reaches
+    # _case_general: jax.lax.cond traces BOTH branches regardless of which
+    # one runs, and `1.0 / (alpha - 1.0)` at alpha=1.0 raises a Python
+    # ZeroDivisionError if alpha is still a plain float at that point (the
+    # case_one branch's own guard never gets a chance to skip it) -- under
+    # jax.jit this conversion happens automatically (all arguments get
+    # traced), which is why the original un-split Discovery version never
+    # hit this; the eager (non-jit) core path here needs it explicitly.
+    alpha = jnp.asarray(alpha, dtype=jnp.float64)
+    is_half = jnp.isclose(alpha, 0.5)
+    is_one = jnp.isclose(alpha, 1.0)
+    return jax.lax.cond(
+        is_half, lambda: _case_half(rho, sigma),
+        lambda: jax.lax.cond(is_one, lambda: _case_one(rho, sigma), lambda: _case_general(rho, sigma, alpha)),
+    )
+
+
+def sandwiched_renyi_divergence(rho: jnp.ndarray, sigma: jnp.ndarray, alpha: float = 1.5) -> float:
+    """Sandwiched quantum Renyi divergence D_alpha(rho||sigma), in bits
+    (log2). `rho`, `sigma` are density matrices of the same dimension;
+    `alpha` selects the order (0.5 -> fidelity-based, 1.0 -> standard
+    relative entropy, both handled as exact closed-form limits rather
+    than through the general formula's own alpha->0.5/1 numerical
+    instability).
+
+    Zero when rho == sigma at every alpha (verified). For alpha > 1,
+    returns `+inf` when supp(rho) is not contained in supp(sigma) --
+    e.g. two different pure (rank-1) states -- rather than a finite
+    number; see the module docstring for why this is the mathematically
+    correct behavior, not an edge-case failure.
+
+    KNOWN LIMITATION at exactly alpha=1.0: the same support-violation
+    check is NOT applied to the alpha=1 (relative-entropy) branch, which
+    instead clips log(0)-type contributions to 0 rather than diverging --
+    e.g. D_1(rho||sigma) for two different pure states returns 0.0, not
+    +inf, even though the true relative entropy diverges there too.
+    Experiment 29 validated the alpha=1 branch only against full-rank
+    (depolarized) inputs specifically to sidestep this exactly-singular
+    case (`scipy.linalg.logm` itself raises `LogmExactlySingularWarning`
+    on singular inputs -- an inherent ill-conditioning of relative
+    entropy near degenerate support, not unique to this implementation).
+    Do not rely on alpha=1 to correctly flag a support mismatch; use
+    alpha slightly above 1 (e.g. 1.001) if that matters for your use case.
+
+    Validation-only, like `uhlmann_fidelity`: meant to grade a correction
+    against a known reference state, not to feed into one (see
+    `uhlmann_fidelity`'s docstring for the full "ideal state as oracle"
+    argument, which applies here identically).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from dense_evolution.mitigation.renyi import sandwiched_renyi_divergence
+    >>> rho = np.array([[1, 0], [0, 0]], dtype=complex)
+    >>> round(float(sandwiched_renyi_divergence(rho, rho, alpha=1.5)), 4)
+    0.0
+    >>> sigma = np.array([[0.5, 0], [0, 0.5]], dtype=complex)
+    >>> round(float(sandwiched_renyi_divergence(rho, sigma, alpha=1.5)), 4)
+    1.0
+    """
+    rho = jnp.asarray(rho, dtype=jnp.complex128)
+    sigma = jnp.asarray(sigma, dtype=jnp.complex128)
+    return float(_sandwiched_renyi_divergence_core(rho, sigma, alpha))
+
+
+sandwiched_renyi_divergence_jit = jax.jit(_sandwiched_renyi_divergence_core)
+"""`jax.jit`-compiled entry point for `sandwiched_renyi_divergence`. `rho`/
+`sigma` must already be `complex128`. Returns a jnp scalar, not a Python
+`float`."""

dense_evolution/mitigation/stabilizer_renyi_entropy.py

@@ -0,0 +1,103 @@
+"""Stabilizer Renyi Entropy (SRE): a per-STATE nonstabilizerness ("magic")
+monotone (Leone, Oliviero, Hamma, "Stabilizer Renyi Entropy",
+arXiv:2106.12587, Phys. Rev. Lett. 128, 050402 (2022), Eq. 5-8 there,
+labeled Eq. 14/18 in the paper that motivated promoting this).
+
+NOT the same quantity as `dense_evolution.mitigation.magic_entropy`
+(Bu-Gu-Jaffe's 3-fold self-convolution "Key Unitary" construction,
+single-qubit only) or `sandwiched_renyi_divergence` (Muller-Lennert et
+al., a DIVERGENCE between TWO density matrices -- "how different are rho
+and sigma", answering a different question entirely; the shared "Renyi"
+in both names is a coincidence of both being alpha-generalizations of
+entropy applied to different objects, not overlapping math). This SRE is
+a genuinely different, MULTI-qubit, SINGLE-state magic monotone: zero for
+every stabilizer state, positive otherwise.
+
+M_2(psi) = -log2[ (1/d) * sum_a sum_b |WHT[c_a](b)|^4 ], where
+c_a(x) = conj(psi(x)) * psi(x XOR a) and WHT is the length-d Walsh-Hadamard
+transform (signmat[b,x] = (-1)^popcount(b AND x)), d = 2**n_qubits.
+
+Verified against known values: every computational-basis/stabilizer state
+gives exactly 0; a single T state ((cos(pi/8), sin(pi/8)) in the
+computational basis) gives -log2(0.75) = 0.415037 bits, matching the
+closed-form derivation of Eq. 5 by hand (not a value copied from
+elsewhere).
+
+Promoted from Dense-Evolution-Discovery's wormhole_magic_entropy.py
+(2026-08-29), where it was implemented fresh because the existing
+magic_entropy is single-qubit only -- this quantity has no dependency on
+that use case (wormhole teleportation), so it belongs here as a general
+multi-qubit magic diagnostic.
+
+VECTORIZATION NOTE: the Discovery script's original version had an
+explicit Python `for a in range(d)` loop, each iteration doing its own
+(d,d)@(d,) matrix-vector product -- d sequential small matmuls. This
+promoted version instead builds the (d,d) matrix of every c_a(x) pair at
+once (broadcasting over x and a together) and applies the Walsh-Hadamard
+transform as ONE (d,d)@(d,d) matmul -- same O(d^3) total FLOP count, but
+expressed as a single large matmul JAX/XLA can execute efficiently
+(GPU/TPU-friendly, no per-iteration Python dispatch overhead), matching
+this package's JAX-by-default convention. Still O(d^3), not the paper's
+own asymptotically-better O(4^n * n) Walsh-Hadamard butterfly algorithm
+(n = log2(d) qubits) -- unimplemented here, same as the Discovery
+original; fine for d up to a few thousand (n up to ~11-12 qubits), the
+sizes this package's exact-statevector backends already target.
+"""
+import jax
+import jax.numpy as jnp
+
+__all__ = ["stabilizer_renyi_entropy", "stabilizer_renyi_entropy_jit"]
+
+
+def _stabilizer_renyi_entropy_core(psi):
+    d = psi.shape[0]
+    idx = jnp.arange(d)
+    # Static (trace-time) construction, same style as magic_entropy.py's
+    # _cnot_matrix -- one Python loop per distinct d, cached by jax.jit.
+    popcount = jnp.array([bin(i).count("1") for i in range(d)])
+
+    bitwise_and = idx[:, None] & idx[None, :]          # [b, x] = b & x
+    signmat = (-1.0) ** popcount[bitwise_and]            # Walsh-Hadamard sign matrix
+
+    xor_table = idx[:, None] ^ idx[None, :]              # [x, a] = x ^ a
+    c = jnp.conj(psi)[:, None] * psi[xor_table]          # [x, a] = c_a(x)
+
+    wht = signmat @ c                                     # [b, a] = WHT[c_a](b)
+    total = jnp.sum(jnp.abs(wht) ** 4)
+    return -jnp.log2(total / d)
+
+
+def stabilizer_renyi_entropy(psi):
+    """Stabilizer Renyi Entropy of a pure state `psi` (length 2**n_qubits),
+    in bits (log2) -- the paper's own convention.
+
+    Zero for every stabilizer state, positive for non-stabilizer ("magic")
+    states -- e.g. a single T state gives 0.415037 bits.
+
+    Parameters
+    ----------
+    psi : array-like, shape (2**n_qubits,)
+        A normalized pure statevector.
+
+    Returns
+    -------
+    float
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> psi0 = np.zeros(8, dtype=complex); psi0[0] = 1.0
+    >>> round(stabilizer_renyi_entropy(psi0), 6)  # computational basis state: stabilizer, expect 0
+    0.0
+    """
+    psi = jnp.asarray(psi, dtype=jnp.complex128)
+    d = psi.shape[0]
+    if d < 1 or (d & (d - 1)) != 0:
+        raise ValueError(f"psi length {d} is not a power of 2 (must be 2**n_qubits)")
+    return float(_stabilizer_renyi_entropy_core(psi))
+
+
+stabilizer_renyi_entropy_jit = jax.jit(_stabilizer_renyi_entropy_core)
+"""`jax.jit`-compiled entry point for `stabilizer_renyi_entropy`. `psi`
+must already be `complex128`. Returns a jnp scalar, not a Python `float`
+-- call `float(...)` yourself if you need one outside a jitted context."""