tridec 0.1.0a1__py3-none-any.whl

tridec/__init__.py

@@ -0,0 +1,42 @@
+"""tridec: vendor-portable GPU decoders for quantum LDPC codes.
+
+Triton min-sum BP and Relay-BP decoders that consume any stim
+DetectorErrorModel or raw parity-check matrices, with CPU reference
+implementations, validated against the standard CPU references (ldpc,
+relay-bp), running on NVIDIA (CUDA) and AMD (ROCm) GPUs.
+
+Quickstart::
+
+    import stim, tridec
+
+    circuit = stim.Circuit.from_file("memory.stim")
+    dem = circuit.detector_error_model(decompose_errors=False)
+    decoder = tridec.from_dem(dem, backend="auto")
+
+    dets, obs = circuit.compile_detector_sampler(seed=0).sample(
+        10_000, separate_observables=True)
+    pred = decoder.decode_batch(dets)            # (shots, n_obs) bool
+    ler = (pred != obs).any(axis=1).mean()
+"""
+from .api import (
+    BpDecoder,
+    RelayBpDecoder,
+    available_backends,
+    from_dem,
+    from_matrices,
+    resolve_backend,
+)
+from .dem import extract
+
+__version__ = "0.1.0.dev0"
+
+__all__ = [
+    "BpDecoder",
+    "RelayBpDecoder",
+    "available_backends",
+    "extract",
+    "from_dem",
+    "from_matrices",
+    "resolve_backend",
+    "__version__",
+]

tridec/adapters/__init__.py

