dense-evolution 8.3.0__py3-none-win_amd64.whl

dense_evolution/noise/kraus_channels.py

@@ -0,0 +1,285 @@
+import functools
+import os
+import time
+from typing import Optional, List, Dict, Any
+import numpy as np
+
+import jax
+import jax.numpy as jnp
+HAS_JAX = True
+
+from .kraus import ideal, depolarizing, bitflip, phaseflip, amplitude_damping, combined
+
+__all__ = ["NoiseModel"]
+
+_CHANNELS = {
+    'ideal': ideal,
+    'depolarizing': depolarizing,
+    'bitflip': bitflip,
+    'phaseflip': phaseflip,
+    'amplitude_damping': amplitude_damping,
+    'combined': combined,
+}
+
+
+def _fresh_rng() -> np.random.Generator:
+    """
+    Create a hardware-entropy-seeded RNG.
+    Combines os.urandom (CSPRNG) with a high-resolution nanosecond counter
+    so two calls within the same microsecond still differ.
+    """
+    entropy_bytes = os.urandom(8)
+    entropy_int   = int.from_bytes(entropy_bytes, byteorder='big')
+    ns_counter    = time.perf_counter_ns() & 0xFFFF_FFFF_FFFF_FFFF
+    seed          = (entropy_int ^ ns_counter) & 0xFFFF_FFFF_FFFF_FFFF
+    return np.random.default_rng(seed)
+
+
+@functools.lru_cache(maxsize=None)
+def _qubit_index_pairs(dim: int, q: int):
+    """
+    Return (idx_0, idx_1) — two integer arrays of length dim/2 — where
+    idx_0[i] has bit q == 0 and idx_1[i] = idx_0[i] | (1 << q).
+
+    Cached on (dim, q) (prog.txt point 5a): apply_to_sv recomputes these
+    two O(dim/2) NumPy arrays from scratch on every call, once per qubit
+    in `target_qubits` -- and apply_to_sv itself runs once per shot in a
+    Monte Carlo ZNE loop, so the same (dim, q) pair gets rebuilt
+    thousands of times for a fixed circuit size. Both arguments are
+    always plain Python ints (dim = len(sv), a concrete value even for a
+    traced JAX sv; q comes from a plain int qubit list), so caching is
+    safe -- the returned arrays are read-only outputs of channel.apply,
+    never mutated in place.
+    """
+    step   = 1 << q
+    all_i  = np.arange(dim, dtype=np.intp)
+    idx_0  = all_i[(all_i & step) == 0]          # shape: (dim//2,)
+    idx_1  = idx_0 | step                          # shape: (dim//2,)
+    return idx_0, idx_1
+
+
+class NoiseModel:
+    """
+    Stochastic single-qubit Kraus channels applied directly to a statevector.
+    Each channel is a separate, importable module under `dense_evolution.
+    noise.kraus` (`dense_evolution.noise.kraus.depolarizing`, etc.) --
+    this class is the shared dispatcher: RNG/key setup, the per-qubit
+    loop, and final normalisation, common to every channel.
+
+    All channels are mathematically correct Kraus maps:
+    - trace is preserved (normalisation enforced at the end)
+    - phaseflip applies Z with probability p per qubit (non-deterministic)
+    - amplitude_damping applies the correct K0/K1 Kraus operators
+    - combined is a true worst-case NISQ mixture of all three Pauli errors
+      plus amplitude damping
+
+    Supported models
+    ----------------
+    'ideal'            identity — no modification
+    'depolarizing'     {√(1-p)I, √(p/3)X, √(p/3)Y, √(p/3)Z}
+    'bitflip'          {√(1-p)I, √p·X}
+    'phaseflip'        {√(1-p)I, √p·Z}    ← was broken, now fixed
+    'amplitude_damping'{K0=diag(1,√(1-γ)), K1=[[0,√γ],[0,0]]}
+    'combined'         depolarizing(p/2) + amplitude_damping(p/3), renormalised
+
+    Every channel draws one fire/no-fire decision per qubit per shot
+    (plus one Pauli choice for depolarizing/combined's depolarizing
+    sub-step), applied identically across the whole statevector -- the
+    same single-Pauli-per-qubit-per-shot convention STIM's
+    DEPOLARIZE1(p) uses. Prior to v8.1.57, every channel instead drew
+    2**(n-1) INDEPENDENT decisions per qubit per shot, one per amplitude
+    pair (i.e. one per branch of the other n-1 qubits) -- inert on a
+    product state, but on an entangled state it over-decohered any
+    coherence-sensitive (off-diagonal) observable, up to hundreds of
+    sigma vs the exact density-matrix Kraus-sum result on test cases
+    (e.g. per-branch sampling dropped a measured value from 1.0 to 0.31
+    at p=0.15 on one such test -- see the v8.1.57 changelog entry for
+    the full reproduction).
+    """
+
+    MODELS = ['ideal', 'depolarizing', 'bitflip', 'phaseflip',
+              'amplitude_damping', 'combined']
+
+    @staticmethod
+    def apply_to_sv(
+        sv:       np.ndarray,
+        n:        int,
+        model:    str,
+        p:        float,
+        rng:      Optional[np.random.Generator] = None,
+        qubits:   Optional[List[int]] = None,
+        jax_key:  Optional[Any] = None,
+    ) -> np.ndarray:
+        """
+        Apply a stochastic Kraus channel to statevector *sv* in-place
+        (numpy path) or via functional updates (JAX path).
+
+        Parameters
+        ----------
+        sv      : complex statevector of length 2**n
+        n       : number of qubits
+        model   : one of NoiseModel.MODELS
+        p       : error probability (or damping rate γ for amplitude_damping)
+        rng     : optional pre-seeded numpy Generator. Used directly when
+                  *sv* is a NumPy array. When *sv* is a JAX array, `rng`
+                  used to be silently ignored in favor of `jax_key` (or a
+                  non-reproducible OS-entropy key if that was also None
+                  -- issue #7); it is now used to *derive* a reproducible
+                  jax_key (`rng.integers(...)` seeds `jax.random.PRNGKey`)
+                  whenever `jax_key` isn't given explicitly, so seeding
+                  `rng` has the effect a caller expects on both array
+                  types instead of only on one of them.
+        qubits  : subset of qubits to apply the channel to; defaults to all
+        jax_key : optional JAX PRNGKey, only meaningful when *sv* is a JAX
+                  array. Takes precedence over `rng` when both are given
+                  (explicit key beats a derived one). Created from OS
+                  entropy if neither `jax_key` nor `rng` is given.
+
+        Returns
+        -------
+        Normalised statevector (same array type as input).
+
+        Examples
+        --------
+        A real quantum computer is never perfect -- every gate has some chance of
+        error. Once you have a statevector from running your own QASM circuit (the
+        same circuit as the getting-started example), this function is how you find
+        out what a noisy device would have actually given you instead.
+
+        Start from the circuit and statevector you already have:
+
+        >>> import numpy as np
+        >>> import dense_evolution as de
+        >>> qasm = 'OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; barrier q; cx q[0],q[1]; measure q -> c;'
+        >>> circuit = de.QASMParser().parse(qasm)
+        >>> sim = de.DenseSVSimulator(2)
+        >>> sim.run_circuit(circuit.to_tuples())
+        >>> sv = np.asarray(sim.get_statevector())
+
+        (the `barrier` is parsed and ignored -- it never becomes a gate tuple, so it
+        has no effect on the statevector, only on how the circuit reads.)
+
+        Call `NoiseModel.apply_to_sv` on that same statevector, telling it the
+        qubit count, which error model to simulate, and how strong it is:
+
+        >>> from dense_evolution.noise import NoiseModel
+        >>> rng = np.random.default_rng(0)
+        >>> sv_noisy = NoiseModel.apply_to_sv(sv.copy(), 2, 'depolarizing', 0.1, rng=rng)
+        >>> round(float(np.vdot(sv_noisy, sv_noisy).real), 4)  # still a valid, normalised state
+        1.0
+
+        `'depolarizing'` above is one of six models; pick any other one the same way,
+        by name:
+
+        >>> NoiseModel.MODELS
+        ['ideal', 'depolarizing', 'bitflip', 'phaseflip', 'amplitude_damping', 'combined']
+
+        `p` is that model's error probability (or damping rate for
+        `'amplitude_damping'`) -- 0.1 above means each qubit has a 10% chance of a
+        random Pauli error per call. Run it many times and average (see
+        [Density-matrix ZNE healing](../examples.md#density-matrix-zne-healing))
+        to see what a real noisy device's *typical* output looks like, not just one
+        random draw.
+        """
+        if model == 'ideal':
+            return sv
+        try:
+            if p <= 0.0:
+                return sv
+        except jax.errors.TracerBoolConversionError:
+            # p is a traced value (e.g. flowing through jax.jit/vmap/grad
+            # as a NoiseSpec pytree leaf) -- can't early-exit on a Python
+            # bool of it. Falling through is still correct: every channel
+            # below already reduces to a no-op at p=0 (`fire = r < p` is
+            # always False), this skips only the eager-mode optimization,
+            # not correctness.
+            pass
+
+        channel = _CHANNELS[model]
+        is_jax = HAS_JAX and isinstance(sv, jnp.ndarray)
+        dim    = len(sv)
+
+        # ── RNG initialisation ────────────────────────────────────────
+        if is_jax:
+            if jax_key is not None:
+                key = jax_key
+            elif rng is not None:
+                # Derive a reproducible JAX key from the caller's seeded
+                # NumPy generator instead of silently ignoring it -- each
+                # call advances `rng`'s state, so a fresh, identically-
+                # seeded `rng` reproduces the exact same sequence of keys
+                # across separate runs (same guarantee the NumPy path
+                # already gives).
+                key = jax.random.PRNGKey(int(rng.integers(0, 2**32 - 1)))
+            else:
+                seed_bytes = os.urandom(4)
+                jax_seed   = int.from_bytes(seed_bytes, byteorder='big')
+                jax_seed  ^= time.perf_counter_ns() & 0xFFFF_FFFF
+                key = jax.random.PRNGKey(jax_seed)
+        else:
+            key = None
+            if rng is None:
+                rng = _fresh_rng()
+
+        target_qubits = qubits if qubits is not None else list(range(n))
+        sv_out = sv  # JAX: functional; NumPy: will be modified in-place copy
+
+        if not is_jax:
+            sv_out = sv.copy()  # never mutate the caller's array
+
+        for q in target_qubits:
+            idx_0, idx_1 = _qubit_index_pairs(dim, q)
+            sv_out, key = channel.apply(sv_out, idx_0, idx_1, p, rng, key, is_jax)
+
+        # ── normalise ─────────────────────────────────────────────────
+        if is_jax:
+            norm = jnp.linalg.norm(sv_out)
+            return sv_out / (norm + 1e-15)
+        else:
+            norm = np.linalg.norm(sv_out)
+            return sv_out / (norm + 1e-15)
+
+    @staticmethod
+    def kraus_description(model: str) -> Dict:
+        """Human-readable Kraus-operator formula and physical meaning for
+        one of `NoiseModel.MODELS`.
+
+        Examples
+        --------
+        >>> from dense_evolution.noise import NoiseModel
+        >>> NoiseModel.kraus_description('bitflip')['physical']
+        'Bit flip σ_x with probability p'
+        """
+        desc = {
+            'ideal': {
+                'kraus': 1,
+                'formula': 'K₀ = I',
+                'physical': 'No noise',
+            },
+            'depolarizing': {
+                'kraus': 4,
+                'formula': 'K₀=√(1-p)I  K₁=√(p/3)X  K₂=√(p/3)Y  K₃=√(p/3)Z',
+                'physical': 'Isotropic Pauli error — equiprobable X, Y, Z',
+            },
+            'bitflip': {
+                'kraus': 2,
+                'formula': 'K₀=√(1-p)I  K₁=√p·X',
+                'physical': 'Bit flip σ_x with probability p',
+            },
+            'phaseflip': {
+                'kraus': 2,
+                'formula': 'K₀=√(1-p)I  K₁=√p·Z',
+                'physical': 'Pure dephasing σ_z with probability p',
+            },
+            'amplitude_damping': {
+                'kraus': 2,
+                'formula': 'K₀=diag(1,√(1-γ))  K₁=[[0,√γ],[0,0]]',
+                'physical': 'T₁ energy relaxation |1⟩→|0⟩ with rate γ',
+            },
+            'combined': {
+                'kraus': 6,
+                'formula': 'Depolarizing(p/2) ∘ AmplitudeDamping(p/3)',
+                'physical': 'Worst-case NISQ: dephasing + relaxation',
+            },
+        }
+        return desc.get(model, desc['ideal'])

