dense-evolution 8.2.2__tar.gz → 8.3.0__tar.gz

{dense_evolution-8.2.2 → dense_evolution-8.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dense-evolution
-Version: 8.2.2
+Version: 8.3.0
 Summary: High-performance quantum simulation toolkit -- Statevector/MPS engines with JIT compilation, noise modeling, VQE, QEC, quantum chemistry, and agent-native tooling
 Author-email: Salvatore Pennacchio <jtatopenn@libero.it>
 License: Business Source License 1.1
@@ -39,6 +39,8 @@ Requires-Dist: streamlit>=1.30.0; extra == "dashboard"
 Requires-Dist: qiskit>=1.0.0; extra == "dashboard"
 Requires-Dist: pylatexenc>=2.10; extra == "dashboard"
 Requires-Dist: plotly>=5.0.0; extra == "dashboard"
+Requires-Dist: rdkit>=2023.9.1; extra == "dashboard"
+Requires-Dist: basis_set_exchange>=0.9; extra == "dashboard"
 Provides-Extra: qiskit
 Requires-Dist: qiskit>=1.0.0; extra == "qiskit"
 Provides-Extra: pennylane
@@ -58,8 +60,6 @@ Provides-Extra: mcp
 Requires-Dist: mcp>=2.0.0; extra == "mcp"
 Requires-Dist: httpx>=0.27; extra == "mcp"
 Requires-Dist: pydantic>=2.0.0; extra == "mcp"
-Provides-Extra: libcint
-Requires-Dist: pyscf>=2.0.0; extra == "libcint"
 Provides-Extra: qmmm
 Requires-Dist: rdkit>=2023.9.1; extra == "qmmm"
 Provides-Extra: ase
@@ -108,6 +108,13 @@ Dynamic: license-file
 **A high-performance quantum simulation toolkit
 Statevector/MPS engines with compilation, noise, VQE, QEC, chemistry, and agent-native tooling.**
 
+<p align="center">
+  <img src="docs/assets/favicon.svg" width="32" alt=""><br>
+  <b>Download the Dense Evolution Dashboard (Streamlit)</b><br>
+  <a href="https://github.com/tatopenn-cell/Dense-Evolution/raw/main/tools/installer/install-dashboard.bat">Windows (.bat)</a> &middot;
+  <a href="https://github.com/tatopenn-cell/Dense-Evolution/raw/main/tools/installer/install-dashboard.sh">macOS / Linux (.sh)</a>
+</p>
+
 [![CI](https://github.com/tatopenn-cell/Dense-Evolution/actions/workflows/ci.yml/badge.svg)](https://github.com/tatopenn-cell/Dense-Evolution/actions/workflows/ci.yml)
 [![Docs](https://img.shields.io/badge/docs-tatopenn--cell.github.io-00e5ff?style=flat-square)](https://tatopenn-cell.github.io/Dense-Evolution/)
 [![codecov](https://codecov.io/gh/tatopenn-cell/Dense-Evolution/branch/main/graph/badge.svg)](https://codecov.io/gh/tatopenn-cell/Dense-Evolution)
@@ -295,6 +302,7 @@ sim.run_chunk(circuit.to_tuples(), chunk_size_gates=500)
 - **Anti-OOM `Chunk` engine.** Circuits too large for one array, split dynamically and sized off the real compute device's own free memory — with disk-backed overflow past even that ceiling. [Chunk guide](https://tatopenn-cell.github.io/Dense-Evolution/api/chunk/).
 - **Real noise, real mitigation.** Stochastic Kraus channels, real-device noise imported from Qiskit backends, and Zero-Noise Extrapolation to correct for it. [Noise](https://tatopenn-cell.github.io/Dense-Evolution/api/noise/) · [Mitigation](https://tatopenn-cell.github.io/Dense-Evolution/api/mitigation/) · [what noise/mitigation/healing each mean](https://tatopenn-cell.github.io/Dense-Evolution/concepts/).
 - **Differentiable VQE, from scratch.** `circuit_to_energy_fn` is the same JAX-differentiable engine real molecular VQE runs on — real Hartree-Fock Hamiltonians, UCCSD/hardware-efficient ansätze, Adam optimization. [Autodiff](https://tatopenn-cell.github.io/Dense-Evolution/api/autodiff/).
+- **libcint integrals on Windows, macOS and Linux.** `pip install dense-evolution` ships libcint compiled for each system: the full two-electron tensor of ethanol in 6-31G* in 0.32 s. [native_hf](https://tatopenn-cell.github.io/Dense-Evolution/api/native_hf/).
 - **OpenQASM 2.0/3.0, both directions.** A real parser, plus Qiskit/PennyLane interop bridges. [QASM Parser](https://tatopenn-cell.github.io/Dense-Evolution/api/parser/) · [Interop](https://tatopenn-cell.github.io/Dense-Evolution/api/interop/).
 - **Code-agnostic QEC decoding**, Majorana/Jordan-Wigner fermion mapping, from-scratch Hartree-Fock for elements outside PennyLane's own basis set, a traversable-wormhole-inspired teleportation protocol, and real QM/MM region partitioning (ring-safe BFS, Diffuse2Seg-derived relevance propagation) — see the [full API reference](https://tatopenn-cell.github.io/Dense-Evolution/api/) for all of it.
 

{dense_evolution-8.2.2 → dense_evolution-8.3.0}/README.md

@@ -8,6 +8,13 @@
 **A high-performance quantum simulation toolkit
 Statevector/MPS engines with compilation, noise, VQE, QEC, chemistry, and agent-native tooling.**
 
+<p align="center">
+  <img src="docs/assets/favicon.svg" width="32" alt=""><br>
+  <b>Download the Dense Evolution Dashboard (Streamlit)</b><br>
+  <a href="https://github.com/tatopenn-cell/Dense-Evolution/raw/main/tools/installer/install-dashboard.bat">Windows (.bat)</a> &middot;
+  <a href="https://github.com/tatopenn-cell/Dense-Evolution/raw/main/tools/installer/install-dashboard.sh">macOS / Linux (.sh)</a>
+</p>
+
 [![CI](https://github.com/tatopenn-cell/Dense-Evolution/actions/workflows/ci.yml/badge.svg)](https://github.com/tatopenn-cell/Dense-Evolution/actions/workflows/ci.yml)
 [![Docs](https://img.shields.io/badge/docs-tatopenn--cell.github.io-00e5ff?style=flat-square)](https://tatopenn-cell.github.io/Dense-Evolution/)
 [![codecov](https://codecov.io/gh/tatopenn-cell/Dense-Evolution/branch/main/graph/badge.svg)](https://codecov.io/gh/tatopenn-cell/Dense-Evolution)
@@ -195,6 +202,7 @@ sim.run_chunk(circuit.to_tuples(), chunk_size_gates=500)
 - **Anti-OOM `Chunk` engine.** Circuits too large for one array, split dynamically and sized off the real compute device's own free memory — with disk-backed overflow past even that ceiling. [Chunk guide](https://tatopenn-cell.github.io/Dense-Evolution/api/chunk/).
 - **Real noise, real mitigation.** Stochastic Kraus channels, real-device noise imported from Qiskit backends, and Zero-Noise Extrapolation to correct for it. [Noise](https://tatopenn-cell.github.io/Dense-Evolution/api/noise/) · [Mitigation](https://tatopenn-cell.github.io/Dense-Evolution/api/mitigation/) · [what noise/mitigation/healing each mean](https://tatopenn-cell.github.io/Dense-Evolution/concepts/).
 - **Differentiable VQE, from scratch.** `circuit_to_energy_fn` is the same JAX-differentiable engine real molecular VQE runs on — real Hartree-Fock Hamiltonians, UCCSD/hardware-efficient ansätze, Adam optimization. [Autodiff](https://tatopenn-cell.github.io/Dense-Evolution/api/autodiff/).
+- **libcint integrals on Windows, macOS and Linux.** `pip install dense-evolution` ships libcint compiled for each system: the full two-electron tensor of ethanol in 6-31G* in 0.32 s. [native_hf](https://tatopenn-cell.github.io/Dense-Evolution/api/native_hf/).
 - **OpenQASM 2.0/3.0, both directions.** A real parser, plus Qiskit/PennyLane interop bridges. [QASM Parser](https://tatopenn-cell.github.io/Dense-Evolution/api/parser/) · [Interop](https://tatopenn-cell.github.io/Dense-Evolution/api/interop/).
 - **Code-agnostic QEC decoding**, Majorana/Jordan-Wigner fermion mapping, from-scratch Hartree-Fock for elements outside PennyLane's own basis set, a traversable-wormhole-inspired teleportation protocol, and real QM/MM region partitioning (ring-safe BFS, Diffuse2Seg-derived relevance propagation) — see the [full API reference](https://tatopenn-cell.github.io/Dense-Evolution/api/) for all of it.
 

{dense_evolution-8.2.2 → dense_evolution-8.3.0}/dense_evolution/__init__.py

@@ -58,9 +58,11 @@ from .circuits.trotter import (pauli_rotation_ops, trotter_evolve_ops, continuou
 from .circuits.uccsd import find_excitations, single_excitation_ops, double_excitation_ops
 from .physics.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)
+                           counts_in_intervals_dimension, nearest_coset_decode, erasure_ml_decode,
+                   peeling_decode, union_find_decode, matching_erasure_decode,
+                           estimate_edge_probabilities_from_detection_events)
 
-__version__ = "8.2.2"
+__version__ = "8.3.0"
 
 __all__ = [
     "__version__",
@@ -105,6 +107,8 @@ __all__ = [
     "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",
     # Utils -- drawing, measurement, random circuits
     "draw_circuit", "plot_circuit", "sample_counts", "statevector_fidelity", "random_circuit",
 ]

dense_evolution-8.3.0/dense_evolution/native_hf/libcint_bridge.py

@@ -0,0 +1,167 @@
+"""libcint bridge for native_hf's one- and two-electron integrals.
+
+native_hf's own build_repulsion_tensor (assembly.py) computes the ERI
+tensor via JAX-jitted Obara-Saika recursions -- correct, differentiable,
+but pays a JIT-compilation tax on mixed-angular-momentum bases (~532s on
+Ne/6-31G* even after the primitive-count-padding fix), and its one-electron
+assembly ran out of memory during XLA compilation for a 4-heavy-atom
+molecule at 6-31G* on a Kaggle CPU kernel. libcint (Sun, J. Comput. Chem.
+36, 1664 (2015), BSD-2) computes the identical integrals with C kernels
+compiled once, ahead of time.
+
+libcint is linked statically, together with csrc/cint_driver.c, into one
+shared library shipped inside the platform wheels of dense-evolution
+(dense_evolution/native_hf/_libcint/, built by
+.github/scripts/build-libcint.sh in .github/workflows/libcint.yml) and
+called through ctypes, with the atm/bas/env arrays built here from
+native_hf's own ContractedShell list. The driver loops over shell blocks
+in C (8-fold ERI symmetry, int2e_optimizer) and writes every integral
+already rescaled and in native_hf's AO order. A source install has no
+bundled library: run build-libcint.sh and point DENSE_EVOLUTION_LIBCINT at
+the resulting file.
+
+Shells are passed to libcint in native_hf's own order, so AO blocks line
+up shell by shell. Two convention differences remain inside each shell,
+confirmed empirically on Ne/6-31G*:
+  - Cartesian component order: libcint orders px,py,pz and
+    xx,xy,xz,yy,yz,zz; native_hf's cartesian_powers orders px,pz,py and
+    xx,xz,xy,zz,yz,yy.
+  - Normalization: libcint's raw Cartesian d components are not unit
+    self-overlap (xx/yy/zz vs. xy/xz/yz differ by exactly a factor of 3).
+    native_hf's primitive-normalized coefficients differ from libcint's
+    radial convention by a per-shell constant too. Both are removed by a
+    per-AO rescale computed from libcint's own overlap diagonal at call
+    time, exact for whatever exponent/element/degree is in play.
+Degrees above 2 raise NotImplementedError (native_hf itself caps at 2).
+"""
+import ctypes
+import os
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from dense_evolution.native_hf.basis import build_molecule_shells
+from dense_evolution.native_hf.cartesian import cartesian_powers
+
+_LIBCINT_CARTESIAN_ORDER = {
+    0: [(0, 0, 0)],
+    1: [(1, 0, 0), (0, 1, 0), (0, 0, 1)],
+    2: [(2, 0, 0), (1, 1, 0), (1, 0, 1), (0, 2, 0), (0, 1, 1), (0, 0, 2)],
+}
+_LIB_NAMES = {"win32": "libdecint.dll", "darwin": "libdecint.dylib"}
+_PTR_ENV_START = 20
+_POINT_NUC = 1
+_KINDS = {"ovlp": 0, "kin": 1, "nuc": 2}
+_lib = None
+
+
+def load_libcint() -> ctypes.CDLL:
+    """The bundled libcint + driver shared library (or DENSE_EVOLUTION_LIBCINT's),
+    loaded once; ImportError if neither exists."""
+    global _lib
+    if _lib is not None:
+        return _lib
+    path = os.environ.get("DENSE_EVOLUTION_LIBCINT") or str(
+        Path(__file__).with_name("_libcint") / _LIB_NAMES.get(sys.platform, "libdecint.so")
+    )
+    if not os.path.isfile(path):
+        raise ImportError(
+            f"native_hf.libcint_bridge needs the bundled libcint library, expected at {path}. "
+            "It ships inside the dense-evolution wheels for Windows, macOS and Linux "
+            "(pip install dense-evolution); for a source install, run "
+            ".github/scripts/build-libcint.sh and set DENSE_EVOLUTION_LIBCINT to the library file."
+        )
+    lib = ctypes.CDLL(path)
+    tail = [ctypes.c_void_p, ctypes.c_int, ctypes.c_void_p, ctypes.c_int, ctypes.c_void_p]
+    lib.de_int1e.argtypes = [ctypes.c_int, ctypes.c_void_p, ctypes.c_int] + [ctypes.c_void_p] * 3 + tail
+    lib.de_int1e.restype = None
+    lib.de_int2e.argtypes = [ctypes.c_void_p, ctypes.c_int] + [ctypes.c_void_p] * 3 + tail
+    lib.de_int2e.restype = None
+    _lib = lib
+    return lib
+
+
+def _permutation_libcint_to_native_hf(degree: int) -> np.ndarray:
+    """perm such that native_hf_ordered[i] == libcint_ordered[perm[i]]."""
+    if degree not in _LIBCINT_CARTESIAN_ORDER:
+        raise NotImplementedError(
+            f"libcint_bridge only has a verified AO-order mapping for degree <= 2; "
+            f"degree={degree} would need the same empirical check first, not an "
+            f"assumed extension of the pattern."
+        )
+    native_order = [tuple(int(x) for x in p) for p in cartesian_powers(degree)]
+    libcint_order = _LIBCINT_CARTESIAN_ORDER[degree]
+    return np.array([libcint_order.index(p) for p in native_order])
+
+
+class _Cint:
+    """atm/bas/env arrays for one molecule plus per-shell AO offsets, the
+    native_hf AO permutation, evaluated by the C driver."""
+
+    def __init__(self, atomic_numbers: list, geometry_bohr: np.ndarray, basis_name: str):
+        self.lib = load_libcint()
+        shells = build_molecule_shells(atomic_numbers, geometry_bohr, basis_name)
+        env = [0.0] * _PTR_ENV_START
+        atm, bas = [], []
+        for z, r in zip(atomic_numbers, np.asarray(geometry_bohr, dtype=float)):
+            atm.append([int(z), len(env), _POINT_NUC, len(env) + 3, 0, 0])
+            env.extend([r[0], r[1], r[2], 0.0])
+        for s in shells:
+            e = np.asarray(s.exponents, dtype=float)
+            c = np.asarray(s.coefficients, dtype=float)
+            bas.append([s.atom_index, s.degree, e.shape[0], 1, 0, len(env), len(env) + e.shape[0], 0])
+            env.extend(e)
+            env.extend(c)
+        self.atm = np.ascontiguousarray(atm, dtype=np.int32)
+        self.bas = np.ascontiguousarray(bas, dtype=np.int32)
+        self.env = np.ascontiguousarray(env, dtype=np.float64)
+        self.sizes = [len(cartesian_powers(s.degree)) for s in shells]
+        self.offsets = np.concatenate([[0], np.cumsum(self.sizes)]).astype(int)
+        self.n = int(self.offsets[-1])
+        self.perm = np.concatenate(
+            [o + _permutation_libcint_to_native_hf(s.degree) for o, s in zip(self.offsets, shells)]
+        )
+        self.ao_loc = np.ascontiguousarray(self.offsets, dtype=np.int32)
+        self.pos = np.ascontiguousarray(np.argsort(self.perm), dtype=np.int32)
+
+    def _tail(self):
+        return (self.atm.ctypes.data, self.atm.shape[0], self.bas.ctypes.data, self.bas.shape[0], self.env.ctypes.data)
+
+    def one(self, kind: str, r: np.ndarray, pos: np.ndarray) -> np.ndarray:
+        out = np.empty((self.n, self.n))
+        r = np.ascontiguousarray(r, dtype=np.float64)
+        self.lib.de_int1e(_KINDS[kind], out.ctypes.data, self.n, self.ao_loc.ctypes.data, r.ctypes.data, pos.ctypes.data, *self._tail())
+        return out
+
+    def rescale(self) -> np.ndarray:
+        S = self.one("ovlp", np.ones(self.n), np.arange(self.n, dtype=np.int32))
+        return 1.0 / np.sqrt(np.diag(S))
+
+    def two(self, r: np.ndarray) -> np.ndarray:
+        out = np.empty((self.n,) * 4)
+        self.lib.de_int2e(out.ctypes.data, self.n, self.ao_loc.ctypes.data, r.ctypes.data, self.pos.ctypes.data, *self._tail())
+        return out
+
+
+def build_overlap_and_core_hamiltonian_libcint(
+    atomic_numbers: list, geometry_bohr: np.ndarray, basis_name: str
+) -> tuple[np.ndarray, np.ndarray]:
+    """Same contract as assembly.build_overlap_matrix + build_core_hamiltonian
+    combined, computed via libcint. Returns (S, H_core) in native_hf's own AO
+    ordering/normalization, ready for scf.run_scf alongside
+    build_repulsion_tensor_libcint's output."""
+    c = _Cint(atomic_numbers, geometry_bohr, basis_name)
+    r = c.rescale()
+    return c.one("ovlp", r, c.pos), c.one("kin", r, c.pos) + c.one("nuc", r, c.pos)
+
+
+def build_repulsion_tensor_libcint(atomic_numbers: list, geometry_bohr: np.ndarray, basis_name: str) -> np.ndarray:
+    """Same contract as assembly.build_repulsion_tensor, computed via libcint
+    with 8-fold permutational symmetry; takes (atomic_numbers, geometry_bohr,
+    basis_name) rather than a shells list.
+
+    geometry_bohr: shape (n_atoms, 3), atomic units, same convention as
+    build_molecule_shells."""
+    c = _Cint(atomic_numbers, geometry_bohr, basis_name)
+    return c.two(c.rescale())

{dense_evolution-8.2.2 → dense_evolution-8.3.0}/dense_evolution/physics/__init__.py

@@ -7,7 +7,9 @@ from .entropy import partial_trace, von_neumann_entropy, mutual_information, cen
 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)
+                   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__ = [
@@ -19,5 +21,7 @@ __all__ = [
     "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-8.2.2 → dense_evolution-8.3.0}/dense_evolution/physics/qec.py

@@ -72,6 +72,7 @@ report a fractal dimension as absurd as 142 in 3 dimensions purely
 from fit noise, not from any real structure in the data.
 """
 import itertools
+from collections import deque
 from typing import Optional, Sequence
 
 import numpy as np
@@ -752,3 +753,361 @@ def nearest_coset_decode(measured_bits: str, coset_a: Sequence[str], coset_b: Se
     d_a = _min_hamming_distance(measured_bits, coset_a)
     d_b = _min_hamming_distance(measured_bits, coset_b)
     return 0 if d_a <= d_b else 1
+
+
+def estimate_edge_probabilities_from_detection_events(check_matrix, events) -> np.ndarray:
+    """Error probability of every qubit, from detection events (Spitz et al.).
+
+    Implements the exact inversion of S. T. Spitz, B. Tarasinski,
+    C. W. J. Beenakker and T. E. O'Brien, "Adaptive weight estimator for
+    quantum error correction in a time-dependent environment",
+    arXiv:1712.02360, Eqs. (13) and (16). For a code in which every qubit is
+    checked by at most two checks (repetition and surface codes), each qubit is
+    an edge between two checks, or between one check and the boundary. A qubit
+    shared by checks ``i`` and ``j`` has probability
+
+    ``p = 1/2 - sqrt(1/4 - (<v_i v_j> - <v_i><v_j>) / (1 - 2 <v_i xor v_j>))``
+
+    where ``v`` are the detection events and ``<.>`` the average over cycles. A
+    qubit on the boundary of check ``i`` has
+
+    ``p = 1/2 + (<v_i> - 1/2) / prod(1 - 2 p_ij)`` over the other qubits of ``i``.
+
+    The result can be passed as ``weights`` (``-log(p / (1 - p))``) to
+    `pymatching_decode`.
+
+    Parameters
+    ----------
+    check_matrix : array_like of shape (n_checks, n_qubits)
+        0/1 matrix, entry ``[c, q] = 1`` when check ``c`` detects an error on
+        qubit ``q``. Every column has one or two ones; no two qubits may join
+        the same pair of checks.
+    events : array_like of shape (n_cycles, n_checks)
+        0/1 detection events: ``1`` when a check changed value since the
+        previous cycle (the syndrome of one cycle's new errors).
+
+    Returns
+    -------
+    numpy.ndarray of shape (n_qubits,)
+        Estimated error probability of each qubit, clipped to [0, 0.5].
+
+    Raises
+    ------
+    ValueError
+        If the shapes do not match, ``events`` is not 0/1, a column of
+        ``check_matrix`` does not have one or two ones, or two qubits join the
+        same pair of checks.
+
+    Notes
+    -----
+    Valid for independent errors and one error type at a time. Needs about
+    ``1 / p`` cycles per qubit for a stable estimate (the paper's Eq. 18). A
+    pair of checks whose correlation is below the statistical noise gives a
+    probability near zero.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from dense_evolution.physics.qec import estimate_edge_probabilities_from_detection_events
+    >>> checks = np.array([[1, 0], [1, 1]])
+    >>> events = np.array([[1, 1]] * 20 + [[0, 0]] * 80)
+    >>> p = estimate_edge_probabilities_from_detection_events(checks, events)
+    >>> bool(p[0] < 0.5 and p[1] < 0.5)
+    True
+    """
+    h = np.asarray(check_matrix, dtype=int)
+    v = np.asarray(events, dtype=float)
+    if h.ndim != 2:
+        raise ValueError("check_matrix must be 2-D (n_checks, n_qubits)")
+    if v.ndim != 2 or v.shape[1] != h.shape[0]:
+        raise ValueError(
+            f"events must have shape (n_cycles, {h.shape[0]}), got {v.shape}"
+        )
+    if v.shape[0] == 0:
+        raise ValueError("events needs at least one cycle")
+    if not np.isin(v, (0.0, 1.0)).all():
+        raise ValueError("events must contain only 0 and 1")
+
+    n_q = h.shape[1]
+    ends = []
+    for q in range(n_q):
+        rows = np.flatnonzero(h[:, q])
+        if len(rows) not in (1, 2):
+            raise ValueError(
+                f"qubit {q} is checked by {len(rows)} checks; need one or two"
+            )
+        ends.append(tuple(int(r) for r in rows))
+    pairs = [e for e in ends if len(e) == 2]
+    if len(set(pairs)) != len(pairs):
+        raise ValueError("two qubits join the same pair of checks")
+
+    mean = v.mean(axis=0)
+    p = np.zeros(n_q)
+    for q, e in enumerate(ends):
+        if len(e) == 2:
+            i, j = e
+            cov = (v[:, i] * v[:, j]).mean() - mean[i] * mean[j]
+            xor = np.abs(v[:, i] - v[:, j]).mean()
+            denom = 1.0 - 2.0 * xor
+            inside = 0.25 - cov / denom if denom > 0 else 0.25
+            p[q] = 0.5 - np.sqrt(max(inside, 0.0))
+    for q, e in enumerate(ends):
+        if len(e) == 1:
+            i = e[0]
+            prod = 1.0
+            for r, other in enumerate(ends):
+                if len(other) == 2 and i in other:
+                    prod *= 1.0 - 2.0 * p[r]
+            if prod <= 0:
+                p[q] = 0.5
+            else:
+                p[q] = 0.5 + (mean[i] - 0.5) / prod
+    return np.clip(p, 0.0, 0.5)
+
+
+def erasure_ml_decode(
+    observed_syndrome: tuple,
+    heralded_qubits: Sequence[int],
+    n_qubits: int,
+    stabilizers: Sequence[str],
+) -> Optional[str]:
+    """Maximum-likelihood decoder for erasures at known locations, for any
+    stabilizer code.
+
+    With the erased qubits known, the error is supported on them, and the
+    syndrome becomes a linear system over GF(2) in the X and Z bits of those
+    qubits (Delfosse & Zemor, arXiv:1703.01517; Kuo & Ouyang,
+    arXiv:2411.13509). Solving it by Gaussian elimination costs O(n^3), where
+    `erasure_aware_decode` tries 4**m assignments for m erased qubits. Any
+    solution is a valid correction when every zero-syndrome operator on the
+    erased qubits is a stabilizer element, so degenerate errors (several
+    errors that differ by a stabilizer) are decoded too, not rejected.
+
+    Parameters
+    ----------
+    observed_syndrome : sequence of int
+        One bit per stabilizer, same convention as `compute_syndrome`.
+    heralded_qubits : sequence of int
+        Indices of the erased qubits.
+    n_qubits : int
+        Number of physical qubits.
+    stabilizers : sequence of str
+        Stabilizer generators as Pauli strings of length `n_qubits`.
+
+    Returns
+    -------
+    str or None
+        A Pauli string supported on the erased qubits that reproduces the
+        syndrome and is equivalent, up to a stabilizer, to every other
+        solution. `None` when no error on the erased qubits explains the
+        syndrome, or when the erased qubits contain a logical operator so the
+        correction is ambiguous. With no erased qubits it returns the identity
+        for a zero syndrome and `None` otherwise.
+
+    Raises
+    ------
+    ValueError
+        If the syndrome length does not match the stabilizers, a stabilizer
+        has the wrong length, or an erased index is out of range.
+
+    Examples
+    --------
+    >>> stabs = ['IIIXXXX', 'IXXIIXX', 'XIXIXIX', 'IIIZZZZ', 'IZZIIZZ', 'ZIZIZIZ']
+    >>> syndrome = compute_syndrome('XIIIIIX', stabs)
+    >>> erasure_ml_decode(syndrome, [0, 6], 7, stabs)
+    'XIIIIIX'
+    """
+    stabs = list(stabilizers)
+    if len(observed_syndrome) != len(stabs):
+        raise ValueError(
+            f"observed_syndrome has {len(observed_syndrome)} entries but there are "
+            f"{len(stabs)} stabilizers"
+        )
+    for i, s in enumerate(stabs):
+        if len(s) != n_qubits:
+            raise ValueError(f"stabilizers[{i}] has length {len(s)}, expected n_qubits={n_qubits}")
+    erased = sorted({int(q) for q in heralded_qubits})
+    if any(q < 0 or q >= n_qubits for q in erased):
+        raise ValueError(f"heralded_qubits must be in range(0, {n_qubits})")
+
+    syn = np.array(observed_syndrome, dtype=np.uint8) % 2
+    k = len(erased)
+    if k == 0:
+        return 'I' * n_qubits if not syn.any() else None
+
+    sym = np.array([_pauli_to_symplectic(s) for s in stabs], dtype=np.uint8)
+    sx, sz = sym[:, :n_qubits], sym[:, n_qubits:]
+    a = np.concatenate([sz[:, erased], sx[:, erased]], axis=1)
+    rref, pivots = _gf2_rref(np.concatenate([a, syn[:, None]], axis=1))
+    if 2 * k in pivots:
+        return None
+
+    sol = np.zeros(2 * k, dtype=np.uint8)
+    for row, col in enumerate(pivots):
+        sol[col] = rref[row, 2 * k]
+    free = [c for c in range(2 * k) if c not in pivots]
+    stab_rref, stab_pivots = _gf2_rref(sym)
+
+    def embed(v):
+        full = np.zeros(2 * n_qubits, dtype=np.uint8)
+        for j, q in enumerate(erased):
+            full[q] = v[j]
+            full[n_qubits + q] = v[k + j]
+        return full
+
+    for f in free:
+        vec = np.zeros(2 * k, dtype=np.uint8)
+        vec[f] = 1
+        for row, col in enumerate(pivots):
+            if rref[row, f]:
+                vec[col] = 1
+        if not _in_gf2_span(embed(vec), stab_rref, stab_pivots):
+            return None
+
+    full = embed(sol)
+    letters = {(0, 0): 'I', (1, 0): 'X', (0, 1): 'Z', (1, 1): 'Y'}
+    return ''.join(letters[(int(full[q]), int(full[n_qubits + q]))] for q in range(n_qubits))
+
+
+def _peel(h, erased, syn):
+    m = h.shape[0]
+    adj = {}
+    for q in erased:
+        rows = np.flatnonzero(h[:, q])
+        u, v = (int(rows[0]), int(rows[1])) if len(rows) == 2 else (int(rows[0]), m)
+        adj.setdefault(u, []).append((v, q))
+        adj.setdefault(v, []).append((u, q))
+    syn = [int(b) for b in syn] + [0]
+    seen, order, parent = set(), [], {}
+    starts = ([m] if m in adj else []) + [v for v in adj if v != m]
+    for s in starts:
+        if s in seen:
+            continue
+        seen.add(s)
+        queue = deque([s])
+        while queue:
+            u = queue.popleft()
+            order.append(u)
+            for v, q in adj[u]:
+                if v not in seen:
+                    seen.add(v)
+                    parent[v] = (u, q)
+                    queue.append(v)
+    corr = set()
+    for u in reversed(order):
+        if u in parent:
+            p, q = parent[u]
+            if syn[u]:
+                corr.add(q)
+                syn[p] ^= 1
+                syn[u] = 0
+        elif u != m and syn[u]:
+            return None
+    if any(syn[v] for v in range(m) if v not in seen):
+        return None
+    return corr
+
+
+def peeling_decode(stabilizers, observed_syndrome, heralded_qubits, n_qubits) -> Optional[str]:
+    """Peeling decoder for a CSS code whose X-type and Z-type checks each join
+    every qubit to at most two checks (repetition and surface codes)."""
+    stabs = list(stabilizers)
+    syn = np.array(observed_syndrome, dtype=np.uint8)
+    erased = sorted({int(q) for q in heralded_qubits})
+    zi = [i for i, s in enumerate(stabs) if 'Z' in s and 'X' not in s]
+    xi = [i for i, s in enumerate(stabs) if 'X' in s and 'Z' not in s]
+    hz = np.array([[c != 'I' for c in stabs[i]] for i in zi], dtype=np.uint8)
+    hx = np.array([[c != 'I' for c in stabs[i]] for i in xi], dtype=np.uint8)
+    x_part = _peel(hz, erased, syn[zi])
+    z_part = _peel(hx, erased, syn[xi])
+    if x_part is None or z_part is None:
+        return None
+    return ''.join('IXZY'[(q in x_part) + 2 * (q in z_part)] for q in range(n_qubits))
+
+
+def _uf_grow(h, erased, syn):
+    m, n = h.shape
+    ends = []
+    for q in range(n):
+        rows = np.flatnonzero(h[:, q])
+        ends.append((int(rows[0]), int(rows[1])) if len(rows) == 2 else (int(rows[0]), m))
+    parent = list(range(m + 1))
+
+    def find(x):
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    support = [0] * n
+    for q in erased:
+        support[q] = 2
+        parent[find(ends[q][0])] = find(ends[q][1])
+    s = [int(b) for b in syn] + [0]
+
+    def odd_roots():
+        par = {}
+        for v in range(m + 1):
+            r = find(v)
+            par[r] = par.get(r, 0) ^ s[v]
+        return {r for r, p in par.items() if p and r != find(m)}
+
+    odd = odd_roots()
+    while odd:
+        grown = False
+        for q in range(n):
+            if support[q] < 2:
+                ru, rv = find(ends[q][0]), find(ends[q][1])
+                inc = (ru in odd) + (rv in odd and rv != ru)
+                if inc:
+                    support[q] = min(2, support[q] + inc)
+                    grown = True
+        if not grown:
+            return None
+        for q in range(n):
+            if support[q] == 2:
+                parent[find(ends[q][0])] = find(ends[q][1])
+        odd = odd_roots()
+    return [q for q in range(n) if support[q] == 2]
+
+
+def _css_split(stabilizers, observed_syndrome):
+    stabs = list(stabilizers)
+    syn = np.array(observed_syndrome, dtype=np.uint8)
+    zi = [i for i, s in enumerate(stabs) if 'Z' in s and 'X' not in s]
+    xi = [i for i, s in enumerate(stabs) if 'X' in s and 'Z' not in s]
+    hz = np.array([[c != 'I' for c in stabs[i]] for i in zi], dtype=np.uint8)
+    hx = np.array([[c != 'I' for c in stabs[i]] for i in xi], dtype=np.uint8)
+    return hz, syn[zi], hx, syn[xi]
+
+
+def union_find_decode(stabilizers, observed_syndrome, heralded_qubits, n_qubits) -> Optional[str]:
+    """Union-Find decoder with erasures and Pauli errors (Delfosse and
+    Nickerson, arXiv:1709.06218): clusters start from the erased qubits and
+    grow by half-edges until every cluster has even syndrome parity or touches
+    the boundary, then each grown cluster is peeled."""
+    hz, sz, hx, sx = _css_split(stabilizers, observed_syndrome)
+    erased = sorted({int(q) for q in heralded_qubits})
+    parts = []
+    for h, s in ((hz, sz), (hx, sx)):
+        grown = _uf_grow(h, erased, s)
+        if grown is None:
+            return None
+        part = _peel(h, grown, s)
+        if part is None:
+            return None
+        parts.append(part)
+    return ''.join('IXZY'[(q in parts[0]) + 2 * (q in parts[1])] for q in range(n_qubits))
+
+
+def matching_erasure_decode(stabilizers, observed_syndrome, heralded_qubits, n_qubits) -> str:
+    """Minimum-weight perfect matching with weight 0 on the erased qubits
+    (Stace, Barrett and Doherty, arXiv:0904.3556), via pymatching."""
+    import pymatching
+
+    hz, sz, hx, sx = _css_split(stabilizers, observed_syndrome)
+    w = np.ones(n_qubits)
+    w[list(heralded_qubits)] = 0.0
+    xp = pymatching.Matching.from_check_matrix(hz, weights=w).decode(sz)
+    zp = pymatching.Matching.from_check_matrix(hx, weights=w).decode(sx)
+    return ''.join('IXZY'[int(xp[q]) + 2 * int(zp[q])] for q in range(n_qubits))