@@ -0,0 +1,258 @@
+"""Optional CPU reference-decoder adapters on a SHARED DEM (import-guarded).
+
+These wrap the standard CPU reference implementations — the `ldpc` package's
+BP / BP-OSD / BP-LSD and IBM's `relay-bp` Rust decoder — behind the same
+``decode_batch(dets) -> predicted_observables`` surface as the native
+backends, so a matched harness (``tridec.validation.run_matched``) can
+decode the SAME shots with every decoder (apples-to-apples LER). They are the
+validation targets the GPU kernels are held against.
+
+Install with the ``decoders`` extra: ``pip install tridec[decoders]``.
+The module imports without either package; each factory raises (or the
+``*_available()`` probes return False) when its dependency is missing.
+
+Interface (every adapter):
+  * ``.name``    -- str identifier (e.g. ``"BPOSD-10"``),
+  * ``.config``  -- dict of pinned hyperparameters (provenance),
+  * ``.dem``     -- the shared ``stim.DetectorErrorModel`` it was built from,
+  * ``.tie_break`` -- declared deterministic tie-break (gate G2),
+  * ``.decode_batch(dets: bool[shots, n_det]) -> bool[shots, n_obs]``.
+
+For an ldpc decoder, each shot's detector syndrome is decoded to an error
+estimate ``e_hat`` (length n_err); predicted observables = ``(Lo @ e_hat) % 2``.
+ldpc 2.4.x exposes only single-shot ``decoder.decode(syndrome)`` (no batched
+entry point), so ldpc adapters loop over shots.
+"""
+import numpy as np
+
+from ..dem import extract
+
+# Pinned min-sum BP hyperparameters shared across the BP-family adapters
+# (the provenance constants the validation grid committed to).
+_BP_MAX_ITER = 30
+_BP_MS_SCALING = 0.625          # standard normalized-min-sum scaling factor
+_BP_METHOD = "minimum_sum"      # min-sum BP (the kernel target)
+_BP_SCHEDULE = "parallel"
+
+
+def ldpc_available():
+    """True iff the `ldpc` package is importable."""
+    try:
+        import ldpc  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+def relay_bp_available():
+    """True iff relay-bp[stim] is importable (import-guarded membership)."""
+    try:
+        import relay_bp  # noqa: F401
+        from relay_bp.stim import CheckMatrices  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+class _LdpcAdapter:
+    """Base for ldpc-family adapters: build H/Lo/priors from the shared DEM,
+    decode each shot's syndrome to an error estimate, map to observables."""
+
+    def __init__(self, dem, name, config, decoder, tie_break):
+        self.dem = dem
+        self.name = name
+        self.config = dict(config)
+        # Declared deterministic tie-break (gate G2). No silent default: the
+        # matched harness asserts this is in APPROVED_TIE_BREAKS.
+        self.tie_break = tie_break
+        self._decoder = decoder
+        ex = extract(dem)
+        # Lo: (n_obs x n_err) GF2 map from error mechanisms to observables.
+        self._Lo = ex["Lo"].toarray().astype(np.uint8)
+        self._n_obs = ex["n_obs"]
+        self._n_err = ex["n_err"]
+        self._n_det = ex["n_det"]
+
+    def decode_batch(self, dets):
+        dets = np.asarray(dets, dtype=bool)
+        shots = dets.shape[0]
+        out = np.zeros((shots, self._n_obs), dtype=bool)
+        syn_u8 = dets.astype(np.uint8)
+        Lo = self._Lo
+        for i in range(shots):
+            e_hat = self._decoder.decode(syn_u8[i])
+            # predicted observables = (Lo @ e_hat) % 2
+            pred = (Lo @ np.asarray(e_hat, dtype=np.uint8)) & 1
+            out[i] = pred.astype(bool)
+        return out
+
+
+def _priors(dem):
+    """Per-mechanism priors from the shared DEM, clipped for ldpc stability."""
+    pri = extract(dem)["priors"]
+    return list(np.clip(pri, 1e-6, 1 - 1e-6))
+
+
+def make_bp(dem):
+    """Pure min-sum BP (no post-processing): ldpc.BpDecoder reference."""
+    from ldpc import BpDecoder
+
+    H = extract(dem)["H"]
+    cfg = dict(decoder="BpDecoder", bp_method=_BP_METHOD,
+               ms_scaling_factor=_BP_MS_SCALING, max_iter=_BP_MAX_ITER,
+               schedule=_BP_SCHEDULE)
+    dec = BpDecoder(H, error_channel=_priors(dem), max_iter=_BP_MAX_ITER,
+                    bp_method=_BP_METHOD, ms_scaling_factor=_BP_MS_SCALING,
+                    schedule=_BP_SCHEDULE)
+    return _LdpcAdapter(dem, "BP", cfg, dec, "min_sum_parallel_hard_decision")
+
+
+def make_bposd0(dem):
+    """BP-OSD order-0 (osd_0): cheapest OSD post-processing."""
+    from ldpc import BpOsdDecoder
+
+    H = extract(dem)["H"]
+    cfg = dict(decoder="BpOsdDecoder", bp_method=_BP_METHOD,
+               ms_scaling_factor=_BP_MS_SCALING, max_iter=_BP_MAX_ITER,
+               schedule=_BP_SCHEDULE, osd_method="osd_0", osd_order=0)
+    dec = BpOsdDecoder(H, error_channel=_priors(dem), max_iter=_BP_MAX_ITER,
+                       bp_method=_BP_METHOD, ms_scaling_factor=_BP_MS_SCALING,
+                       schedule=_BP_SCHEDULE, osd_method="osd_0", osd_order=0)
+    return _LdpcAdapter(dem, "BPOSD-0", cfg, dec, "osd0_reliability_order")
+
+
+def make_bposd10(dem):
+    """BP-OSD order-10 combination-sweep (osd_cs): the strong classical bar."""
+    from ldpc import BpOsdDecoder
+
+    H = extract(dem)["H"]
+    cfg = dict(decoder="BpOsdDecoder", bp_method=_BP_METHOD,
+               ms_scaling_factor=_BP_MS_SCALING, max_iter=_BP_MAX_ITER,
+               schedule=_BP_SCHEDULE, osd_method="osd_cs", osd_order=10)
+    dec = BpOsdDecoder(H, error_channel=_priors(dem), max_iter=_BP_MAX_ITER,
+                       bp_method=_BP_METHOD, ms_scaling_factor=_BP_MS_SCALING,
+                       schedule=_BP_SCHEDULE, osd_method="osd_cs", osd_order=10)
+    return _LdpcAdapter(dem, "BPOSD-10", cfg, dec, "osd_cs_order10")
+
+
+def make_bplsd(dem):
+    """BP + Localised-Statistics Decoder (lsd_cs, order 10)."""
+    from ldpc import BpLsdDecoder
+
+    H = extract(dem)["H"]
+    lsd_order = 10
+    cfg = dict(decoder="BpLsdDecoder", bp_method=_BP_METHOD,
+               ms_scaling_factor=_BP_MS_SCALING, max_iter=_BP_MAX_ITER,
+               schedule=_BP_SCHEDULE, lsd_method="lsd_cs", lsd_order=lsd_order)
+    dec = BpLsdDecoder(H, error_channel=_priors(dem), max_iter=_BP_MAX_ITER,
+                       bp_method=_BP_METHOD, ms_scaling_factor=_BP_MS_SCALING,
+                       schedule=_BP_SCHEDULE, lsd_method="lsd_cs",
+                       lsd_order=lsd_order)
+    return _LdpcAdapter(dem, "BPLSD", cfg, dec, "lsd_cs_order10")
+
+
+# --------------------------------------------------------------------------- #
+# Relay-BP (relay-bp[stim] >= 0.2.2) — IBM's Rust reference decoder.            #
+# --------------------------------------------------------------------------- #
+# Construct-from-DEM:
+#   from relay_bp.stim import CheckMatrices
+#   cm = CheckMatrices.from_dem(dem)        # -> .check_matrix (ndet x E csc),
+#                                           #    .observables_matrix (nobs x E csc),
+#                                           #    .error_priors (E,)
+#   dec = relay_bp.RelayDecoderF64(cm.check_matrix, error_priors=cm.error_priors,
+#             gamma0=, pre_iter=, num_sets=, set_max_iter=, gamma_dist_interval=,
+#             stop_nconv=, stopping_criterion='nconv')   # disjoint-relay ensemble
+#   runner = relay_bp.ObservableDecoderRunner(dec, cm.observables_matrix,
+#                                             include_decode_result=False)
+# Decode:
+#   runner.decode_observables_batch(syndromes uint8 [shots, n_det])
+#       -> predicted observables uint8 [shots, n_obs]
+# This is the path relay_bp.stim.SinterDecoder_RelayBP uses internally, minus
+# sinter's bit-packing — the runner is driven directly for a clean decode_batch.
+_RELAY_BP_DEFAULTS = dict(
+    gamma0=0.1,
+    pre_iter=80,
+    num_sets=60,
+    set_max_iter=60,
+    gamma_dist_interval=(-0.24, 0.66),
+    stop_nconv=5,
+    stopping_criterion="nconv",
+)
+
+
+class RelayBPAdapter:
+    """Relay-BP adapter (in-process). Builds the relay-BP decoder from the SAME
+    shared DEM via ``relay_bp.stim.CheckMatrices.from_dem`` and decodes a batch
+    of syndromes straight to observables. G1 holds trivially: ``.dem is dem``."""
+
+    def __init__(self, dem, **params):
+        import importlib.metadata as _md
+
+        import relay_bp
+        from relay_bp.stim import CheckMatrices
+
+        self.dem = dem
+        self.name = "RelayBP"
+        try:
+            ver = _md.version("relay-bp")
+        except Exception:  # pragma: no cover - metadata present once installed
+            ver = "unknown"
+        cfg = dict(_RELAY_BP_DEFAULTS)
+        cfg.update(params)
+        self.config = dict(decoder="RelayBP", relay_bp_version=ver, **cfg)
+        # Deterministic relay schedule (fixed gamma distribution + nconv stop).
+        self.tie_break = "relay_bp_nconv_disjoint_ensemble"
+
+        cm = CheckMatrices.from_dem(dem)
+        self._n_obs = cm.observables_matrix.shape[0]
+        decoder = relay_bp.RelayDecoderF64(
+            cm.check_matrix,
+            error_priors=cm.error_priors,
+            **cfg,
+        )
+        self._runner = relay_bp.ObservableDecoderRunner(
+            decoder, cm.observables_matrix, include_decode_result=False)
+
+    def decode_batch(self, dets):
+        dets = np.asarray(dets, dtype=bool)
+        pred = np.asarray(
+            self._runner.decode_observables_batch(dets.astype(np.uint8)))
+        pred = (pred % 2).astype(bool)
+        if pred.ndim == 1:
+            pred = pred.reshape(-1, 1)
+        return pred
+
+
+def make_relay_bp(dem, **params):
+    return RelayBPAdapter(dem, **params)
+
+
+# Registry: name -> factory(dem).
+_FACTORIES = {
+    "BPOSD-0": make_bposd0,
+    "BPOSD-10": make_bposd10,
+    "BPLSD": make_bplsd,
+    "BP": make_bp,
+}
+
+DEFAULT_DECODERS = ("BPOSD-0", "BPOSD-10", "BPLSD", "BP")
+
+
+def build_decoders(dem, which=DEFAULT_DECODERS, include_relay=False):
+    """Construct all requested adapters from ONE shared DEM object.
+
+    Every returned adapter has ``.dem is dem`` (provenance for the matched
+    harness). ``which`` selects/orders the ldpc-family adapters by registry
+    name. Relay-BP is OPT-IN via ``include_relay=True`` and is added ONLY when
+    its package is available (import-guarded), so the core set always builds.
+    """
+    decoders = []
+    for name in which:
+        if name not in _FACTORIES:
+            raise KeyError(f"unknown decoder {name!r}; known: {sorted(_FACTORIES)}")
+        decoders.append(_FACTORIES[name](dem))
+
+    if include_relay and relay_bp_available():
+        decoders.append(make_relay_bp(dem))
+
+    return decoders