dense_evolution/noise/oscillating.py

@@ -0,0 +1,32 @@
+"""A noise strength that oscillates instead of scaling smoothly/linearly
+-- for stress-testing mitigation techniques whose extrapolation assumes a
+smooth noise-vs-scale relationship."""
+import jax.numpy as jnp
+
+__all__ = ["oscillating_p_eff"]
+
+
+def oscillating_p_eff(base_p: float, factor: float, freq: float, amp: float) -> jnp.ndarray:
+    """Effective noise probability that oscillates around `base_p` as a
+    function of `factor` (e.g. a ZNE noise-scale factor), instead of
+    scaling smoothly with it: `base_p * (1 + amp * sin(factor * pi /
+    freq))`, clipped to `[0.01, 0.5]` so it always stays a valid
+    probability.
+
+    Promoted from Dense-Evolution-Discovery's jsd_zne_oscillating_noise.py,
+    where it was used to build a noise-vs-scale relationship deliberately
+    NOT smooth/monotonic, to stress-test
+    `dense_evolution.mitigation.jsd_predictive_zne_density_matrix` against
+    noise models where plain Richardson extrapolation's smoothness
+    assumption breaks down.
+
+    Examples
+    --------
+    >>> from dense_evolution.noise import oscillating_p_eff
+    >>> round(float(oscillating_p_eff(base_p=0.1, factor=0.0, freq=2.0, amp=0.5)), 4)
+    0.1
+    >>> round(float(oscillating_p_eff(base_p=0.1, factor=1.0, freq=2.0, amp=0.5)), 4)
+    0.15
+    """
+    p = base_p * (1.0 + amp * jnp.sin(factor * jnp.pi / freq))
+    return jnp.clip(p, 0.01, 0.5)

