lcd-qec 0.1.0__py3-none-any.whl

lcd/__init__.py

@@ -0,0 +1,4 @@
+"""Logical Coset Distinguishability (LCD): rigorous logical-error bounds and numerics for the resource theory of
+surface-code noise. Distributed on PyPI as ``lcd-qec``."""
+
+__version__ = "0.1.0"

lcd/analysis/__init__.py

@@ -0,0 +1,4 @@
+from .crossing import crossing
+from .stratified import Estimate, Strata, StratifiedEstimator
+
+__all__ = ["Estimate", "Strata", "StratifiedEstimator", "crossing"]

lcd/analysis/burst_detection.py

@@ -0,0 +1,337 @@
+"""Burst detection from detection events: counting versus a space-time scan statistic (theory §5.4-5.5).
+
+Theorem 5.9 says that, under the marked-Poisson model (M), a test that uses the space-time pattern of the detection
+events has Stein exponent D_pattern = D_count + Lambda_1 D(pi_1 || pi_0) >= D_count, where D_count belongs to the test that
+uses only the total number of events. This module provides the two tests for detector data of a 1-D (repetition) code
+laid out on a (round, position) grid, with a common interface:
+
+* ``CountDetector``: z-score of the total number of detection events against the baseline mean and the *empirical*
+  variance of the per-shot total (any monotone function of the total, e.g. its Poisson or binomial likelihood ratio
+  against an elevated rate, gives the same one-sided test and the same ROC once thresholds are calibrated).
+* ``ScanDetector``: maximum over rectangles (contiguous positions x contiguous rounds, sizes from a bounded list) of the
+  Bernoulli log-likelihood ratio "every cell of the rectangle has a common rate rho > baseline" versus the per-cell
+  baseline rates p_i (rho at its maximum-likelihood value k / n). With m shots summed into the counts K, the cell counts
+  are Binomial(m, p_i) and
+
+      LLR(A) = k ln(rho) + (n - k) ln(1 - rho) - sum_{i in A} [K_i ln p_i + (m - K_i) ln(1 - p_i)],   n = m |A|, rho = k / n,
+
+  set to 0 unless k exceeds its baseline expectation. All box sums come from 2-D cumulative sums (integral images),
+  so one rectangle size costs O(cells) per shot. ``model="poisson"`` gives the Kulldorff Poisson scan
+  k ln(k / mu) - (k - mu) with mu = m sum_A p_i instead.
+
+Both detectors take an array K of shape (batch, rounds, positions) holding detection events summed over m consecutive
+shots (m = 1: single shots), and optionally the number M of Bernoulli trials per cell; ``counts_and_trials`` builds
+(K, M), optionally after masking leakage-like streaks (``streak_mask``: runs of >= min_run consecutive events of one
+detector, which dominate the tail of the scan statistic on real data). Thresholds are calibrated empirically on clean shots
+(``thresholds``): neither statistic's null distribution is taken from the model, because real detection events are
+correlated (one fault flips two detectors) and the per-shot totals are over-dispersed.
+
+``plant_bursts`` XORs synthetic burst events into real shots; ``marked_poisson_divergences`` and
+``bernoulli_divergences`` give D_count and D_pattern (Lemma 5.8 / Theorem 5.9, and the independent-Bernoulli analogue)
+for a planted burst at a known location.
+"""
+from __future__ import annotations
+
+import collections
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+import numpy as np
+from scipy.special import xlogy
+
+DEFAULT_WIDTHS = (1, 2, 3, 4, 6, 8, 12, 16, 24)
+DEFAULT_HEIGHTS = (1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 51)
+
+
+# ---------------------------------------------------------------------------------------------------------- data access
+def chain_layout(coords: dict, dem) -> np.ndarray:
+    """Detector indices of a 1-D code on a (round, position) grid, positions ordered along the chain.
+
+    ``coords``: detector -> coordinates (x, y, t) as returned by ``stim.Circuit.get_detector_coordinates``; ``dem``: a
+    ``stim.DetectorErrorModel`` whose two-detector mechanisms inside one time slice give the chain's adjacency."""
+    times = sorted({float(c[-1]) for c in coords.values()})
+    tindex = {t: i for i, t in enumerate(times)}
+    sites = sorted({tuple(float(v) for v in c[:-1]) for c in coords.values()})
+    adj: dict = collections.defaultdict(set)
+    for inst in dem.flattened():
+        if inst.type != "error":
+            continue
+        ds = [t.val for t in inst.targets_copy() if t.is_relative_detector_id()]
+        if len(ds) == 2 and coords[ds[0]][-1] == coords[ds[1]][-1]:
+            a, b = (tuple(float(v) for v in coords[d][:-1]) for d in ds)
+            if a != b:
+                adj[a].add(b)
+                adj[b].add(a)
+    ends = [s for s in sites if len(adj[s]) == 1]
+    if len(ends) != 2 or any(len(adj[s]) > 2 for s in sites):
+        raise ValueError("the space-like adjacency is not a simple chain")
+    order, prev = [min(ends)], None
+    while len(order) < len(sites):
+        nxt = [s for s in adj[order[-1]] if s != prev]
+        prev = order[-1]
+        order.append(nxt[0])
+    pos = {s: i for i, s in enumerate(order)}
+    layout = np.full((len(times), len(order)), -1, dtype=np.int64)
+    for d, c in coords.items():
+        layout[tindex[float(c[-1])], pos[tuple(float(v) for v in c[:-1])]] = d
+    if (layout < 0).any():
+        raise ValueError("some (round, position) cells have no detector")
+    return layout
+
+
+class B8Reader:
+    """Random access to a stim b8 file of detection events (one byte-aligned, little-endian record per shot)."""
+
+    def __init__(self, path: str | Path, num_detectors: int):
+        self.num_detectors = num_detectors
+        self.nbytes = (num_detectors + 7) // 8
+        self.raw = np.memmap(path, dtype=np.uint8, mode="r")
+        if self.raw.size % self.nbytes:
+            raise ValueError("file size is not a multiple of the record size")
+        self.shots = self.raw.size // self.nbytes
+        self.raw = self.raw.reshape(self.shots, self.nbytes)
+
+    def events(self, idx) -> np.ndarray:
+        """Detection events of the shots ``idx`` (slice or index array) as a uint8 array (shots, num_detectors)."""
+        return np.unpackbits(np.asarray(self.raw[idx]), axis=1, bitorder="little")[:, :self.num_detectors]
+
+    def grid(self, idx, layout: np.ndarray) -> np.ndarray:
+        """Detection events of the shots ``idx`` on the (round, position) grid: uint8 array (shots, rounds, positions)."""
+        return self.events(idx)[:, layout]
+
+
+def window_sums(grids: np.ndarray, w: int, starts: Sequence[int] | None = None) -> np.ndarray:
+    """Sums of ``w`` consecutive shots: out[j] = grids[starts[j]:starts[j] + w].sum(0) (all starts if None)."""
+    g = np.asarray(grids, dtype=np.int32)
+    if w == 1 and starts is None:
+        return g
+    c = np.concatenate([np.zeros((1,) + g.shape[1:], np.int32), np.cumsum(g, axis=0, dtype=np.int32)])
+    s = np.arange(len(g) - w + 1) if starts is None else np.asarray(starts)
+    return c[s + w] - c[s]
+
+
+# ------------------------------------------------------------------------------------------------------------- baseline
+def streak_mask(grids: np.ndarray, min_run: int) -> np.ndarray:
+    """Cells (shots, rounds, positions) that belong to a run of at least ``min_run`` consecutive detection events of one
+    detector in time. Such runs are the signature of leakage (a detector firing in every round), far more frequent in
+    real data than independent rates allow; masking them makes a test insensitive to them."""
+    x = np.asarray(grids).astype(np.int16)
+    T = x.shape[1]
+    f = np.zeros_like(x)
+    b = np.zeros_like(x)
+    f[:, 0] = x[:, 0]
+    for t in range(1, T):
+        f[:, t] = (f[:, t - 1] + 1) * x[:, t]
+    b[:, T - 1] = x[:, T - 1]
+    for t in range(T - 2, -1, -1):
+        b[:, t] = (b[:, t + 1] + 1) * x[:, t]
+    return (f + b - 1 >= min_run).astype(np.uint8)
+
+
+def counts_and_trials(grids: np.ndarray, min_run: int | None = None, w: int = 1,
+                      starts: Sequence[int] | None = None) -> tuple[np.ndarray, np.ndarray | None]:
+    """(K, M): detection events and Bernoulli trials per cell summed over windows of ``w`` shots, after masking streak
+    cells (``streak_mask``) if ``min_run`` is given; M is None (= w for every cell) without masking."""
+    g = np.asarray(grids, dtype=np.uint8)
+    if min_run is None:
+        return window_sums(g, w, starts), None
+    keep = 1 - streak_mask(g, min_run)
+    return window_sums(g * keep, w, starts), window_sums(keep, w, starts)
+
+
+@dataclass
+class Baseline:
+    """Per-cell detection rates p (rounds, positions) and the mean / variance of the per-shot total, from clean shots.
+    With ``min_run`` the rates and totals are those of the streak-masked data and ``count_var`` is the variance of the
+    total minus its expectation given the mask."""
+    p: np.ndarray
+    count_mean: float
+    count_var: float
+    shots: int
+    min_run: int | None = None
+
+    @classmethod
+    def fit(cls, grids: np.ndarray, min_run: int | None = None) -> "Baseline":
+        """Estimate from grids (shots, rounds, positions); rates clipped to [1/(2n), 1 - 1/(2n)]."""
+        g = np.asarray(grids, dtype=np.uint8)
+        n = len(g)
+        if n < 2:
+            raise ValueError("need at least two shots")
+        K, M = counts_and_trials(g, min_run)
+        M = np.ones_like(K) if M is None else M
+        p = np.clip(K.sum(0) / np.maximum(M.sum(0), 1), 0.5 / n, 1 - 0.5 / n)
+        res = K.reshape(n, -1).sum(1) - (M * p).reshape(n, -1).sum(1)
+        return cls(p=p, count_mean=float(p.sum()), count_var=float(res.var(ddof=1)), shots=n, min_run=min_run)
+
+
+# ------------------------------------------------------------------------------------------------------------ detectors
+class CountDetector:
+    """z-score of the total number of detection events of m summed shots: (N - E) / sqrt(m var), E = sum_i M_i p_i
+    (= m mu without masking)."""
+    name = "count"
+
+    def __init__(self, baseline: Baseline):
+        self.p, self.var = baseline.p, baseline.count_var
+
+    def score(self, K: np.ndarray, M: np.ndarray | None = None, m: int = 1) -> np.ndarray:
+        K = np.asarray(K)
+        N = K.reshape(len(K), -1).sum(1, dtype=np.int64).astype(np.float64)
+        E = m * self.p.sum() if M is None else (np.asarray(M) * self.p).reshape(len(K), -1).sum(1)
+        return (N - E) / np.sqrt(m * self.var)
+
+
+def _integral(x: np.ndarray) -> np.ndarray:
+    """Integral image over the last two axes, with a leading row and column of zeros."""
+    c = np.cumsum(np.cumsum(x, axis=-2), axis=-1)
+    pad = [(0, 0)] * (x.ndim - 2) + [(1, 0), (1, 0)]
+    return np.pad(c, pad)
+
+
+def _box(c: np.ndarray, h: int, w: int) -> np.ndarray:
+    """All h x w box sums from an integral image: shape (..., T - h + 1, Q - w + 1)."""
+    return c[..., h:, w:] - c[..., :-h, w:] - c[..., h:, :-w] + c[..., :-h, :-w]
+
+
+class ScanDetector:
+    """Space-time scan statistic: max over rectangles (heights x widths) of the elevated-rate log-likelihood ratio.
+
+    Each cell i carries K_i events in M_i Bernoulli trials (M_i = m without masking). For a rectangle A with
+    k = sum K_i, n = sum M_i, rho = k / n:
+        bernoulli:  LLR = k ln rho + (n - k) ln(1 - rho) - sum_A [K_i ln p_i + (M_i - K_i) ln(1 - p_i)]  if k > sum_A M_i p_i
+        poisson:    LLR = k ln(k / mu) - (k - mu),  mu = sum_A M_i p_i                                     if k > mu
+    and 0 otherwise."""
+    name = "pattern"
+
+    def __init__(self, baseline: Baseline, widths: Sequence[int] = DEFAULT_WIDTHS,
+                 heights: Sequence[int] = DEFAULT_HEIGHTS, model: str = "bernoulli"):
+        if model not in ("bernoulli", "poisson"):
+            raise ValueError("model must be 'bernoulli' or 'poisson'")
+        p = np.asarray(baseline.p, dtype=np.float64)
+        T, Q = p.shape
+        self.p, self.model = p, model
+        self.widths = sorted({int(w) for w in widths if 1 <= w <= Q})
+        self.heights = sorted({int(h) for h in heights if 1 <= h <= T})
+        self.logit = np.log(p) - np.log1p(-p)
+        self.log1mp = np.log1p(-p)
+
+    def regions(self) -> int:
+        T, Q = self.p.shape
+        return sum((T - h + 1) * (Q - w + 1) for h in self.heights for w in self.widths)
+
+    def _integrals(self, K: np.ndarray, M: np.ndarray | None, m: int) -> dict:
+        K = np.asarray(K, dtype=np.float64)
+        Mf = np.full(K.shape[1:], float(m)) if M is None else np.asarray(M, dtype=np.float64)
+        return dict(k=_integral(K), ka=_integral(K * self.logit), n=_integral(Mf), nb=_integral(Mf * self.log1mp),
+                    mu=_integral(Mf * self.p))
+
+    def llr_boxes(self, K: np.ndarray, h: int, w: int, M: np.ndarray | None = None, m: int = 1,
+                  C: dict | None = None) -> np.ndarray:
+        """LLR of every h x w rectangle: shape (batch, T - h + 1, Q - w + 1)."""
+        C = self._integrals(K, M, m) if C is None else C
+        k, mu = _box(C["k"], h, w), _box(C["mu"], h, w)
+        if self.model == "poisson":
+            with np.errstate(divide="ignore", invalid="ignore"):
+                llr = xlogy(k, k / mu) - (k - mu)
+            return np.where(k > mu, llr, 0.0)
+        n = _box(C["n"], h, w)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            rho = np.where(n > 0, k / np.maximum(n, 1e-300), 0.0)
+            alt = xlogy(k, rho) + xlogy(n - k, 1.0 - rho)
+        null = _box(C["ka"], h, w) + _box(C["nb"], h, w)
+        return np.where(k > mu, alt - null, 0.0)
+
+    def score(self, K: np.ndarray, M: np.ndarray | None = None, m: int = 1, return_argmax: bool = False,
+              batch: int = 256):
+        """Scan statistic of each row of K (batch, rounds, positions); M: trials per cell (None: m everywhere).
+
+        With ``return_argmax`` also returns an int array (batch, 4) of the maximizing (round0, pos0, height, width)."""
+        K = np.asarray(K)
+        out = np.zeros(len(K))
+        arg = np.zeros((len(K), 4), dtype=np.int64)
+        Q = self.p.shape[1]
+        for s in range(0, len(K), batch):
+            Kb = K[s:s + batch]
+            C = self._integrals(Kb, None if M is None else M[s:s + batch], m)
+            best = np.zeros(len(Kb))
+            ab = arg[s:s + batch]
+            for h in self.heights:
+                for w in self.widths:
+                    L = self.llr_boxes(Kb, h, w, C=C).reshape(len(Kb), -1)
+                    j = L.argmax(1)
+                    v = L[np.arange(len(Kb)), j]
+                    better = v > best
+                    best = np.where(better, v, best)
+                    if return_argmax and better.any():
+                        q = Q - w + 1
+                        ab[better] = np.stack([j[better] // q, j[better] % q, np.full(better.sum(), h),
+                                               np.full(better.sum(), w)], 1)
+            out[s:s + batch] = best
+        return (out, arg) if return_argmax else out
+
+
+# ---------------------------------------------------------------------------------------------- calibration and planting
+def thresholds(null_scores: np.ndarray, fars: Sequence[float]) -> dict:
+    """Empirical thresholds: the smallest t with (#null scores > t) / n <= far, for each false-alarm rate."""
+    s = np.sort(np.asarray(null_scores))[::-1]
+    out = {}
+    for a in fars:
+        j = int(np.floor(a * len(s)))  # allow j exceedances
+        out[float(a)] = float(s[j]) if j < len(s) else float(-np.inf)
+    return out
+
+
+def plant_bursts(grids: np.ndarray, rng: np.random.Generator, R: int, T: int, theta: float,
+                 corner: tuple[int, int] | None = None) -> tuple[np.ndarray, tuple[int, int]]:
+    """XOR a burst into every shot of ``grids`` (shots, rounds, positions): each cell of one R-position x T-round
+    rectangle flips independently with probability theta. The rectangle is the same for all shots (a burst lasting
+    the whole window); its corner (round0, pos0) is uniformly random unless given. Returns (new grids, corner)."""
+    g = np.array(grids, dtype=np.uint8, copy=True)
+    nT, nQ = g.shape[1:]
+    if corner is None:
+        corner = (int(rng.integers(0, nT - T + 1)), int(rng.integers(0, nQ - R + 1)))
+    t0, q0 = corner
+    flips = rng.random((len(g), T, R)) < theta
+    g[:, t0:t0 + T, q0:q0 + R] ^= flips.astype(np.uint8)
+    return g, corner
+
+
+# --------------------------------------------------------------------------------------------------------------- theory
+def planted_rates(p: np.ndarray, R: int, T: int, theta: float, corner: tuple[int, int]) -> np.ndarray:
+    """Per-cell rates after XOR-ing Bernoulli(theta) into the rectangle: p + theta (1 - 2p) inside, p outside."""
+    p1 = np.array(p, dtype=np.float64, copy=True)
+    t0, q0 = corner
+    s = p1[t0:t0 + T, q0:q0 + R]
+    p1[t0:t0 + T, q0:q0 + R] = s + theta * (1 - 2 * s)
+    return p1
+
+
+def marked_poisson_divergences(lam0: np.ndarray, lam1: np.ndarray) -> dict:
+    """Lemma 5.8 / Theorem 5.9: D_pattern, D_count, and the decomposition D_pattern = D_count + Lambda_1 D(pi_1||pi_0)."""
+    l0, l1 = np.ravel(lam0).astype(float), np.ravel(lam1).astype(float)
+    dp = float(np.sum(xlogy(l1, l1 / l0) - l1 + l0))
+    L0, L1 = l0.sum(), l1.sum()
+    dc = float(L1 * np.log(L1 / L0) - L1 + L0)
+    pi0, pi1 = l0 / L0, l1 / L1
+    dpi = float(np.sum(xlogy(pi1, pi1 / pi0)))
+    return dict(D_pattern=dp, D_count=dc, Lambda0=float(L0), Lambda1=float(L1), D_pi=dpi,
+                identity_residual=float(dp - dc - L1 * dpi), ratio=dp / dc if dc > 0 else float("inf"))
+
+
+def _poisson_binomial(p: np.ndarray) -> np.ndarray:
+    """Distribution of a sum of independent Bernoulli(p_i) (exact, by convolution)."""
+    dist = np.ones(1)
+    for q in np.ravel(p):
+        dist = np.convolve(dist, [1 - q, q])
+    return dist
+
+
+def bernoulli_divergences(p0: np.ndarray, p1: np.ndarray) -> dict:
+    """Independent-Bernoulli cells: D_pattern = sum_i KL(Bern(p1_i)||Bern(p0_i)); D_count = KL of the exact
+    Poisson-binomial laws of the totals. Per shot, H1 relative to H0."""
+    a, b = np.ravel(p0).astype(float), np.ravel(p1).astype(float)
+    dp = float(np.sum(xlogy(b, b / a) + xlogy(1 - b, (1 - b) / (1 - a))))
+    f0, f1 = _poisson_binomial(a), _poisson_binomial(b)
+    mask = f1 > 0
+    dc = float(np.sum(f1[mask] * (np.log(f1[mask]) - np.log(np.maximum(f0[mask], 1e-300)))))
+    return dict(D_pattern=dp, D_count=dc, ratio=dp / dc if dc > 0 else float("inf"))