tridec/api.py

@@ -0,0 +1,337 @@
+"""Public decoder API: ``from_dem`` / ``from_matrices`` + backend dispatch.
+
+Backends
+--------
+  * ``"numpy"``  — pure-numpy normalized-min-sum BP (always available; the
+                   CPU reference the GPU paths are validated against).
+  * ``"torch"``  — batched torch edge-list BP; bit-identical to numpy at fp64
+                   for one iteration; runs on CPU and CUDA/ROCm devices.
+  * ``"triton"`` — the Triton kernels (min-sum BP and Relay-BP); requires
+                   triton + a CUDA or ROCm GPU. fp32 messages on the BP path
+                   (>=99.5% hard-decision agreement vs the fp64 references,
+                   LER-validated on H200 and MI300X — see bench/receipts/).
+  * ``"auto"``   — triton if importable AND a GPU is visible, else torch if
+                   importable, else numpy.
+
+Algorithms per backend (honest availability matrix):
+
+  ===========  =======  =======  ========
+  algorithm     numpy    torch    triton
+  ===========  =======  =======  ========
+  bp (min-sum)   yes      yes      yes
+  relay          no       no       yes
+  ===========  =======  =======  ========
+
+Relay-BP has no in-package CPU implementation; its CPU reference is IBM's
+``relay-bp`` Rust decoder, available through ``tridec.adapters`` (the
+``decoders`` extra) and used as the validation oracle for the Triton path.
+"""
+import numpy as np
+import scipy.sparse as sp
+
+from .dem import extract
+
+_BACKENDS = ("auto", "numpy", "torch", "triton")
+
+# Validated defaults (the configuration the carried receipts were measured at).
+_BP_DEFAULTS = dict(max_iter=30, ms_scaling_factor=0.625)
+_RELAY_DEFAULTS = dict(
+    gamma0=0.1,
+    pre_iter=80,
+    num_sets=60,
+    set_max_iter=60,
+    gamma_dist_interval=(-0.24, 0.66),
+    stop_nconv=5,
+    stopping_criterion="nconv",
+)
+
+
+# --------------------------------------------------------------------------- #
+# Backend availability / resolution.                                           #
+# --------------------------------------------------------------------------- #
+def _torch_available():
+    try:
+        import torch  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def _triton_gpu_available():
+    try:
+        import triton  # noqa: F401
+        import torch
+        return bool(torch.cuda.is_available())
+    except Exception:
+        return False
+
+
+def available_backends():
+    """The backends usable in THIS environment, best first."""
+    out = []
+    if _triton_gpu_available():
+        out.append("triton")
+    if _torch_available():
+        out.append("torch")
+    out.append("numpy")
+    return out
+
+
+def resolve_backend(backend="auto"):
+    """Resolve a backend request to a concrete backend name.
+
+    ``"auto"`` -> triton if importable AND a GPU (CUDA or ROCm) is visible,
+    else torch if importable, else numpy. Explicitly requesting an unavailable
+    backend raises RuntimeError with the reason.
+    """
+    if backend not in _BACKENDS:
+        raise ValueError(
+            f"unknown backend {backend!r}; expected one of {_BACKENDS}")
+    if backend == "auto":
+        if _triton_gpu_available():
+            return "triton"
+        if _torch_available():
+            return "torch"
+        return "numpy"
+    if backend == "torch" and not _torch_available():
+        raise RuntimeError(
+            "torch backend requested but torch is not importable; "
+            "install with the [torch] extra: pip install tridec[torch]")
+    if backend == "triton" and not _triton_gpu_available():
+        raise RuntimeError(
+            "triton backend requested but triton + a CUDA/ROCm GPU are not "
+            "available (triton importable: requires the [gpu] extra; GPU "
+            "visible: torch.cuda.is_available() must be True)")
+    return backend
+
+
+def _default_device(backend, device):
+    if device is not None:
+        return device
+    if backend == "triton":
+        return "cuda"
+    if backend == "torch":
+        try:
+            import torch
+            return "cuda" if torch.cuda.is_available() else "cpu"
+        except Exception:  # pragma: no cover
+            return "cpu"
+    return "cpu"
+
+
+def _dense_uint8(M):
+    if M is None:
+        return None
+    if sp.issparse(M):
+        M = M.toarray()
+    return (np.asarray(M, dtype=np.uint8) % 2)
+
+
+# --------------------------------------------------------------------------- #
+# Decoders.                                                                    #
+# --------------------------------------------------------------------------- #
+class BpDecoder:
+    """Normalized min-sum BP over the numpy / torch / triton backends.
+
+    Construct via ``tridec.from_dem`` / ``tridec.from_matrices``
+    (or directly). ``decode_batch(dets)`` returns predicted observables
+    (bool[shots, n_obs]) when an observable map is available (always the case
+    via ``from_dem``), else hard error estimates (uint8[shots, n_bits]).
+    """
+
+    algorithm = "bp"
+
+    def __init__(self, H, priors, observables=None, backend="auto", device=None,
+                 max_iter=30, ms_scaling_factor=0.625, block_s=256, dem=None):
+        self.backend = resolve_backend(backend)
+        self.device = _default_device(self.backend, device)
+        self.dem = dem
+        self.max_iter = int(max_iter)
+        self.ms_scaling_factor = float(ms_scaling_factor)
+
+        if self.backend == "numpy":
+            from .backends.bp_numpy import BpBaseline
+            self._impl = BpBaseline(H, priors, max_iter=max_iter,
+                                    ms_scaling_factor=ms_scaling_factor)
+        elif self.backend == "torch":
+            from .backends.bp_torch import BpGpu
+            self._impl = BpGpu(H, priors, max_iter=max_iter,
+                               ms_scaling_factor=ms_scaling_factor)
+        else:  # triton
+            from .backends.bp_triton import BpTriton
+            self._impl = BpTriton(H, priors, max_iter=max_iter,
+                                  ms_scaling_factor=ms_scaling_factor,
+                                  block_s=block_s)
+
+        Lo = _dense_uint8(observables)
+        self._Lo = Lo
+        if Lo is not None:
+            # Attach the observable map to the backend impl so its validated
+            # decode_batch path (e_hat -> (Lo @ e_hat) % 2) applies unchanged.
+            self._impl._Lo = Lo
+            self._impl._n_obs = int(Lo.shape[0])
+        self.n_obs = None if Lo is None else int(Lo.shape[0])
+        self.n_bits = self._impl.n_bits
+        self.n_checks = self._impl.n_checks
+
+        self.name = f"portable-bp[{self.backend}]"
+        self.tie_break = "min_sum_parallel_hard_decision"
+        self.config = dict(
+            decoder="tridec.BpDecoder", backend=self.backend,
+            bp_method="minimum_sum", ms_scaling_factor=self.ms_scaling_factor,
+            max_iter=self.max_iter, schedule="parallel")
+
+    @classmethod
+    def from_dem(cls, dem, backend="auto", device=None, **opts):
+        kw = dict(_BP_DEFAULTS)
+        kw.update(opts)
+        ex = extract(dem)
+        obj = cls(ex["H"], ex["priors"], observables=ex["Lo"], backend=backend,
+                  device=device, dem=dem, **kw)
+        return obj
+
+    # -- decode surfaces ---------------------------------------------------- #
+    def decode_batch(self, detection_events):
+        """Decode a batch of detector-event vectors.
+
+        Returns predicted observables (bool[shots, n_obs]) when an observable
+        map is present, else hard error estimates (uint8[shots, n_bits]).
+        """
+        dets = np.asarray(detection_events)
+        if dets.ndim == 1:
+            dets = dets[None, :]
+        if self._Lo is not None:
+            if self.backend == "numpy":
+                return self._impl.decode_batch(dets.astype(bool))
+            return self._impl.decode_batch(dets.astype(bool), device=self.device)
+        # No observable map: return hard error estimates.
+        syn = dets.astype(np.uint8)
+        if self.backend == "numpy":
+            out = np.zeros((syn.shape[0], self.n_bits), dtype=np.uint8)
+            for i in range(syn.shape[0]):
+                out[i] = self._impl.decode(syn[i])
+            return out
+        post = self._impl.run_iterations_batch(syn, n_iter=self.max_iter,
+                                               device=self.device)
+        return (post < 0.0).astype(np.uint8)
+
+    def decode(self, detection_events):
+        """Single-shot convenience: 1-D in, 1-D out."""
+        out = self.decode_batch(np.asarray(detection_events)[None, :])
+        return out[0]
+
+
+class RelayBpDecoder:
+    """Relay-BP (disordered-memory min-sum relay ensemble), Triton backend only.
+
+    Defaults match the ``relay_bp`` Rust oracle configuration the kernels were
+    LER-validated against (gamma0=0.1, pre_iter=80, num_sets=60,
+    set_max_iter=60, gamma_dist_interval=(-0.24, 0.66), stop_nconv=5).
+    """
+
+    algorithm = "relay"
+
+    def __init__(self, H, priors, observables=None, backend="auto", device=None,
+                 block_s=256, dtype="float64", dem=None, **relay_params):
+        resolved = resolve_backend(backend)
+        if resolved != "triton":
+            raise NotImplementedError(
+                f"Relay-BP is implemented on the triton backend only (resolved "
+                f"backend: {resolved!r}). There is no in-package CPU Relay-BP; "
+                f"for a CPU reference use the relay-bp adapter "
+                f"(tridec.adapters.make_relay_bp, [decoders] extra).")
+        self.backend = "triton"
+        self.device = _default_device("triton", device)
+        self.dem = dem
+
+        cfg = dict(_RELAY_DEFAULTS)
+        cfg.update(relay_params)
+        from .backends.relay_triton import RelayBpTriton
+        self._impl = RelayBpTriton(H, priors, block_s=block_s, dtype=dtype,
+                                   **cfg)
+
+        Lo = _dense_uint8(observables)
+        self._Lo = Lo
+        if Lo is not None:
+            self._impl._Lo = Lo
+            self._impl._n_obs = int(Lo.shape[0])
+        self.n_obs = None if Lo is None else int(Lo.shape[0])
+        self.n_bits = self._impl.n_bits
+        self.n_checks = self._impl.n_checks
+
+        self.name = "portable-relay-bp[triton]"
+        self.tie_break = "relay_bp_nconv_disjoint_ensemble"
+        self.config = dict(
+            decoder="tridec.RelayBpDecoder", backend="triton",
+            dtype=dtype, **cfg)
+
+    @classmethod
+    def from_dem(cls, dem, backend="auto", device=None, **opts):
+        ex = extract(dem)
+        return cls(ex["H"], ex["priors"], observables=ex["Lo"], backend=backend,
+                   device=device, dem=dem, **opts)
+
+    def decode_batch(self, detection_events):
+        dets = np.asarray(detection_events)
+        if dets.ndim == 1:
+            dets = dets[None, :]
+        if self._Lo is not None:
+            return self._impl.decode_batch(dets.astype(bool), device=self.device)
+        # No observable map: return the lowest-weight valid error estimate.
+        import torch
+        dev = torch.device(self.device)
+        syn_t = torch.as_tensor(dets.astype(bool), device=dev)
+        best_eh = self._impl._relay_posteriors(syn_t, dev)       # (N, S)
+        return best_eh.t().cpu().numpy().astype(np.uint8)
+
+    def decode(self, detection_events):
+        out = self.decode_batch(np.asarray(detection_events)[None, :])
+        return out[0]
+
+
+# --------------------------------------------------------------------------- #
+# Factories.                                                                   #
+# --------------------------------------------------------------------------- #
+def from_dem(dem, backend="auto", algorithm="bp", device=None, **opts):
+    """Build a decoder from a ``stim.DetectorErrorModel``.
+
+    Args:
+        dem: the DEM (build with ``decompose_errors=False`` — the decoders
+            consume the raw hyperedge mechanism set).
+        backend: "auto" | "numpy" | "torch" | "triton" (see module docstring).
+        algorithm: "bp" (min-sum BP, all backends) or "relay" (Relay-BP,
+            triton backend only).
+        device: optional torch device string for the torch/triton backends.
+        **opts: decoder hyperparameters (e.g. max_iter, ms_scaling_factor for
+            bp; gamma0, pre_iter, num_sets, ... for relay).
+
+    Returns a decoder with ``decode_batch(detection_events) ->
+    predicted_observables`` and a single-shot ``decode``.
+    """
+    if algorithm == "bp":
+        return BpDecoder.from_dem(dem, backend=backend, device=device, **opts)
+    if algorithm == "relay":
+        return RelayBpDecoder.from_dem(dem, backend=backend, device=device,
+                                       **opts)
+    raise ValueError(f"unknown algorithm {algorithm!r}; expected 'bp' or 'relay'")
+
+
+def from_matrices(H, priors, observables=None, backend="auto", algorithm="bp",
+                  device=None, **opts):
+    """Build a decoder from a raw GF2 parity-check matrix + per-bit priors.
+
+    Args:
+        H: (n_checks x n_bits) GF2 check matrix (dense or scipy sparse).
+        priors: per-bit error probabilities, length n_bits.
+        observables: optional (n_obs x n_bits) GF2 observable map. With it,
+            ``decode_batch`` returns predicted observables; without it, hard
+            error estimates.
+        backend, algorithm, device, **opts: as in ``from_dem``.
+    """
+    if algorithm == "bp":
+        return BpDecoder(H, priors, observables=observables, backend=backend,
+                         device=device, **opts)
+    if algorithm == "relay":
+        return RelayBpDecoder(H, priors, observables=observables,
+                              backend=backend, device=device, **opts)
+    raise ValueError(f"unknown algorithm {algorithm!r}; expected 'bp' or 'relay'")

tridec/backends/__init__.py

@@ -0,0 +1,11 @@
+"""Decoder backends.
+
+``bp_numpy`` is always importable (numpy/scipy only). ``bp_torch`` requires
+torch; ``bp_triton`` / ``relay_triton`` additionally require triton and a GPU
+to RUN (they import without one — the kernels compile only where triton
+exists). The API layer (``tridec.api``) imports the optional backends
+lazily, so a missing extra never breaks the core package.
+"""
+from .bp_numpy import BpBaseline
+
+__all__ = ["BpBaseline"]