dense_evolution/noise/pink.py

@@ -0,0 +1,80 @@
+"""1/f ("pink") noise: a noise-strength trace with a power-law power
+spectral density, S(f) ~ 1/f^alpha, instead of the flat (white) or
+purely time-local (oscillating, burst) profiles this package's other
+generators produce -- the dominant real decoherence source (flux noise,
+charge noise) in superconducting qubits."""
+import jax
+import jax.numpy as jnp
+
+__all__ = ["pink_noise_p_eff"]
+
+
+def pink_noise_p_eff(base_p: float, n_samples: int, key, alpha: float = 1.0, amp: float = 0.5) -> jnp.ndarray:
+    """Effective noise probability trace of length `n_samples` fluctuating
+    around `base_p` with a 1/f^alpha power spectrum (`alpha=1.0` is the
+    real, standard "pink"/flicker-noise case; other values interpolate
+    toward white noise, `alpha=0`, or Brownian noise, `alpha=2`), instead
+    of `oscillating_p_eff`'s single deterministic frequency or
+    `cosmic_ray_burst_profile`'s one-shot deterministic event -- for
+    stress-testing mitigation techniques against the actual dominant
+    decoherence mechanism (1/f flux/charge noise) in real superconducting
+    hardware, not just synthetic worst cases.
+
+    Generated by the spectral-synthesis method of Timmer & Koenig (1995,
+    "On generating power law noise", Astronomy and Astrophysics 300, 707):
+    both the amplitude and the phase of each Fourier component are drawn
+    randomly (independent real/imaginary Gaussian draws, giving the
+    correct chi-squared-distributed power per bin, not just the correct
+    mean spectrum), scaled by `frequency ** (-alpha / 2)` so the power
+    spectrum scales as `frequency ** (-alpha)`, then inverse-transformed
+    to the time domain -- the standard algorithm for this exact problem,
+    not a bespoke construction. The zero-frequency (DC) component is
+    fixed to exactly 0, so the trace has zero mean before rescaling.
+    Verified during development: the fitted log-log power-spectrum slope
+    over 30 independent realizations at `alpha=1.0` is -0.996, matching
+    the expected -1 to within numerical/finite-sample tolerance.
+
+    The resulting zero-mean, unit-variance trace is rescaled to
+    `base_p * (1 + amp * trace)` and clipped to `[0.01, 0.5]`, the same
+    valid-probability range `oscillating_p_eff` uses, so it can be fed
+    directly wherever a per-trial or per-timestep `p` is expected.
+
+    Parameters
+    ----------
+    base_p : float
+        Center noise probability the trace fluctuates around.
+    n_samples : int
+        Length of the trace (e.g. one value per Monte Carlo trial, or per
+        time step of a trajectory).
+    key : jax.random.PRNGKey
+        Random key; two independent draws are taken from it internally
+        (real and imaginary Fourier-amplitude parts).
+    alpha : float
+        Spectral exponent: power spectral density ~ `1/frequency**alpha`.
+        `1.0` (default) is real 1/f/pink/flicker noise.
+    amp : float
+        Fractional modulation depth around `base_p`, same role as in
+        `oscillating_p_eff`.
+
+    Examples
+    --------
+    >>> import jax
+    >>> from dense_evolution.noise import pink_noise_p_eff
+    >>> trace = pink_noise_p_eff(0.05, 256, jax.random.PRNGKey(0))
+    >>> trace.shape
+    (256,)
+    >>> bool((trace >= 0.01).all() and (trace <= 0.5).all())
+    True
+    """
+    freqs = jnp.fft.rfftfreq(n_samples)
+    freqs = freqs.at[0].set(freqs[1])  # avoid a 1/0 singularity at DC; DC amplitude is zeroed below anyway
+    key_re, key_im = jax.random.split(key)
+    real_part = jax.random.normal(key_re, shape=freqs.shape)
+    imag_part = jax.random.normal(key_im, shape=freqs.shape)
+    scale = freqs ** (-alpha / 2.0)
+    spectrum = (real_part + 1j * imag_part) * scale
+    spectrum = spectrum.at[0].set(0.0)
+    trace = jnp.fft.irfft(spectrum, n=n_samples)
+    trace = (trace - jnp.mean(trace)) / jnp.std(trace)
+    p = base_p * (1.0 + amp * trace)
+    return jnp.clip(p, 0.01, 0.5)