lcd/analysis/circuit_peierls.py

@@ -0,0 +1,300 @@
+"""Circuit-level Peierls bound for minimum-weight matching on a detector error model (theory, Theorem 4.28).
+
+Input: a stim detector error model with one logical observable, decomposed into graphlike components
+(``circuit.detector_error_model(decompose_errors=True)``), and the decoder's edge weights (by default those of
+``pymatching.Matching.from_detector_error_model``). Output: an upper bound on the logical failure probability of an
+exact minimum-weight decoder with those weights, hence of the maximum-likelihood decoder.
+
+The bound (Theorem 4.28):
+  * the observable graph is the part of the decoding graph whose components (without the boundary vertex b) carry an
+    edge that flips the observable; every mechanism is written as a set of its edges with the same detectors and the same
+    observable flip, as one edge whenever such an edge exists ("re-decomposition");
+  * if every cycle avoiding b has even observable parity (checked; the graph is "balanced"), the boundary detectors
+    split into two sides and the odd cycles are the paths between the sides closed through b;
+  * for lam >= 0 an odd simple cycle gamma contributes at most prod_{e in gamma} beta_e(lam), with
+        beta_e(lam) = exp(-lam w_e) (1 - q_e + q_e exp(2 lam w_e)) * prod_{split m on e} (1 + p_m^(1/k_m)(exp(2 lam w_e) - 1)),
+    q_e the flip probability of edge e from the mechanisms that have no other edge on any odd cycle with e, and the
+    remaining (split) mechanisms m with k_m edges shared out by the splitting lemma;
+  * pymatching minimizes rounded weights; every beta_e is multiplied by exp(lam delta), delta the rounding slack (4.28(e));
+  * summing over non-backtracking walks from one side to the other gives start^T (I - B)^{-1} end, finite when the
+    spectral radius of the weighted non-backtracking matrix B is < 1.
+
+    from lcd.analysis.circuit_peierls import peierls_bound
+    res = peierls_bound(circuit.detector_error_model(decompose_errors=True))
+    res["bound"], res["lam"], res["rho_upper"]
+"""
+from __future__ import annotations
+
+import collections
+from dataclasses import dataclass, field
+from math import sqrt
+
+import numpy as np
+import scipy.sparse as sp
+import scipy.sparse.linalg as spla
+
+Edge = tuple  # (u,) for an edge to the boundary vertex, (u, v) with u < v otherwise
+
+
+@dataclass
+class DemGraph:
+    edges: list                     # edges of the observable graph
+    flag: np.ndarray                # observable flag of each edge (0/1)
+    q: np.ndarray                   # flip probability of each edge from its exclusive mechanisms
+    split: list                     # per edge: the shares p_m^(1/k_m) of mechanisms that are split
+    side: dict                      # boundary detector -> side 0/1 (odd cycles join the two sides)
+    stats: dict = field(default_factory=dict)
+
+    @property
+    def index(self) -> dict:
+        return {e: i for i, e in enumerate(self.edges)}
+
+
+def _parse(dem) -> list:
+    """[(p, [(detectors, observable parity), ...]), ...] with one entry per graphlike component."""
+    if dem.num_observables != 1:
+        raise ValueError("one logical observable expected")
+    import stim
+    out = []
+    for inst in dem.flattened():
+        if inst.type != "error":
+            continue
+        comps, dets, o = [], [], 0
+        for t in inst.targets_copy() + [stim.DemTarget.separator()]:
+            if t.is_separator():
+                comps.append((tuple(sorted(dets)), o))
+                dets, o = [], 0
+            elif t.is_logical_observable_id():
+                o ^= 1
+            else:
+                dets.append(t.val)
+        p = inst.args_copy()[0]
+        if not 0 <= p <= 0.5:
+            raise ValueError(f"mechanism probability {p} outside [0, 1/2]")
+        out.append((p, comps))
+    return out
+
+
+def dem_graph(dem) -> DemGraph:
+    """The observable graph of a decomposed detector error model, with re-decomposed mechanisms (Definition 4.27)."""
+    mechs = _parse(dem)
+    flag: dict = {}
+    for _, comps in mechs:
+        for e, o in comps:
+            if len(e) not in (1, 2):
+                raise ValueError(f"component {e} is not graphlike (use decompose_errors=True)")
+            if flag.setdefault(e, o) != o:
+                raise ValueError(f"edge {e} carries both observable flags")
+    parent: dict = {}
+
+    def find(x):
+        parent.setdefault(x, x)
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    for e in flag:
+        find(e[0])
+        if len(e) == 2:
+            parent[find(e[0])] = find(e[1])
+    roots = {find(e[0]) for e, o in flag.items() if o}
+    in_obs = lambda e: find(e[0]) in roots  # noqa: E731
+    edges = sorted(e for e in flag if in_obs(e))
+    eid = {e: i for i, e in enumerate(edges)}
+
+    # balance and sides
+    adj = collections.defaultdict(list)
+    for e in edges:
+        if len(e) == 2:
+            adj[e[0]].append((e[1], flag[e]))
+            adj[e[1]].append((e[0], flag[e]))
+    phi: dict = {}
+    for s in {x for e in edges for x in e}:
+        if s in phi:
+            continue
+        phi[s], stack = 0, [s]
+        while stack:
+            x = stack.pop()
+            for y, o in adj[x]:
+                if y not in phi:
+                    phi[y] = phi[x] ^ o
+                    stack.append(y)
+                elif phi[y] != phi[x] ^ o:
+                    raise NotImplementedError("an odd cycle avoids the boundary vertex (unbalanced graph)")
+    side = {e[0]: flag[e] ^ phi[e[0]] for e in edges if len(e) == 1}
+
+    # re-decomposition
+    lists = collections.defaultdict(list)
+    split = [[] for _ in edges]
+    n_re = n_excl = n_split = 0
+    for p, comps in mechs:
+        zc = [(e, o) for e, o in comps if in_obs(e)]
+        if not zc:
+            continue
+        S, L = set(), 0
+        for e, o in zc:
+            S ^= set(e)
+            L ^= o
+        key = tuple(sorted(S))
+        if not S:
+            if L:
+                raise ValueError("a mechanism flips the observable without any detector")
+            continue
+        if key in eid and flag[key] == L:
+            lists[eid[key]].append(p)
+            n_re += len(zc) > 1
+            continue
+        if len(zc) == 1:
+            lists[eid[zc[0][0]]].append(p)
+            continue
+        es = [eid[e] for e, _ in zc]
+        if all(len(e) == 1 for e, _ in zc) and len({side[e[0]] for e, _ in zc}) == 1:
+            for i in es:                       # boundary edges on one side: never two on an odd simple cycle
+                lists[i].append(p)
+            n_excl += 1
+        else:
+            for i in es:
+                split[i].append(p ** (1 / len(es)))
+            n_split += 1
+    q = np.zeros(len(edges))
+    for i, ps in lists.items():
+        q[i] = 0.5 * (1 - np.prod([1 - 2 * x for x in ps]))
+    stats = dict(mechanisms=len(mechs), edges=len(edges), boundary_edges=sum(len(e) == 1 for e in edges),
+                 redecomposed=n_re, exclusive_multi=n_excl, split_multi=n_split)
+    return DemGraph(edges=edges, flag=np.array([flag[e] for e in edges], np.int8), q=q, split=split, side=side,
+                    stats=stats)
+
+
+def pymatching_weights(dem, G: DemGraph) -> np.ndarray:
+    """Weights of the observable-graph edges in pymatching's matching graph built from the same model."""
+    import pymatching
+    m = pymatching.Matching.from_detector_error_model(dem)
+    eid = G.index
+    w = np.full(len(G.edges), np.nan)
+    for u, v, attr in m.edges():
+        key = (u,) if v is None else tuple(sorted((u, v)))
+        if key in eid:
+            w[eid[key]] = attr["weight"]
+    if np.isnan(w).any() or (w < 0).any():
+        raise ValueError("an observable-graph edge has no nonnegative pymatching weight")
+    return w
+
+
+# pymatching 2.x (sparse_blossom/driver/user_graph.h, user_graph.cc) minimizes the integer weights
+# 2 round(kappa w), kappa = (NUM_DISTINCT_WEIGHTS - 1) / max|w| over all edges (kappa = 1 if every weight is an integer).
+PYMATCHING_NUM_DISTINCT_WEIGHTS = 1 << 24
+
+
+def pymatching_rounding_slack(dem) -> float:
+    """delta of Theorem 4.28(e): pymatching minimizes weights within delta per edge of its float weights (up to scale)."""
+    import pymatching
+    if int(pymatching.__version__.split(".")[0]) != 2:
+        raise RuntimeError(f"weight discretization checked for pymatching 2.x only, found {pymatching.__version__}")
+    ws = np.array([attr["weight"] for _, _, attr in pymatching.Matching.from_detector_error_model(dem).edges()])
+    if ws.size == 0 or np.all(np.round(ws) == ws):
+        return 0.0
+    return float(np.abs(ws).max()) / (2 * (PYMATCHING_NUM_DISTINCT_WEIGHTS - 1))
+
+
+def edge_factors(G: DemGraph, w: np.ndarray, lam: float, delta: float = 0.0) -> np.ndarray:
+    """beta_e(lam) of Theorem 4.28, times exp(lam delta) for a decoder that minimizes weights within delta of w (4.28(e))."""
+    a = np.exp(2 * lam * w)
+    beta = np.exp(lam * (delta - w)) * (1 - G.q + G.q * a)
+    for i, shares in enumerate(G.split):
+        for s in shares:
+            beta[i] *= 1 + s * (a[i] - 1)
+    return beta
+
+
+@dataclass
+class _Arcs:
+    arc_edge: np.ndarray
+    rows: np.ndarray
+    cols: np.ndarray
+    start_bdry: np.ndarray          # boundary edge index of the arc's tail if on side 0, else -1
+    end_bdry: np.ndarray            # boundary edge index of the arc's head if on side 1, else -1
+
+
+def _arcs(G: DemGraph) -> _Arcs:
+    arcs, arc_edge = [], []
+    for i, e in enumerate(G.edges):
+        if len(e) == 2:
+            arcs += [(e[0], e[1]), (e[1], e[0])]
+            arc_edge += [i, i]
+    out = collections.defaultdict(list)
+    for a, (x, _) in enumerate(arcs):
+        out[x].append(a)
+    rows, cols = [], []
+    for a, (x, y) in enumerate(arcs):
+        for b in out[y]:
+            if arcs[b][1] != x:
+                rows.append(a)
+                cols.append(b)
+    bedge = {e[0]: i for i, e in enumerate(G.edges) if len(e) == 1}
+    sb = np.array([bedge[x] if G.side.get(x) == 0 else -1 for x, _ in arcs], dtype=np.int64)
+    eb = np.array([bedge[y] if G.side.get(y) == 1 else -1 for _, y in arcs], dtype=np.int64)
+    return _Arcs(np.array(arc_edge, np.int64), np.array(rows, np.int64), np.array(cols, np.int64), sb, eb)
+
+
+def walk_sum(G: DemGraph, beta: np.ndarray, arcs: _Arcs | None = None) -> tuple[float, float]:
+    """(bound, rho_upper): the sum over non-backtracking walks between the sides, closed by their boundary edges.
+
+    rho_upper = 1 - 1/max z with z = (I - B)^{-1} 1 is a Collatz-Wielandt upper bound on the spectral radius of B; if z
+    is not positive the radius is >= 1 and the bound is infinite.
+    """
+    A = arcs if arcs is not None else _arcs(G)
+    n = len(A.arc_edge)
+    if n == 0:
+        return 0.0, 0.0
+    B = sp.csc_matrix((beta[A.arc_edge[A.cols]], (A.rows, A.cols)), shape=(n, n))
+    lu = spla.splu((sp.identity(n, format="csc") - B).tocsc())
+    z = lu.solve(np.ones(n))
+    if not np.all(z > 0):
+        return np.inf, np.nan
+    rho_upper = 1 - 1 / z.max()
+    start = np.where(A.start_bdry >= 0, beta[np.maximum(A.start_bdry, 0)] * beta[A.arc_edge], 0.0)
+    end = np.where(A.end_bdry >= 0, beta[np.maximum(A.end_bdry, 0)], 0.0)
+    return float(start @ lu.solve(end)), float(rho_upper)
+
+
+def peierls_bound(dem, weights: np.ndarray | None = None, lams=None, G: DemGraph | None = None,
+                  delta: float | None = None) -> dict:
+    """Minimize the bound of Theorem 4.28 over lam (the bound is log-convex in lam: coarse grid, then golden section).
+
+    Default: pymatching's weights and its rounding slack delta (Theorem 4.28(e)). With explicit ``weights`` the decoder is
+    assumed to minimize exactly those weights (delta = 0) unless ``delta`` is given.
+    """
+    G = G if G is not None else dem_graph(dem)
+    if weights is None:
+        w = pymatching_weights(dem, G)
+        delta = pymatching_rounding_slack(dem) if delta is None else delta
+    else:
+        w, delta = weights, (0.0 if delta is None else delta)
+    A = _arcs(G)
+
+    def f(lam):
+        return walk_sum(G, edge_factors(G, w, lam, delta), A)
+
+    grid = list(lams) if lams is not None else [0.1 * k for k in range(1, 10)]
+    vals = [f(l)[0] for l in grid]
+    k = int(np.argmin(vals))
+    if lams is None and np.isfinite(vals[k]):
+        lo, hi = grid[max(k - 1, 0)] if k > 0 else 0.01, grid[min(k + 1, len(grid) - 1)] if k < len(grid) - 1 else 0.99
+        g = (sqrt(5) - 1) / 2
+        x1, x2 = hi - g * (hi - lo), lo + g * (hi - lo)
+        f1, f2 = f(x1)[0], f(x2)[0]
+        for _ in range(25):
+            if f1 <= f2:
+                hi, x2, f2 = x2, x1, f1
+                x1 = hi - g * (hi - lo)
+                f1 = f(x1)[0]
+            else:
+                lo, x1, f1 = x1, x2, f2
+                x2 = lo + g * (hi - lo)
+                f2 = f(x2)[0]
+        lam = x1 if f1 <= f2 else x2
+    else:
+        lam = grid[k]
+    val, rho = f(lam)
+    return dict(bound=val, lam=float(lam), rho_upper=rho, delta=delta, stats=G.stats)