dense-evolution 8.3.0__py3-none-win_amd64.whl

dense_evolution/mitigation/healing.py

@@ -0,0 +1,215 @@
+"""
+dense_evolution.healing -- predictive-healing primitives for noisy vector
+sequences (VQE/MD telemetry, quantum state trajectories).
+
+Built empirically, one formula at a time, not derived top-down from a
+named theory -- worth being precise about, since one piece of it turns
+out to have a real mathematical identity worth naming rather than
+leaving implicit: calculate_vettore_dinamico's core term,
+log(E_B / E_A), is a log-likelihood ratio -- the same elementary
+quantity Kullback-Leibler divergence (relative entropy) is built from
+(D_KL(A||B) = sum_x A(x) * log(A(x)/B(x)), a probability-weighted
+average of exactly this log-ratio, which calculate_vettore_dinamico
+does not compute -- it uses one un-weighted log-ratio between two
+scalars, not a full KL divergence over a distribution). Equivalently,
+if -log(E) is read as self-information ("surprisal"), log(E_B/E_A) is
+the *difference in surprisal* between the two states.
+
+Not every formula in this module carries the same reading -- calculate_
+phi_ab's blend of cosine-alignment and Euclidean-distance terms is a
+geometric similarity construction, not an information-theoretic one;
+naming it as such would be the overclaiming this note is trying to
+avoid, not fix.
+"""
+
+import math
+import warnings
+
+import jax
+import jax.numpy as jnp
+import json
+from datetime import datetime, timezone
+from typing import Dict, Tuple, List, Any
+
+
+GLOBAL_CONSTANTS = {
+    'TARGET_SIGMA_IDEALE': 10.0,
+    'THRESHOLD_DELTA_PREEMP': 0.2,
+    'SEMANTIC_LEARNING_RATE': 0.05,
+    'V_DINAMIC_K_COEFF': 5.0,
+    'V_STATIC_K_PRIME_COEFF': 1.0,
+    'V_DINAMIC_MIN_EFFECTIVE_VALUE': 0.01,
+    # Plain math.sqrt, not jnp.sqrt -- a bare jnp constant built at
+    # import time bakes in whatever precision jax_enable_x64 happens to
+    # be at that exact moment (permanently truncated to float32 if it's
+    # still False), the same class of bug config.py's ensure_x64()
+    # exists to avoid. This constant only ever divides a jnp array, so a
+    # plain Python float sidesteps the process-wide flag entirely.
+    'MAX_SEMANTIC_DISTANCE': math.sqrt(2.0),
+    'WEIGHT_SEMANTIC': 0.6,
+    'WEIGHT_COHERENCE': 0.4,
+    'NON_STATIC_THRESHOLD_A': 1e-2,
+    'DAMPING_BOOST_ON_STASIS': 0.1,
+    'EPSILON_DISSIPATION_BASE': 0.01
+}
+
+# =====================================================================
+# 📊 CORE LAYER
+# =====================================================================
+
+@jax.jit
+def _calculate_advanced_sigma_core(kappa: jnp.ndarray, H: jnp.ndarray, Psi: jnp.ndarray, Omega_sync: jnp.ndarray, tau_K: jnp.ndarray) -> jnp.ndarray:
+    return kappa * H * Psi * Omega_sync * tau_K
+
+
+def calculate_advanced_sigma(kappa: jnp.ndarray, H: jnp.ndarray, Psi: jnp.ndarray, Omega_sync: jnp.ndarray, tau_K: jnp.ndarray) -> jnp.ndarray:
+    """Deprecated: kappa*H*Psi*Omega_sync*tau_K, intended as the source of
+    zero_noise_extrapolation's sigma_at_base_noise (see this module's own
+    docs/api/healing.md), but its 5 inputs never had a defined provenance
+    in a ZNE context -- and Dense-Evolution-Discovery Experiment 35
+    (scripts/zne_healing_sigma_provenance.py) has since shown that even a
+    fully-designed input wouldn't matter: a permutation-test negative
+    control (real sigma vs. randomly shuffled sigma) performed
+    statistically identically, meaning the healing-adapted branch's
+    coefficient perturbation doesn't discriminate real signal from noise
+    at all. Kept for backward compatibility only (no known external
+    callers found in Dense-Evolution, Dense-Evolution-Discovery, or
+    Dense-Armor); will be removed in a future major version. This wrapper
+    is intentionally NOT @jax.jit-decorated (unlike the private core it
+    delegates to) so the warning fires on every call, not just once per
+    traced input shape."""
+    warnings.warn(
+        "calculate_advanced_sigma is deprecated: its output was never wired into "
+        "any real pipeline, and Dense-Evolution-Discovery Experiment 35 found the "
+        "one place it could have been used (zero_noise_extrapolation's healing "
+        "branch) does not discriminate real sigma from random noise anyway. "
+        "Will be removed in a future release.",
+        DeprecationWarning, stacklevel=2,
+    )
+    return _calculate_advanced_sigma_core(kappa, H, Psi, Omega_sync, tau_K)
+
+@jax.jit
+def calculate_phi_ab(state_A: jnp.ndarray, state_B: jnp.ndarray, ipg_vector: jnp.ndarray) -> jnp.ndarray:
+    """Computes the Phi_AB spatial alignment and coherence factor."""
+    semantic_change = state_B - state_A
+    norm_change = jnp.linalg.norm(semantic_change)
+    norm_ipg = jnp.linalg.norm(ipg_vector)
+
+    alignment = jnp.where(
+        (norm_change > 1e-12) & (norm_ipg > 1e-12),
+        # jnp.dot on complex arrays is the bilinear (non-conjugated) product
+        # and stays complex, which used to blow up jnp.clip below with
+        # "ValueError: Clip received a complex value". jnp.real(jnp.vdot(..))
+        # is the correct Hermitian-inner-product real part -- for real
+        # inputs it reduces exactly to jnp.dot (no behavior change for
+        # existing real-valued callers), and for complex inputs (e.g. a
+        # genuine statevector) it gives the real alignment value this
+        # function needs. Re(vdot(a,b)) == Re(vdot(b,a)) always, even
+        # though vdot(a,b) != vdot(b,a) in general (they're conjugates) --
+        # argument order doesn't matter here only because we take the real part.
+        jnp.real(jnp.vdot(semantic_change, ipg_vector)) / (norm_change * norm_ipg),
+        0.0
+    )
+    semantic_alignment = (alignment + 1.0) / 2.0
+
+    distance_A_B = jnp.linalg.norm(state_A - state_B)
+    coherence_component = 1.0 - (distance_A_B / GLOBAL_CONSTANTS['MAX_SEMANTIC_DISTANCE'])
+
+    phi_ab = (semantic_alignment * GLOBAL_CONSTANTS['WEIGHT_SEMANTIC']) + (coherence_component * GLOBAL_CONSTANTS['WEIGHT_COHERENCE'])
+    return jnp.clip(phi_ab, 0.0, 1.0)
+
+@jax.jit
+def calculate_vettore_dinamico(E_A: jnp.ndarray, E_B: jnp.ndarray, Phi_AB: jnp.ndarray) -> jnp.ndarray:
+    """Computes the Dynamic Vector (V_dinamic) as a differential logarithmic energy variation.
+
+    log(E_B / E_A) is a log-likelihood ratio -- the same elementary
+    quantity Kullback-Leibler divergence is built from (see this
+    module's docstring for the precise distinction: this is one
+    un-weighted log-ratio between two scalars, not a full KL divergence
+    over a probability distribution). Equivalently, the difference in
+    surprisal (-log E) between the two states."""
+    valid_inputs = (E_A > 1e-12) & (E_B > 1e-12)
+    ratio = jnp.where(valid_inputs, E_B / E_A, 1.0)
+    log_ratio_clamped = jnp.clip(jnp.log(ratio), -5.0, 5.0)
+    v_vita = GLOBAL_CONSTANTS['V_DINAMIC_K_COEFF'] * log_ratio_clamped * Phi_AB
+    return jnp.where(valid_inputs, v_vita, 0.0)
+
+@jax.jit
+def calculate_vettore_statico(v_dinamic_value: jnp.ndarray) -> jnp.ndarray:
+    """Computes the Static Vector tensorial-stasis indicator."""
+    is_growing = v_dinamic_value > GLOBAL_CONSTANTS['V_DINAMIC_MIN_EFFECTIVE_VALUE']
+    return GLOBAL_CONSTANTS['V_STATIC_K_PRIME_COEFF'] * (1.0 - jnp.where(is_growing, 1.0, 0.0))
+
+@jax.jit
+def calculate_delta_preemp(current_sigma: jnp.ndarray, target_sigma_ideal: float = 10.0) -> jnp.ndarray:
+    """Computes the predictive deviation Delta_Pre_emp normalized against the ideal eigenstate."""
+    safe_target = jnp.where(target_sigma_ideal <= 0.0, 1.0, target_sigma_ideal)
+    return jnp.abs(current_sigma - target_sigma_ideal) / safe_target
+
+@jax.jit
+def evaluate_phi_trigger(deterministic_dq_dt_a: jnp.ndarray) -> Tuple[jnp.ndarray, jnp.ndarray, jnp.ndarray]:
+    """Evaluates the Phi-Trigger state by computing the conditional damping coefficients."""
+    magnitude_change_a = jnp.abs(deterministic_dq_dt_a)
+    trigger_active = magnitude_change_a > GLOBAL_CONSTANTS['NON_STATIC_THRESHOLD_A']
+
+    lambda_step = jnp.where(trigger_active, 0.05, 0.05 + GLOBAL_CONSTANTS['DAMPING_BOOST_ON_STASIS'])
+    epsilon_dissip = jnp.where(trigger_active, GLOBAL_CONSTANTS['EPSILON_DISSIPATION_BASE'],
+                                GLOBAL_CONSTANTS['EPSILON_DISSIPATION_BASE'] + GLOBAL_CONSTANTS['DAMPING_BOOST_ON_STASIS'])
+
+    return jnp.where(trigger_active, 1.0, 0.0), lambda_step, epsilon_dissip
+
+@jax.jit
+def calculate_jax_reflection(coherence_values: jnp.ndarray, noise_levels: jnp.ndarray) -> Tuple[jnp.ndarray, jnp.ndarray, jnp.ndarray]:
+    """Performs spectral statistical aggregation (Zero-Drift) on the XLA runtime."""
+    n_coh = coherence_values.shape[0]
+    avg_coherence = jnp.where(n_coh > 0, jnp.mean(coherence_values), 0.0)
+    var_coherence = jnp.where(n_coh > 0, jnp.var(coherence_values), 0.0)
+
+    n_noise = noise_levels.shape[0]
+    avg_noise = jnp.where(n_noise > 0, jnp.mean(noise_levels), 0.0)
+
+    return avg_coherence, var_coherence, avg_noise
+
+# =====================================================================
+#  OPERATIONAL LAYER: LOGGING AND HISTORY TRACKING
+# =====================================================================
+
+class MemoryReflectionEngine:
+    def __init__(self):
+        self.memory: List[Dict[str, Any]] = []
+
+    def record_event(self, event_type: str, value: float, description: str = ""):
+        event = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "type": event_type,
+            "value": float(value),
+            "description": description
+        }
+        self.memory.append(event)
+
+    def reflect(self) -> Dict[str, Any]:
+        coherence_list = [e['value'] for e in self.memory if e['type'] == 'coherence']
+        interventions = [e for e in self.memory if e['type'] == 'intervention']
+        noise_list = [e['value'] for e in self.memory if e['type'] == 'noise']
+
+        j_coherence = jnp.array(coherence_list, dtype=jnp.float64) if coherence_list else jnp.array([], dtype=jnp.float64)
+        j_noise = jnp.array(noise_list, dtype=jnp.float64) if noise_list else jnp.array([], dtype=jnp.float64)
+
+        avg_coh, var_coh, avg_noise = calculate_jax_reflection(j_coherence, j_noise)
+
+        report = {
+            'average_coherence': float(avg_coh) if coherence_list else None,
+            'variance_coherence': float(var_coh) if coherence_list else None,
+            'interventions_count': len(interventions),
+            'average_noise': float(avg_noise) if noise_list else None,
+            'total_events': len(self.memory)
+        }
+        return report
+
+    def export_memory(self, filepath: str):
+        with open(filepath, 'w') as f:
+            json.dump(self.memory, f, indent=2)
+
+    def load_memory(self, filepath: str):
+        with open(filepath, 'r') as f:
+            self.memory = json.load(f)