dense_evolution/observables.py

@@ -0,0 +1,11 @@
+"""Backward-compatibility shim -- the real implementation moved to
+dense_evolution.physics.observables as part of the Phase 2 subpackage split
+(see prog.txt). Kept so `from dense_evolution.observables import pauli_expectation, pauli_sum_expectation, pauli_hamiltonian_to_matrix`
+(used by external consumers, e.g. Dense-Evolution-Discovery) keeps working
+unchanged. Import from dense_evolution.physics.observables directly in new code.
+"""
+from dense_evolution.physics.observables import (
+    pauli_expectation, pauli_sum_expectation, pauli_hamiltonian_to_matrix, pauli_sum_matvec,
+)
+
+__all__ = ['pauli_expectation', 'pauli_sum_expectation', 'pauli_hamiltonian_to_matrix', 'pauli_sum_matvec']

dense_evolution/parser.py

@@ -0,0 +1,9 @@
+"""Backward-compatibility shim -- the real implementation moved to
+dense_evolution.circuits.parser as part of the Phase 2 subpackage split
+(see prog.txt). Kept so `from dense_evolution.parser import QASMParser`
+(used by external consumers, e.g. Dense-Evolution-Discovery) keeps working
+unchanged. Import from dense_evolution.circuits.parser directly in new code.
+"""
+from dense_evolution.circuits.parser import QASMParser, QASMCircuit
+
+__all__ = ['QASMParser', 'QASMCircuit']

