Python API reference

Construct the distance-l toric code [[2l², 2, l]]. The plumbing warmup — needs no external dependencies.

✓ B1 reproduces Roffe 2020's 9.9 ± 0.2% threshold.

Construct the [[144, 12, 12]] bivariate-bicycle "gross code" (Bravyi et al., Nature 2024; literature note 002). n=144, k=12, weight-6, CSS.

✓ Validated: B3.

class Code

A CSS code with its decoder attached. Decoding targets the X-error sector: the syndrome comes from Hz, and the logical-failure test is against rowspace(Hx).

glean.simulate_toric

Code-capacity Monte-Carlo on the toric code. Returns (failures, shots, logical_error_rate, stderr).

failures, shots, ler, stderr = glean.simulate_toric(l=6, p=0.05, shots=5000)

glean.load_dem

Ingest a flattened Stim DEM string — the text of circuit.detector_error_model(flatten_loops=True). num_detectors and num_observables are the authoritative counts from the DEM (literature note 001).

class DetectorErrorModel

Decodes detector syndromes into predicted logical-observable flips. The Tanner graph is built once and cached on the object, then reused across every decode.

Accessors (properties, no parentheses)

The validated baseline — B3: == Roffe's ldpc to 99.8% / <0.4σ on the gross code.

import glean, stim, numpy as np

circuit = stim.Circuit.generated(
    "surface_code:rotated_memory_z", distance=5, rounds=5,
    after_clifford_depolarization=1e-3)
dem = circuit.detector_error_model(flatten_loops=True)

g = glean.load_dem(str(dem), dem.num_detectors, dem.num_observables)
sampler = circuit.compile_detector_sampler()
det, obs = sampler.sample(shots=10_000, separate_observables=True)

pred = np.asarray(g.decode_batch(det.tolist(), osd_order=10, parallel=True))
ler = (pred != obs).any(axis=1).mean()

The OSD-free, real-time differentiator — B4: == the authors' relay_bp crate, <0.95σ; real-time iteration budget met.

gamma_dist is the (low, high) uniform memory-disorder interval. stop_nconv is the "-S" in "Relay-BP-S" (the number of converged relay legs to ensemble). The returned per-shot iteration count is the real-time budget metric (B4: median 16 / p90 212 ≪ 600).

pred, iters = g.decode_batch_relay(
    det.tolist(), gamma0=0.1, pre_iter=80, num_sets=60, set_max_iter=60,
    gamma_dist=(-0.24, 0.66), stop_nconv=5, alpha=1.0, seed=0, parallel=True)
# iters[i] = total BP iterations the decoder spent on shot i.

glean.load_bp_otf

Build a BP+OTF decoder from the full + sparsified flattened DEM texts and the transfer-matrix incidence merge_entries (each (k, j): full-DEM fault k piles into sparsified fault j).

class BpOtf

A single BP+OTF decoder undershoots BP+OSD-0 (note 006 §IV expected); the published accuracy is recovered by a 23-member ensemble of decoders over different sparsified DEMs — see bp_otf_gross.py.

Heußen, Winter, Rispler, Müller, Phys. Rev. Research 6, 013177 (2024); literature note 007. Estimates p_L(p) = Σ_w A_w · p_fail^(w) by stratifying on the fault weight w: the weight probabilities A_w are exact and decoder-independent (Poisson–binomial of the priors), so only the few contributing low-w classes (w ≳ d/2) need sampling.

✓ B8 — unbiased, 0.0σ vs direct MC at p=3×10⁻³.

decode_fn(syndromes) is any decoder: syndromes is a list[list[int]], the return is array-like (len(syndromes), num_observables). For relay-BP, wrap to drop the iteration counts. DssEstimate fields: p_L, err, p_L_lo, p_L_hi (rigorous truncation bracket), w_max, tail_mass, classes, total_shots.

import glean, numpy as np

g = glean.load_dem(dem_text, n_det, n_obs)
decode_fn = lambda s: np.asarray(g.decode_batch(s, osd_order=10, parallel=True))

est = glean.dss.estimate(g, decode_fn, weights=range(1, 13), shots=50_000)
print(est.p_L, "+/-", est.err, "bracket", (est.p_L_lo, est.p_L_hi))