dense_evolution/mitigation/kl_divergence.py

@@ -0,0 +1,93 @@
+"""Classical Kullback-Leibler divergence between probability distributions
+(Kullback, S. & Leibler, R.A., "On Information and Sufficiency", The
+Annals of Mathematical Statistics, 22(1), 79-86, 1951).
+
+D_KL(p||q) = sum_x p(x) * log2(p(x)/q(x)), the relative entropy of q from
+p, in bits (log2, matching the rest of this subpackage's convention --
+`sandwiched_renyi_divergence`/`magic_entropy` both use log2).
+
+Checked against the paper's own text directly (Section 2, eq. 2.2-2.3),
+not assumed from the textbook formula alone: what this module implements
+is what Kullback & Leibler call I(1:2), "the mean information for
+discrimination between H1 and H2" -- what the broader literature later
+popularized as "the KL divergence". Their OWN word "divergence",
+J(1,2) = I(1:2) + I(2:1) (eq. 2.9), names the symmetrized sum of both
+directions instead -- deliberately not implemented here, since it would
+duplicate the Jensen-Shannon divergence this codebase already uses
+(`mps.py`'s bond-dimension search, `zne.py`'s predictive ZNE), which is
+bounded and better-behaved at disjoint supports.
+
+Distinct in kind from `sandwiched_renyi_divergence(rho, sigma, alpha=1.0)`,
+which reduces to the QUANTUM relative entropy Tr[rho(log rho - log sigma)]
+between density MATRICES via matrix logarithms -- this module implements
+the simpler classical case directly over probability VECTORS (e.g. a
+measurement-outcome distribution |psi|^2, or any other normalized
+histogram), with no eigendecomposition needed.
+
+Originated from an honest gap flagged in this subpackage's own healing.py
+docstring: calculate_vettore_dinamico's core term, log(E_B/E_A), is a
+single un-weighted log-likelihood ratio between two scalars -- the same
+elementary quantity this divergence is built from, but not this
+divergence itself. Built and validated in Dense-Evolution-Discovery,
+Experiment 32
+(https://tatopenn-cell.github.io/Dense-Evolution-Discovery/kullback_leibler_divergence/):
+against an independent scipy.stats.entropy reference (1e-9 bits across 20
+random trials), Gibbs' inequality (D_KL >= 0, 200 random pairs, never
+negative), a genuine support-violation case (+inf, not a finite wrong
+number), and a real measurement-distribution application confirming this
+is not a trivial rescaling of healing.py's existing scalar signal.
+
+Additive, not a replacement for the already-validated healing pipeline.
+"""
+import jax
+import jax.numpy as jnp
+
+__all__ = ["kl_divergence", "kl_divergence_jit"]
+
+_EPS = 1e-12
+
+
+def _kl_divergence_core(p: jnp.ndarray, q: jnp.ndarray) -> jnp.ndarray:
+    # 0 * log(0/q) = 0 by the standard x*log(x) -> 0 (x -> 0+) convention
+    # (Cover & Thomas, "Elements of Information Theory", 2nd ed., section
+    # 2.1) -- terms where p is (numerically) zero contribute nothing,
+    # regardless of q there.
+    p_is_zero = p < _EPS
+
+    # A term is only a genuine support violation when p(x) > 0 but
+    # q(x) == 0: p has mass where q has none, so no finite log-ratio can
+    # account for it -- D_KL(p||q) is +inf by definition, not a numerical
+    # artifact to clamp away (the same lesson already learned the hard way
+    # for sandwiched_renyi_divergence's alpha>1 case -- see renyi.py).
+    q_is_zero = q < _EPS
+    is_support_violation = jnp.any((~p_is_zero) & q_is_zero)
+
+    safe_p = jnp.where(p_is_zero, 1.0, p)
+    safe_q = jnp.where(q_is_zero, 1.0, q)
+    terms = jnp.where(p_is_zero, 0.0, safe_p * jnp.log2(safe_p / safe_q))
+    finite_result = jnp.sum(terms)
+    return jnp.where(is_support_violation, jnp.inf, finite_result)
+
+
+def kl_divergence(p: jnp.ndarray, q: jnp.ndarray) -> float:
+    """Classical Kullback-Leibler divergence D_KL(p||q), in bits.
+
+    `p`, `q` are 1-D real, non-negative probability vectors of the same
+    length, each summing to 1 (not validated here -- callers pass in a
+    normalized distribution, e.g. `jnp.abs(psi) ** 2` for a statevector's
+    measurement-outcome probabilities). Not symmetric: D_KL(p||q) !=
+    D_KL(q||p) in general.
+
+    Zero iff p == q (Gibbs' inequality: D_KL(p||q) >= 0 always, with
+    equality only at p == q). Returns `+inf` when p has support where q
+    does not (p(x) > 0, q(x) == 0 for some x) -- the correct value, not an
+    edge case to avoid; see the module docstring.
+    """
+    p = jnp.asarray(p, dtype=jnp.float64)
+    q = jnp.asarray(q, dtype=jnp.float64)
+    return float(_kl_divergence_core(p, q))
+
+
+kl_divergence_jit = jax.jit(_kl_divergence_core)
+"""`jax.jit`-compiled entry point for `kl_divergence`. `p`/`q` must already
+be `float64` arrays. Returns a jnp scalar, not a Python `float`."""