dense_evolution/physics/__init__.py

@@ -0,0 +1,27 @@
+"""Physics subpackage: state preparation, observables, entropy, fermions, QEC."""
+from .states import ghz_state
+from .observables import (pauli_expectation, pauli_sum_expectation, pauli_hamiltonian_to_matrix,
+                           pauli_sum_matvec, multiply_pauli_terms,
+                           pauli_sum_matvec_jax, pauli_sum_expectation_jax, PauliSumOperator)
+from .entropy import partial_trace, von_neumann_entropy, mutual_information, central_charge
+from .fermions import majorana_pauli_terms, total_parity_operator, hubbard_hamiltonian_pauli_terms, square_lattice_edges
+from .qec import (pauli_commutes, compute_syndrome, erasure_aware_decode, pymatching_decode,
+                   blind_minimum_weight_decode, decode_with_erasure_fallback,
+                   counts_in_intervals_dimension, nearest_coset_decode, erasure_ml_decode,
+                   peeling_decode, union_find_decode, matching_erasure_decode,
+                   estimate_edge_probabilities_from_detection_events)
+from .spectral import has_exact_degeneracy, matrix_function_eigh, spectral_evolve
+
+__all__ = [
+    "ghz_state",
+    "pauli_expectation", "pauli_sum_expectation", "pauli_hamiltonian_to_matrix", "pauli_sum_matvec",
+    "multiply_pauli_terms",
+    "pauli_sum_matvec_jax", "pauli_sum_expectation_jax", "PauliSumOperator",
+    "partial_trace", "von_neumann_entropy", "mutual_information", "central_charge",
+    "majorana_pauli_terms", "total_parity_operator", "hubbard_hamiltonian_pauli_terms", "square_lattice_edges",
+    "pauli_commutes", "compute_syndrome", "erasure_aware_decode", "pymatching_decode", "blind_minimum_weight_decode",
+    "decode_with_erasure_fallback", "counts_in_intervals_dimension", "nearest_coset_decode",
+    "erasure_ml_decode", "peeling_decode", "union_find_decode", "matching_erasure_decode",
+    "estimate_edge_probabilities_from_detection_events",
+    "has_exact_degeneracy", "matrix_function_eigh", "spectral_evolve",
+]