# Trace a curve from ONE decode campaign (p_fail^(w) is p-independent):
table = glean.dss.sample_pfail(g, decode_fn, weights=range(1, 13), shots=50_000)
for p in (1e-3, 2e-3, 3e-3):
    g_p = glean.load_dem(build_dem_at(p), n_det, n_obs)   # your DEM rebuilt at rate p
    A = glean.dss.weight_probs(g_p, w_max=12)             # A_w depends on p; p_fail^(w) does not
    print(p, glean.dss.combine(table, A).p_L)

DEM-level primitives (on DetectorErrorModel)

• dss_weight_probs(w_max) → A_w[0..w_max] — decoder-independent Poisson–binomial pmf.
• dss_sample(w, count, seed=0) → (syndromes, true_observable_flips) — draw count fault sets of exactly weight w from Pr(S) ∝ ∏_{i∈S} p_i/(1−p_i), then decode + compare for p_fail^(w).

Bravyi & Vargo, Phys. Rev. A 88, 062308 (2013); circuit-level extension Mayer et al. 2025; literature note 008. The deep-number pin: a telescoping product P_L(p_target) = P_L(p_1) · ∏_j R_j where each ratio is estimated by Bennett's acceptance-ratio method over a Metropolis-in-F chain — no resolution wall at depth.

✓ B9 — unbiased vs direct MC at p=3×10⁻³ (0.07σ) and p=2×10⁻³ (0.30σ); pins the Bravyi Nature deep point (B10).

SplittingEstimate fields include pL, pL_lo, pL_hi, log_pL, log_pL_err, rhat (Gelman–Rubin mixing diagnostic), p_seq, and ratios (the per-rate breakdown). The chained confidence bound is a heuristic (Mayer §V.1); honesty is reported via rhat < 1.1.

DEM-level primitives (on DetectorErrorModel)

• splitting_find_failing(seed_priors, max_tries=200000, seed=0, …) — seed a chain by finding one BP+OSD-failing config. Returns fired-mechanism indices or None.
• splitting_sample(odds, init, seeds, burn_in=2000, n_samples=2000, thin=10, …) — run one Metropolis chain per seeds entry (parallel, GIL released).

See benchmarks/splitting_gross.py for the full deep-point harness.

class glean.SinterDecoder

A drop-in decoder for Stim's sinter.collect(...) pipeline, conforming to the de-facto sinter.Decoder interface (compile_decoder_for_dem → decode_shots_bit_packed).

✓ B6 — bit-exact vs the direct decode_batch / decode_batch_relay path; reproduces B3/B4 LER through sinter.collect.

• method: "bp_osd" → BP+OSD-CS (B3 baseline); "relay" → relay-BP (B4).
• parallel: spread shots across cores with rayon inside each decode (output identical to serial).
• **params: forwarded to the batch decode — osd_order, max_iter, alpha for bp_osd; num_sets, stop_nconv, gamma_dist, seed for relay. Instances are picklable, so sinter can ship them to worker processes.

import sinter, glean

results = sinter.collect(
    num_workers=8, tasks=tasks,
    decoders=["glean_bp_osd"],
    custom_decoders={"glean_bp_osd": glean.SinterDecoder(method="bp_osd")},
)

Requires quantumlib's Stim sinter (pip install sinter). import glean itself stays sinter-free (the adapter is imported lazily on first access of glean.SinterDecoder).

osd_order — the post-processor

Code.decode / DetectorErrorModel.decode* take osd_order to select the OSD post-processor: a negative value → OSD-0 (zeroth order); λ ≥ 0 → OSD-CS-λ (combination-sweep of order λ). The validated default across the library is osd_order=10 (BP+OSD-CS-10).

parallel — rayon batch parallelism

Every *_batch* method accepts parallel=False (default). parallel=True releases the GIL and spreads shots across cores with rayon, allocating one workspace per worker. The output is bit-identical to serial (same observables, same iteration counts) — purely a throughput knob (B5: 4–5× on a 10-core M4). The serial path stays rayon-free at runtime.

Real-time budget

relay-BP's headline real-time claim is the per-shot BP iteration count returned alongside the predictions (not wall-clock µs, which are offline/relative). B4 reports median 16 / p90 212 iterations against a 600-iteration budget.