dense_evolution/mitigation/magic_entropy.py

@@ -0,0 +1,163 @@
+"""Magic entropy: a single-qubit density-matrix diagnostic built from the
+3-fold self-convolution "Key Unitary" construction (Bu, Gu, Jaffe,
+"Stabilizer testing and magic entropy", arXiv:2306.09292, Definitions 7-8).
+
+Originated from a Colab proposal for a pairwise "Quantum Ruzsa Divergence"
+(following Bu, Gu, Jaffe, "A convolutional quantum Ruzsa divergence and
+its applications", arXiv:2401.14385) that turned out to have no valid
+definition for qubits: that paper's pairwise convolution needs
+s^2+t^2=1 mod d, which has no solution at d=2. The companion paper above
+does not patch this with a qubit-specific pairwise formula -- it defines
+a structurally different, minimum-3-input "Key Unitary" convolution (K
+quantum registers, K must be ODD, K>=3; there is no K=2 case). For qubits
+the smallest valid object is therefore the 3-fold SELF-convolution of one
+state with itself, boxtimes_3(rho,rho,rho), and the entropy of its
+reduced output register is what the paper calls "magic entropy": zero
+for stabilizer states, positive for non-stabilizer ("magic") states (the
+paper's Examples 32/33).
+
+Validated end-to-end in Dense-Evolution-Discovery, Experiment 30
+(https://tatopenn-cell.github.io/Dense-Evolution-Discovery/quantum_ruzsa_magic_entropy/):
+the Key Unitary circuit was checked basis-state by basis-state against
+the paper's own Lemma 9 combinatorial identity; magic_entropy was
+checked against all six single-qubit stabilizer states (~0, max observed
+4e-11) and the two standard magic states T and H (0.811 bits, matching
+each other exactly as expected by symmetry); and it was used as a noise
+diagnostic that is qualitatively distinct from uhlmann_fidelity and the
+sandwiched Renyi divergence (see renyi.py in this same subpackage) --
+under amplitude damping it is non-monotonic (rises then returns to
+exactly 0, since the p=1 fixed point |0> is a stabilizer state), unlike
+either of those two, which change monotonically over the same sweep.
+
+Restricted to SINGLE-QUBIT density matrices (2x2) -- the Key Unitary here
+is built for n=1-qubit registers specifically; a multi-qubit
+generalization would need a larger Key Unitary circuit (n-qubit
+registers, Definition 7 in general) not implemented here.
+
+A shadow-measurement-based estimator for this same quantity, using
+randomized measurement snapshots instead of the exact density matrix, is
+promoted alongside this module in magic_entropy_shadows.py -- see that
+module for why it has its own API shape (measurement snapshots in, not a
+density matrix) rather than a function alongside this one.
+"""
+import functools
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+
+__all__ = ["magic_entropy", "magic_entropy_jit"]
+
+
+def _cnot_matrix(control: int, target: int, n: int = 3) -> np.ndarray:
+    """Permutation matrix for a CNOT(control->target) gate on n qubits,
+    computational basis ordered as |q0 q1 ... q(n-1)> (this package's
+    MSB-first convention, matching dense_evolution.physics.entropy)."""
+    dim = 2 ** n
+    mat = np.zeros((dim, dim))
+    for i in range(dim):
+        bits = [(i >> (n - 1 - k)) & 1 for k in range(n)]
+        if bits[control]:
+            bits[target] ^= 1
+        j = 0
+        for bit in bits:
+            j = (j << 1) | bit
+        mat[j, i] = 1.0
+    return mat
+
+
+def _build_key_unitary_k3() -> jnp.ndarray:
+    """Definition 7 (Bu, Gu, Jaffe, arXiv:2306.09292, p.6), specialized to
+    K=3 registers of n=1 qubit each -- the minimum valid case (K must be
+    odd). U = (CNOT_{2->1} CNOT_{3->1}) (CNOT_{1->2} CNOT_{1->3}): layer 1
+    fans register 1 into registers 2,3; layer 2 XORs registers 2,3 (their
+    post-layer-1 values) back into register 1. Verified basis-state by
+    basis-state against the paper's own Lemma 9 identity in
+    Dense-Evolution-Discovery's tests/test_quantum_ruzsa_magic_entropy.py."""
+    layer1 = _cnot_matrix(0, 2) @ _cnot_matrix(0, 1)
+    layer2 = _cnot_matrix(2, 0) @ _cnot_matrix(1, 0)
+    return jnp.array(layer2 @ layer1, dtype=jnp.complex128)
+
+
+@functools.lru_cache(maxsize=1)
+def _key_unitary_k3() -> jnp.ndarray:
+    """Cached, lazily-built K3 Key Unitary -- NOT a bare module-level
+    constant (that used to be `_KEY_UNITARY_K3 = _build_key_unitary_k3()`,
+    evaluated at import time). A bare module-level `jnp.array(...,
+    dtype=jnp.complex128)` runs before anything has had a chance to call
+    `dense_evolution.config.ensure_x64()` (only DenseSVSimulator,
+    QuantumHardwareRegistry and circuit_to_energy_fn do that, and only
+    the first time one of them is constructed) -- so on a bare `import
+    dense_evolution`, jax_enable_x64 is still False at this point, and
+    JAX both silently truncates the requested complex128 to complex64
+    AND raises a UserWarning about it, on every fresh interpreter
+    (verified directly: 3-4 near-identical warnings fire on a plain
+    `import dense_evolution as de`, one per such module-level constant
+    across this file and magic_entropy_shadows.py, before this fix).
+    Wrapping it in a cached lazy getter defers construction to first
+    actual use (typically after some simulator has already called
+    ensure_x64()), which both silences the spurious warning in the
+    common case and avoids permanently baking in whatever precision
+    happened to be active at import time -- exactly the "lazy, not an
+    import-time side effect" policy dense_evolution.config already
+    documents for the rest of the package, just not yet applied here."""
+    return _build_key_unitary_k3()
+
+
+def _self_convolve_3_core(rho: jnp.ndarray) -> jnp.ndarray:
+    """boxtimes_3(rho,rho,rho) = Tr_{2,3}[V (rho (x) rho (x) rho) V^dagger]
+    (Definition 8). `rho` may be pure or mixed. Not built on
+    `dense_evolution.physics.entropy.partial_trace` -- that helper is
+    pure-statevector-only, and this needs to trace out a general (possibly
+    mixed) 3-qubit density matrix built from a possibly-mixed input."""
+    key_unitary = _key_unitary_k3()
+    rho_full = jnp.kron(jnp.kron(rho, rho), rho)
+    evolved = key_unitary @ rho_full @ jnp.conj(key_unitary).T
+    tensor = evolved.reshape(2, 2, 2, 2, 2, 2)
+    return jnp.einsum("ijkljk->il", tensor)
+
+
+def _magic_entropy_core(rho: jnp.ndarray, eps: float = 1e-12) -> jnp.ndarray:
+    reduced = _self_convolve_3_core(rho)
+    ev = jnp.linalg.eigvalsh(reduced)
+    # Clip then renormalize (same order magic_entropy_from_shadows uses),
+    # not clip alone: an unclipped-then-unnormalized eigenvalue sum that
+    # has drifted off 1 (numerical trace error in `reduced`) would
+    # otherwise get silently truncated at the eps/1.0 clip bounds instead
+    # of corrected -- masking the drift rather than fixing it.
+    safe_ev = jnp.clip(jnp.real(ev), eps, None)
+    safe_ev = safe_ev / jnp.sum(safe_ev)
+    return -jnp.sum(safe_ev * jnp.log2(safe_ev))
+
+
+def magic_entropy(rho: jnp.ndarray) -> float:
+    """Magic entropy of a single-qubit density matrix `rho` (2x2), in bits
+    (log2) -- NOTE this differs from
+    `dense_evolution.physics.entropy.von_neumann_entropy`'s natural-log
+    (nats) convention; kept as log2 here to match both the source paper's
+    own convention and the values already published in
+    Dense-Evolution-Discovery's Experiment 30.
+
+    Zero for every single-qubit stabilizer state (|0>, |1>, |+>, |->,
+    |+i>, |-i>), positive for non-stabilizer ("magic") states -- e.g. the
+    T-state and H-state both give 0.811 bits.
+
+    Differentiable through `jax.grad`, including at stabilizer states
+    where the reduced matrix's eigenvalues are exactly degenerate (e.g.
+    the fully mixed state I/2 gives eigenvalues [0.5, 0.5]): unlike
+    `uhlmann_fidelity`, which needs a custom `_eigh_degenerate_safe` JVP
+    rule because it reconstructs eigenVECTORS (ill-defined in a
+    degenerate eigenspace), this function only ever needs eigenVALUES
+    (`jnp.linalg.eigvalsh`, no eigenvectors), whose gradient is
+    well-defined even at exact degeneracies -- confirmed directly:
+    `jax.grad(magic_entropy)` is finite (no NaN) at both the fully mixed
+    state and a magic state.
+    """
+    rho = jnp.asarray(rho, dtype=jnp.complex128)
+    return float(_magic_entropy_core(rho))
+
+
+magic_entropy_jit = jax.jit(_magic_entropy_core)
+"""`jax.jit`-compiled entry point for `magic_entropy`. `rho` must already
+be `complex128`. Returns a jnp scalar, not a Python `float` -- call
+`float(...)` yourself if you need one outside a jitted context."""