dense_evolution/physics/entropy.py

@@ -0,0 +1,161 @@
+"""
+Multi-qubit partial trace, von Neumann entropy, and mutual information.
+
+Nothing like this existed anywhere in the package before: the only prior
+partial trace (dashboard_core/state_visuals.py's private
+`_reduced_density_matrix`) is single-qubit-only and uses the *opposite*,
+little-endian convention (qubit 0 = least significant bit). Everything
+here uses this package's own convention instead, matching
+dense_evolution.observables/pauli_hamiltonian_to_matrix: qubit 0 is the
+*most* significant bit of the basis-state index. Do not mix the two --
+reusing dashboard_core's helper here would silently transpose which
+qubits get traced out.
+
+Originated in research/wormhole_syk.py (a traversable-wormhole-inspired
+quantum teleportation reproduction) -- promoted here because these are
+generic quantum-information utilities, not specific to that experiment.
+Any state can have a subsystem's reduced density matrix, entropy, or the
+mutual information between two subsystems computed with these three
+functions; the wormhole work needed all three because the physically
+meaningful readout there (a message injected into one system showing up
+correlated with a reference qubit) is *not* visible in any single-qubit
+expectation value -- see mutual_information's docstring.
+"""
+
+import numpy as np
+
+__all__ = ['partial_trace', 'von_neumann_entropy', 'mutual_information', 'central_charge']
+
+
+def partial_trace(state, n_qubits, keep_qubits):
+    """Reduced density matrix on `keep_qubits`, tracing out the rest.
+
+    MSB-first (qubit 0 = most significant bit), this package's own
+    convention everywhere else -- NOT the same as dashboard_core.
+    state_visuals._reduced_density_matrix, which is deliberately
+    little-endian (Qiskit's convention) for its own Bloch-sphere/Q-sphere
+    display consumers. Two genuinely different conventions for two
+    different consumers, not an accidental divergence.
+
+    Parameters
+    ----------
+    state : np.ndarray
+        A pure statevector of length 2**n_qubits.
+    n_qubits : int
+    keep_qubits : list[int]
+        Qubit indices (this package's MSB-first convention) to keep.
+
+    Returns
+    -------
+    np.ndarray
+        Density matrix of shape (2**len(keep_qubits), 2**len(keep_qubits)).
+    """
+    keep_qubits = sorted(keep_qubits)
+    trace_qubits = [q for q in range(n_qubits) if q not in keep_qubits]
+    psi = np.transpose(np.asarray(state).reshape([2] * n_qubits), keep_qubits + trace_qubits)
+    keep_dim, trace_dim = 2 ** len(keep_qubits), 2 ** len(trace_qubits)
+    psi = psi.reshape(keep_dim, trace_dim)
+    return psi @ psi.conj().T
+
+
+def von_neumann_entropy(rho):
+    """S(rho) = -Tr(rho log rho), computed from rho's eigenvalues. Nearly-
+    zero eigenvalues (which a numerically pure/near-pure state produces,
+    and which are mathematically forbidden from being exactly negative
+    for a real density matrix but can land at a tiny negative float) are
+    clipped before the log rather than raising or propagating a NaN.
+
+    Natural log (nats), NOT log2 (bits) -- unlike this package's other
+    entropy-family quantities (magic_entropy, kl_divergence,
+    sandwiched_renyi_divergence, stabilizer_renyi_entropy), which all
+    use log2 and say so explicitly. mutual_information/central_charge
+    below inherit this same nats convention."""
+    eigs = np.clip(np.linalg.eigvalsh(rho).real, 1e-14, None)
+    return float(-np.sum(eigs * np.log(eigs)))
+
+
+def mutual_information(state, n_qubits, qubits_a, qubits_b):
+    """I(A:B) = S(A) + S(B) - S(A union B), the standard quantum mutual
+    information between two disjoint subsystems of a pure global state.
+    In nats (natural log), same as von_neumann_entropy above -- see its
+    docstring for how this differs from this package's other,
+    log2-based entropy quantities.
+
+    Why this and not a single-qubit expectation value: a qubit entangled
+    in a Bell pair (or more generally, maximally mixed on its own) has a
+    marginal <Z> of exactly 0 regardless of what operation was applied to
+    its partner -- this is the no-signaling theorem, not a measurement
+    limitation, and no amount of clever circuit design around a
+    single-qubit readout can get around it. Mutual information *can*
+    reveal correlations a marginal expectation value structurally cannot,
+    because it depends on the *joint* state of A and B, not either one
+    alone. Verified in tests/unit/test_entropy.py against the exact textbook
+    value for a Bell pair (I = 2*ln(2), maximal) and a GHZ state.
+    """
+    if not set(qubits_a).isdisjoint(qubits_b):
+        raise ValueError(
+            f"qubits_a and qubits_b must be disjoint, got qubits_a={qubits_a!r}, "
+            f"qubits_b={qubits_b!r} -- an overlapping qubit would be traced "
+            "into S(A), S(B) AND S(A union B) inconsistently, silently "
+            "corrupting the result rather than raising."
+        )
+    s_a = von_neumann_entropy(partial_trace(state, n_qubits, qubits_a))
+    s_b = von_neumann_entropy(partial_trace(state, n_qubits, qubits_b))
+    s_ab = von_neumann_entropy(partial_trace(state, n_qubits, list(qubits_a) + list(qubits_b)))
+    return s_a + s_b - s_ab
+
+
+def central_charge(Ls, S, n_qubits):
+    """Fit an open-chain entanglement entropy curve S(L) to the Calabrese-
+    Cardy CFT prediction S(L) = (c/6)*ln[(2N/pi)*sin(pi*L/N)] + const
+    (Calabrese & Cardy, J. Stat. Mech. 2004, P06002, eq. 4/19 combined via
+    the standard open-chain doubling trick) and return (c, r_squared).
+    The fit itself is in the natural-log (nats) convention shown above --
+    `S` must be too (von_neumann_entropy's own convention) for the fitted
+    `c` to come out right; a log2-based S would scale it off by ln(2).
+
+    Backend-agnostic: `S` can come from any source (exact diagonalization
+    via `partial_trace`/`von_neumann_entropy` on this package's own
+    `DenseSVSimulator`, `MPSSimulator`, `Chunk`, or elsewhere) -- this
+    doesn't compute the entropy itself, only fits an already-measured
+    curve. Meant as a benchmark diagnostic: does a given backend/
+    truncation scheme preserve genuine critical CFT scaling, and with
+    what effective central charge?
+
+    A high r_squared alone does NOT mean the extracted c is trustworthy --
+    Dense-Evolution-Discovery Experiment 36 found fitting at a finite-size
+    pseudo-critical point (a susceptibility peak, not the true CFT point)
+    gives a deceptively clean fit (r_squared=0.999997) to a wrong answer
+    (c off by 2x). Only trust this near a genuine, independently-verified
+    critical point.
+
+    Parameters
+    ----------
+    Ls : array-like of int
+        Subsystem sizes, each counted from one physical boundary of an
+        open chain of `n_qubits` sites (not a bulk interval -- see
+        Discovery Experiment 36 for the periodic/bulk c/3 case instead).
+    S : array-like of float
+        Entanglement entropy at each L in `Ls`, same length.
+    n_qubits : int
+        Total open-chain length N.
+
+    Returns
+    -------
+    c : float
+        Extracted central charge (theory: 0.5 for Ising, 1.0 for a free
+        boson/XX chain, ...).
+    r_squared : float
+        Fit quality, in [0, 1] for a sane fit (can go negative for a
+        pathological fit worse than the mean).
+    """
+    Ls = np.asarray(Ls, dtype=float)
+    S = np.asarray(S, dtype=float)
+    x = np.log((2.0 * n_qubits / np.pi) * np.sin(np.pi * Ls / n_qubits))
+    slope, intercept = np.polyfit(x, S, 1)
+    c = 6.0 * slope
+    pred = slope * x + intercept
+    ss_res = float(np.sum((S - pred) ** 2))
+    ss_tot = float(np.sum((S - S.mean()) ** 2))
+    r_squared = 1.0 - ss_res / ss_tot if ss_tot > 0 else float("nan")
+    return float(c), r_squared