use pecos_decoders::{SparseMatrix, Decoder, BpMethod, OsdMethod, UfMethod, BpSchedule, BpOsdDecoder, BpLsdDecoder, BeliefFindDecoder, FlipDecoder, UnionFindDecoder, SoftInfoBpDecoder, LdpcError, InputVectorType};
use ndarray::array;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let rows: Vec<u32> = vec![0, 0, 1, 1];
let cols: Vec<u32> = vec![0, 1, 2, 3];
let pcm = SparseMatrix::from_coo(2, 4, rows, cols)?;
let error_rate = 0.05;
let syndrome = array![1u8, 0];
// CODE
Ok(())
}
PECOS provides quantum error correction decoders through both Python and Rust APIs. The availability of specific decoders varies by language.
The decoder system in PECOS is designed around modularity and performance:
- Optional Components: Decoders are not built by default to keep PECOS lightweight
- External Integration: LDPC decoders come from specialized external projects
- Unified API: Consistent interface across different decoder implementations
- Cross-Language Support: Some decoders available in both Python and Rust, others Rust-only
PECOS reads flat Stim detector-error-model text using a strict subset of Stim's grammar:
- Instruction names and detector/observable target prefixes are case-insensitive; tags and inline
#comments are supported. - Targets and
^separators require spacing; separators cannot be first, last, or adjacent. - PECOS rejects a detector or observable repeated within one component of an error instruction, and an identical component repeated within one instruction, even though Stim accepts them, because it almost always indicates a mistake. Extension
TPtargets follow the same rule. Components are identical when they contain the same set of targets regardless of order:D0 D1 ^ D1 D0is rejected, whileD0 D1 L0 ^ D0 D1 L1contains two distinct components. A target may appear in several components of a decomposed mechanism. - Parenthesized arguments immediately follow the name or tag.
errorrequires one probability in[0, 1], witherror()meaning zero; detector and logical-observable declarations require exactly one target of the appropriate kind. - Grammar is validated per instruction; block balance is not checked by the tokenizer. PECOS readers requiring flat DEMs reject
repeat,shift_detectors, and closing braces with a flattening error, including stray braces and unclosed repeat blocks. - PECOS extension targets and metadata statements require an explicit opt-in:
ParsedDemandDetectorErrorModel::with_pecos_dem_metadataenable the whole PECOS superset, includingTPtargets and JSON metadata statements.
Python constructors report tokenizer errors as ValueError with the Invalid DEM syntax: prefix. Stim-backed constructors such as PyMatchingDecoder and TesseractDecoder validate the original text before passing it to their backend, which supports loop expansion and retains its native errors for backend-specific constraints.
The following decoder APIs and supporting types are publicly re-exported from
pecos.decoders:
| API | Primary input | Description |
|---|---|---|
MWPM2D |
QECC object | Legacy minimum-weight perfect matching for 2D codes. |
DummyDecoder |
None | No-op decoder for tests and interface benchmarks. |
PyMatchingDecoder |
Graph-like DEM text or CheckMatrix |
PyMatching minimum-weight perfect matching, with optional correlated decoding. |
FusionBlossomDecoder |
Check matrix, standard-code parameters, or a manual graph | Pure-Rust minimum-weight perfect matching. |
TesseractDecoder |
DEM text | Search-based decoder that accepts raw hyperedges. |
TesseractTrellisDecoder |
DEM text | Sums probability mass over a beam of partial syndromes and reports a per-shot observable probability; accepts at most one observable and a 256-detector active frontier. The probability and low_confidence flag come only from this class; the tesseract_trellis() spec path yields the observable mask. |
DemAwareDecoder |
DEM text | Maps DEM mechanisms and observables onto BP-OSD and other check-matrix decoders. |
BpOsdBuilder / BpOsdDecoder |
SparseMatrix check matrix or DEM text |
Belief propagation with ordered-statistics post-processing. |
BpLsdBuilder / BpLsdDecoder |
SparseMatrix check matrix or DEM text |
Belief propagation with localized-statistics post-processing. |
MinSumBpBuilder / MinSumBpDecoder |
Dense check matrix and error priors, or DEM text | Min-sum belief propagation. |
RelayBpBuilder / RelayBpDecoder |
Dense check matrix and error priors, or DEM text | Relay belief propagation. |
UnionFindBuilder / UnionFindDecoder |
SparseMatrix check matrix or DEM text |
Union-find decoding with inversion or peeling. |
CheckMatrix / SparseMatrix |
Dense or coordinate-form matrix data | Matrix containers used by matching and LDPC decoder constructors. |
MwpmResult / BpResult / TesseractResult / TesseractTrellisResult |
Decoder output | Result objects for matching, belief-propagation, and Tesseract decoders. |
The experimental frontier() and bp_trellis() factories are not part of this table: they import from pecos.decoders only when the optional pecos-rslib-exp package is installed, and are described in the Rust-backed Frontier and Rust-backed BP-Trellis sections below.
Python decoder inputs name their encoding explicitly: use
decode_syndrome(...) for a dense detector vector and
decode_from_defects(...) for sparse detector indices. The BP/LDPC classes'
from_dem(...) constructors return a DemAwareDecoder wrapper so their results
include observable_flips and their instances retain the DEM dimensions.
The Rust API provides access to a broader set of decoders:
LDPC Decoders (feature: ldpc):
- BP-OSD (Belief Propagation with Ordered Statistics Decoding)
- BP-LSD (Belief Propagation with Localized Statistics Decoding)
- MBP (Min-sum Belief Propagation)
- Belief Find decoder
- Flip decoder
- Union Find decoder
- SoftInfoBP decoder
Other Decoders:
- Fusion Blossom MWPM (feature:
fusion-blossom) - PyMatching MWPM (feature:
pymatching) - Tesseract (feature:
tesseract) - Chromobius color code decoder (feature:
chromobius) - Native Relay-BP and min-sum BP (feature:
relay-bp)
=== ":fontawesome-brands-python: Python"
Install PECOS with decoder support:
```bash
pip install quantum-pecos
```
The Python package exports the decoder APIs listed above.
=== ":fontawesome-brands-rust: Rust"
Add decoder dependencies to your `Cargo.toml`:
```toml
[dependencies]
# Option 1: Use the meta-crate with specific features
pecos-decoders = { version = "0.1.1", features = ["ldpc"] }
# Option 2: Use individual decoder crate
pecos-ldpc-decoders = "0.1.1"
# Core types (always needed for custom decoders)
pecos-decoder-core = "0.1.1"
```
Build with LDPC decoders:
```bash
# Build LDPC decoders
cargo build --package pecos-decoders --features ldpc
# Build all decoders
cargo build --package pecos-decoders --all-features
```
The MWPM2D decoder implements Minimum Weight Perfect Matching for 2D topological codes.
import pecos as pc
# Create a surface code first
surface = pc.qeccs.Surface4444(distance=3)
# Create decoder with the QECC
decoder = pc.decoders.MWPM2D(surface)A no-op decoder useful for testing decoder interfaces without actual decoding.
from pecos.decoders import DummyDecoder
decoder = DummyDecoder()Before using decoders, you need a quantum error correction code:
use pecos_decoders::SparseMatrix;
// Create a parity check matrix in COO (coordinate) format
let rows: Vec<u32> = vec![0, 0, 1, 1];
let cols: Vec<u32> = vec![0, 1, 2, 3];
let pcm = SparseMatrix::from_coo(2, 4, rows, cols)?;DEM-built Relay-BP, min-sum BP, BP-OSD, BP-LSD and BeliefFind handle
probability-0 and probability-1 mechanisms exactly: impossible mechanisms are
removed, and certain mechanisms contribute fixed syndrome and observable biases.
Reduction follows any uniform error_rate override and duplicate merging
(BeliefFind does not merge duplicates). Detector and observable indices stay the
same. Construction fails if no uncertain error mechanism remains after support
reduction, including with error_rate=0. A biased syndrome that fires a
detector that no uncertain error mechanism can flip raises an error naming the
lowest such index and the number that fired. This includes declared-but-unused
detectors and aborts batch decoding. Syndrome lengths and binary values are
checked before applying biases.
In Python, DemAwareDecoder (including convenience from_dem constructors)
raises ValueError for empty reduced support, fired dead detectors, wrong
lengths, and non-binary syndromes. StructuredDemDecoder.decode_syndrome raises
ValueError for fired dead detectors and non-binary input, but RuntimeError
for wrong lengths. On spec-built paths, empty reduced support raises
RuntimeError when the decoder is built (for the logical-subgraph,
logical-algorithm and logical-circuit decoders, in their constructors).
SampleBatch.decode, DemSampler decoding and the logical decoders'
decode/decode_count raise RuntimeError for fired dead detectors, which
aborts the batch; SampleBatch.compare_decoders instead counts them as
decode-error outcomes for those shots.
Raw BP-OSD, BP-LSD, soft-information BP and BeliefFind builders require finite
priors strictly in (0, 1); MBP is unchanged. Their product-sum check update
bounds saturated tanh products to the closest double below one in magnitude,
keeping check-to-bit messages finite; other products are unchanged.
belief_matching, experimental BP-trellis, and the pecos_uf bp and
bp_serial presets retain native ±30 saturation. Perturbed ensemble members
retain their probability clamp, so only the anchor member receives the exact
original bias.
Combines belief propagation with ordered statistics decoding post-processing.
use pecos_decoders::{BpOsdDecoder, BpMethod, OsdMethod, BpSchedule};
// Build decoder with configuration
let mut decoder = BpOsdDecoder::builder(&pcm)
.error_rate(error_rate)
.max_iter(100)
.bp_method(BpMethod::MinimumSum)
.osd_method(OsdMethod::OsdE)
.osd_order(10)
.build()?;
// Decode syndrome
let result = decoder.decode(&syndrome.view())?;
println!("Decoding: {:?}", result.decoding);
println!("Converged: {}", result.converged);Localized version of OSD for better scaling with large codes.
BP+LSD builders, specs and DEM constructors default to minimum-sum BP, scaling
factor 0.625, at most 30 iterations, parallel scheduling, one bit per growth step,
and order 0. lsd_order: 0 = LSD-0, no reprocessing; > 0 = combination-sweep (OSD-CS) reprocessing of that order.
The raw Rust builder permits explicit reprocessing methods. Both the builder
and BpLsdDecoder::new reject Off at every order, because LSD always runs, and
reject Osd0 with a positive order. At order 0 every accepted method (Osd0,
OsdCs, OsdE) runs LSD-0.
Cluster growth ranks BP log-probability ratios in ascending order, choosing more
likely errors first. bits_per_step=0 grows all candidate bits each step; their
insertion order still affects pivots and the solution.
Python BpLsdBuilder exposes .bp_method(...), .ms_scaling_factor(...),
.bits_per_step(...) and .lsd_order(...). BpLsdDecoder.from_dem, the bp_lsd
spec factory and DemAwareDecoder.from_dem(..., decoder_type="bp_lsd") accept
these settings as keywords. Scaling defaults to 0.625; explicit None selects
product-sum. An explicit bp_method="product_sum" (alias "ps") ignores scaling;
bp_method="minimum_sum" (alias "ms") with None uses 0.625. These rules also
apply to the Python builder. Rust specs use ms_scaling_factor: None to select
product-sum.
use pecos_decoders::BpLsdDecoder;
let mut decoder = BpLsdDecoder::builder(&pcm)
.error_rate(error_rate)
.bits_per_step(1)
.lsd_order(10)
.build()?;
assert_eq!(decoder.lsd_method(), pecos_decoders::OsdMethod::OsdCs);
let result = decoder.decode(&syndrome.view())?;Combines belief propagation with union-find algorithm.
use pecos_decoders::{BeliefFindDecoder, UfMethod};
let mut decoder = BeliefFindDecoder::builder(&pcm)
.error_rate(error_rate)
.uf_method(UfMethod::Inversion)
.max_iter(10)
.build()?;
let result = decoder.decode(&syndrome.view())?;Fast bit-flipping decoder suitable for real-time applications.
use pecos_decoders::FlipDecoder;
let mut decoder = FlipDecoder::builder(&pcm)
.max_iter(100)
.build()?;
let result = decoder.decode(&syndrome.view())?;Graph-based decoder using union-find data structure.
use pecos_decoders::{UnionFindDecoder, UfMethod};
let mut decoder = UnionFindDecoder::builder(&pcm)
.method(UfMethod::Inversion)
.build()?;
// Union find decode takes syndrome, LLRs, and bits_per_step
let llrs = vec![0.1; 4]; // one LLR per bit column
let result = decoder.decode(&syndrome.view(), &llrs, 1)?;Use log-likelihood ratios for improved decoding performance.
use pecos_decoders::SoftInfoBpDecoder;
let mut decoder = SoftInfoBpDecoder::builder(&pcm)
.error_rate(error_rate)
.max_iter(50)
.build()?;
// Soft decode takes soft syndrome values, cutoff, and sigma
let soft_syndrome = vec![0.9, 0.1];
let result = decoder.decode(&soft_syndrome, 5.0, 0.5)?;Decode multiple syndromes efficiently.
use pecos_decoders::BpOsdDecoder;
use ndarray::array;
let mut decoder = BpOsdDecoder::builder(&pcm).error_rate(error_rate).build()?;
let syndromes = vec![
array![1u8, 0],
array![0u8, 1],
];
for (i, syn) in syndromes.iter().enumerate() {
let result = decoder.decode(&syn.view())?;
println!("Syndrome {}: {:?}", i, result.decoding);
}use pecos_decoders::{BpOsdDecoder, BpSchedule};
let mut decoder = BpOsdDecoder::builder(&pcm)
.error_rate(error_rate)
.bp_schedule(BpSchedule::Parallel)
.omp_threads(4)
.build()?;use pecos_decoders::{BpOsdDecoder, LdpcError};
let mut decoder = BpOsdDecoder::builder(&pcm).error_rate(error_rate).build()?;
match decoder.decode(&syndrome.view()) {
Ok(result) => {
println!("Decoding: {:?}", result.decoding);
println!("Converged: {}", result.converged);
}
Err(e) => {
eprintln!("Decoding error: {}", e);
}
}For exact endpoint handling when built from a DEM, see LDPC Decoders.
relay_bp, RelayBpBuilder, and RelayBpDecoder use PECOS's native Relay-BP
kernel (pecos-bp), implementing Müller et al., arXiv:2506.01779.
Native Relay-BP and min-sum flip a bit when its posterior log-likelihood ratio
is <= 0, including either exact zero, matching relay-bp and ldpc. PECOS always
floors the stored prior that seeds messages and memory at magnitude 4e-5,
as relay-bp does when min_log_prior_ratio is set (its default is None).
The sign is preserved except that exact zero becomes +4e-5, so priors of
exactly one half no longer start at a tie. Nothing downstream is floored again.
Correction costs use raw saturated priors; BP+UF and trellis are unchanged.
The existing saturation at ±30 is unchanged. Decoding results can change.
For a fixed configuration, decoding is a deterministic function of (seed, syndrome).
Decode order, batch splitting and worker count cannot change a result; serial and
parallel batch decoding are supported.
The default leg-zero memory strength is gamma0=0.35, defined by
pecos_relay_bp::DEFAULT_GAMMA0. In PECOS sweeps at p = 0.005 it was the best
or tied-best of the values tried on surface, color and gross codes: significantly
better on surface d5 (Z), color d5 and gross X, tied on gross Z. The paper used
0.125 for gross and 0.35 for surface; set gamma0 explicitly to reproduce the
paper. The default gamma_dist_interval=(-0.24, 0.66) is the paper's gross-code
interval.
Use pre_iter for leg zero and set_max_iter for each of the num_sets relay
legs. Relay has no max_iter option, including RelayBpDecoder.from_dem;
the generic DemAwareDecoder.from_dem rejects explicit max_iter for Relay.
gamma0=None disables memory in leg zero only; relay legs keep their sampled
memory. The Rust and Python RelayBpBuilder can construct a RelayBpDecoder
with num_sets=0 for a single leg (then pre_iter must be positive). The
relay_bp spec factory requires positive num_sets.
alpha=None means unit scaling, while alpha=0.0 selects dynamic scaling;
alpha_iteration_scaling_factor must always be finite and greater than zero.
Stopping targets must be positive, so stopping("n_conv_0") is rejected.
Python RelayBpBuilder.explicit_gammas(rows) sets one memory strength per bit:
row 0 serves relay leg 1, and rows cycle; None restores sampling from
gamma_dist_interval(low, high). Both builder-created Python decoders provide
decode_batch(detection_events, num_shots), decoding sequentially with the GIL
released. Pass num_shots * check_count row-major 0/1 bytes (for example,
numpy_array.astype(numpy.uint8).tobytes()); the result is
num_shots * bit_count row-major correction bytes.
MinSumBpBuilder uses a single native memory-BP leg, keeps a positive max_iter,
and has no memory when gamma0=None. Both families require binary matrices and
syndromes and one finite probability in [0, 1] per matrix column.
-
Algorithm Selection:
- BP-OSD: Best overall performance for most codes
- BP-LSD: Better for very large codes
- Flip: Fastest but lower performance
- Union Find: Good for codes with specific structure
-
Parameter Tuning:
- Start with default parameters
- Increase
max_iterationsfor better convergence - Adjust
osd_orderbased on code size and error rate - Use parallel schedules for larger codes
-
Hardware Optimization:
- Enable CPU-specific optimizations in release builds
- Use multiple threads for batch decoding
- Consider memory layout for cache efficiency
Install the optional pecos-rslib-exp package for this section and BP-Trellis
below. Standard pecos.decoders imports do not load the experimental extension.
The explicit from pecos.decoders import frontier, bp_trellis convenience import
loads it lazily and raises an actionable ImportError if it is unavailable.
Experimental factories are excluded from wildcard imports. Their specifications
work with SampleBatch.decode(...) and DemSampler.decode(...); the standard
DecoderSpec.parse strings and composite-spec factories do not load optional
providers. The experimental calls cross a Python adapter at each shot, with
native model construction and decoding releasing the GIL.
from pecos_rslib_exp import frontier
from pecos_rslib.qec import SampleBatch
dem = "error(0.1) D0 D1 D2 L0\n"
batch = SampleBatch([[1, 1, 1], [0, 0, 0]], [1, 0])
result = batch.decode(dem, frontier(k=64), workers=2, predictions=True)
assert result.predictions == [1, 0]
assert result.num_errors == 0Frontier accepts raw DEMs, including hyperedges. workers=None selects the
worker count automatically; workers=1 runs sequentially. Parallel execution
releases the Python GIL and preserves shot order. Each active worker owns
independent decoder scratch, so more workers and larger k increase memory use.
SampleBatch.decode(...) builds exactly one decoder per worker;
DemSampler.decode(...) builds one up front to check dimensions and then one per
scheduled group of sampling chunks, which can be several times the worker count
on a long run. Plain specifications rebuild the model for each decoder.
Recovery-configured Frontier specifications prepare the trellis model and optional
feasibility basis once per decode call, sharing them across all workers with
independent scratch. This prepared state is released when the call finishes.
Options match pecos_rslib_exp.FrontierDecoder.from_dem: k, delta,
score_alpha, bp_score_iterations, column_order, merge_indistinguishable,
metric_mode, and int_metric_scale. The default ordering is
"deadline_reorder"; "time_order", "backward_deadline_reorder", and explicit
column permutations are also accepted. Frontier remains experimental, and
pruning can make predictions approximate. For per-shot logical masses, pruning
status, and complementary gaps, use the direct experimental binding.
The direct FrontierDecoder.decode_syndrome, decode_from_defects, and
decode_batch methods share a Rust recovery implementation. They accept
on_no_path="raise" (default), "report", or "fallback", and an optional
delta_max. Invalid inputs, configuration errors, and engine faults still raise
in every mode. Always-answer means a prediction is returned for a normal
no-path outcome; it does not suppress programming errors.
from pecos_rslib_exp import FrontierDecoder
decoder = FrontierDecoder.from_dem(
"error(0.1) D0 D1 L0\n",
k=256,
delta=16,
fallback="feasible_then_zero",
)
# Strict: raise if no configured attempt finds a path.
assert decoder.decode_syndrome([1, 1]).observable_flips.mask == 1
# Reporting: retain successful shots and explicit no-path reports in order.
outcomes = decoder.decode_batch(
[[0, 0], [1, 0], [1, 1]],
workers=2,
on_no_path="report",
delta_max=64,
)
assert [outcome.no_path for outcome in outcomes] == [False, True, False]
assert outcomes[1].cause == "infeasible"
# Always-answer: use the explicitly configured fallback after attempts fail.
answer = decoder.decode_syndrome([1, 0], on_no_path="fallback", delta_max=64)
assert answer.fallback_used
assert answer.status == "fallback:zero"
assert answer.syndrome_consistent is FalseWith delta=16, delta_max=64, attempts use 16, 32, then 64, stopping at the
first success. A non-power-of-two maximum is included as the final cap. A zero
base grows first to min(1, delta_max). The maximum must be finite and at least
the base delta; omitting it disables retries. K stays fixed. Attempts restart
DP using one prepared model and one BP preparation per shot. Residual or
infeasible failures skip remaining attempts because widening cannot help.
delta_max bounds the pruning window, not wall-clock runtime.
The returned types are distinct:
FrontierResult: a decoded prediction,no_path=False,fallback_used=False.deltas_tried,delta_used, andescalation_rungs_usedrecord recovery. Transitions count all attempts; evidence and pruning diagnostics describe the successful attempt, whose prediction can still be approximate.FrontierNoPath: no prediction,no_path=True,fallback_used=False.causeis"residual","infeasible", or"exhausted". Residual includes adetectorthat cannot be changed; exhausted indicates failure after pruning, which alone does not prove incompatibility. Reports exposedeltas_tried, totaltransitions, totaldropped_states, and one-shotbp_seconds.FrontierFallback: an explicit prediction,no_path=True,fallback_used=True.failureretains the original no-path report. It has no likelihood or confidence estimate. Itsobservable_flipscan be nonzero.
Configure fallback="feasible_then_zero" to prepare a reusable GF(2) solver for
an independent binary DEM. It chooses a probability-ordered column basis and
verifies the resulting fault explanation against the syndrome. A successful
fallback has status="fallback:feasible", syndrome_consistent=True, and
mechanism_indices referring to the original DEM. This is a deterministic
heuristic, not a maximum-likelihood or minimum-weight decoder. Preprocessing
uses additional memory for the basis and witnesses. Direct decode_batch workers
share this state; recovery-configured specifications also share it across all
workers within each SampleBatch.decode or DemSampler.decode call.
build_seconds reports Frontier construction only, excluding that preparation.
If the DEM has no explanation, this policy returns zero observable flips with
status="fallback:zero" and syndrome_consistent=False. An explicitly selected
fallback="zero" always uses zero after no-path and reports consistency as
None (unverified). Neither zero prediction is presented as a successful decode.
Configuring a fallback does not activate it until on_no_path="fallback" is
requested. Feasibility handles p=0/p=1 and joint ^ components, but is rejected
for categorical from_factors models; those can use the explicit zero policy.
Syndrome consistency does not imply logical identity. For the model
error(0.1) D0 L0, a fired D0 requires logical mask 1; no identity-sector
explanation exists. A DEM mechanism explanation is also not automatically a
physical data-qubit Pauli correction. Record fallback and incompatible-shot
rates alongside logical error rates. Do not silently drop undecoded shots from
the denominator; always-answer predictions can be scored across all shots.
Rust callers use pecos_frontier::recovery::FrontierRecoveryDecoder with
RecoveryOptions, NoPathAction, and FallbackPolicy. The normal
FrontierDecoder remains the strict parity-port engine. The shared
pecos_decoder_core::feasibility::DemFeasibility utility can also be prepared
and queried independently of Frontier.
use pecos_frontier::{FrontierConfig, SparseDem};
use pecos_frontier::recovery::{
FallbackPolicy, FrontierRecoveryDecoder, FrontierRecoveryOutcome,
NoPathAction, RecoveryOptions,
};
let dem = SparseDem::from_dem_str("error(0.1) D0 D1 L0")?;
let mut decoder = FrontierRecoveryDecoder::from_sparse_dem(
&dem,
FrontierConfig { k: 256, delta: 16.0, ..Default::default() },
Some(FallbackPolicy::FeasibleThenZero),
)?;
let outcome = decoder.decode(&[1, 0], RecoveryOptions {
delta_max: Some(64.0),
on_no_path: NoPathAction::Fallback,
})?;
assert!(matches!(outcome, FrontierRecoveryOutcome::Fallback {
syndrome_consistent: Some(false), ..
}));Rust decode_batch preserves per-shot Result values in input order. Python
batch calls preserve normal no-path/fallback outcomes but still raise an indexed
exception for other errors. Rust callers can also bind options using
decoder.with_options(options)? to obtain an ObservableDecoder adapter for
a shared batch DecoderFactory (with native batch dispatch disabled).
decode_outcome preserves reports; prediction-only decode_obs returns an error
when reporting supplies no mask. FrontierCommitteeDecoder remains strict.
The frontier(...) specification accepts the same recovery controls for both
SampleBatch.decode and DemSampler.decode:
from pecos_rslib_exp import frontier
from pecos_rslib.qec import SampleBatch
dem = "error(0.1) D0 D1 D2 L0\n"
# The middle syndrome is incompatible with this DEM and uses the zero fallback.
batch = SampleBatch([[1, 1, 1], [1, 0, 0], [0, 0, 0]], [1, 1, 0])
spec = frontier(
k=256,
delta=16,
delta_max=64,
on_no_path="fallback",
fallback="feasible_then_zero",
)
result = batch.decode(dem, spec, workers=4, predictions=True)
print(result.num_errors, result.num_fallback, result.num_undecoded)
fallback_errors = sum(r.logical_error for r in result.recovery if r.fallback_used)
assert result.num_fallback == 1
assert result.num_undecoded == 0
assert result.num_errors == 1
assert fallback_errors == 1Every supplied prediction, including fallback, is compared against the shot's
true logical observables. A syndrome-compatible fallback with the wrong logical
mask counts as an error. recovery contains shot indices, actual deltas_tried,
fallback_used, syndrome_consistent, undecoded, and logical_error for shots
requiring retries, reporting, or fallback. These records are retained even when
predictions=False, so fallback success can be measured separately.
With on_no_path="report", retained predictions contains None for undecoded
shots. num_scored excludes those shots and num_errors counts mismatches among
supplied predictions. The full-batch logical_error_rate (including timing
stats) is NaN and interval() raises when any shot is undecoded; neither an
identity placeholder nor an artificially reduced error rate is reported. Rust
DecodeResult exposes partial_predictions in this case and leaves its
complete predictions absent. Strict defaults and version-1 providers retain
their existing behavior. Recovery specifications require both the standard and
experimental Python extensions to support provider protocol version 2.
from pecos_rslib_exp import bp_trellis
from pecos_rslib.qec import SampleBatch
dem = "error(0.1) D0 D1 D2 L0\n"
batch = SampleBatch([[1, 1, 1], [0, 0, 0]], [1, 0])
spec = bp_trellis(
k=8,
delta=100.0,
score_alpha=0.8,
bp_score_iterations=5,
merge_indistinguishable=True,
ordering="deadline",
escalation=[(64, 100.0)],
)
result = batch.decode(dem, spec, workers=2, predictions=True)
assert result.predictions == [1, 0]
assert result.num_errors == 0The ladder uses one engine model and prepares each shot once, including BP.
escalation=[(k, delta), ...] chooses both pruning parameters per rung;
escalation_ks=[k, ...] is shorthand for rungs at the base delta. Pass only
one ladder keyword. The default ladder is empty. Rungs need not be monotone,
and an exact base cannot have a ladder. Rungs run only after a no-path attempt
that dropped states: never after a successful but wrong prediction, and never
after a residual or infeasible no-path.
The default ladder is empty so that the per-shot cost of a configuration is
exactly what it says. When a no-path shot should be retried rather than
reported, the evidence-backed setting is one rung at k = 64 with the base
delta, as in the example above. On the bivariate-bicycle 144 corpus at
physical error rate 0.003, a 4 -> 64 ladder reached 8 failures per 1000 shots
at 49 ms per shot, against 10 failures at 101 ms for a single k = 16; an
8 -> 64 ladder reached 0 failures per 1000 at 72 ms per shot at rate 0.002.
On the rotated surface code at distance 5 no shot ever escalated, so the rung
costs nothing there. A ladder never rescues a confidently wrong prediction,
only a no-path, and a fully exact configuration (k unbounded, delta
infinite) exhausted memory on that corpus, so the last rung should stay
finite.
The direct BpTrellisDecoder.decode_syndrome, decode_from_defects, and
decode_batch(shots, workers=1) methods accept on_no_path="raise" (default)
or "report". Report mode returns a BpTrellisNoPath in place for each failed
shot, preserving batch order. Its cause is "residual" when a detector's
residual cannot be changed, "infeasible" when an attempt proves there is no
path without pruning, or "exhausted" when all attempts fail after pruning.
Residual and infeasible outcomes skip remaining rungs. Other errors still raise.
Both outcome classes expose no_path, transitions, bp_runs, and
bp_seconds. Only a decoded result exposes observable_flips; a report exposes
placeholder_flips instead, the forced contribution of probability-one
mechanisms, including wide observables. The names differ on purpose, so code
written for a correction raises AttributeError on a report rather than
silently consuming a placeholder. The report also exposes detector (only for
residual) and rungs_tried.
BP time is counted once, while transitions sum all attempts.
The bp_trellis(...) spec route remains strict and accepts no on_no_path.
ordering also accepts "backward_deadline", "time_order", or an explicit
mechanism permutation. BP-Trellis uses floating-point coset masses and does not
expose Frontier's integer metric options.
Like Frontier, BP-Trellis accepts raw hyperedges and arbitrary-width observables,
releases the GIL during batch decoding, and supports automatic worker selection
and DemSampler.decode(...). It remains experimental. Use
pecos_rslib_exp.BpTrellisDecoder for per-shot confidence, pruning status, and
retry telemetry; the unified batch result returns predictions and aggregate scores.
Graph decoder specs (PyMatching, Fusion Blossom and its perturbed correlated
variant, PECOS UF, K-MWPM, non-hybrid belief matching, and astar) project raw
hyperedges themselves. Projection uses disjoint components already present as
standalone faults in the model, preserving probabilities and observable effects.
A DetectorErrorModel object decodes its standard text plus its fault_sector labels.
Those labels guide the choice of graphlike components.
Use batch.decode(dem, spec) or dem.build_decoder(spec) to preserve them.
Saving with batch.save(path, dem=dem) also preserves the object's labels in
corpus format v2. SampleBatch.load(path).decode(None, spec) uses the stored
text and labels. A labelled embedded model has object semantics, including
provider refusal; passing loaded.dem explicitly decodes unlabelled text.
All-null labels (including v1 corpora) retain text semantics and provider support.
loaded.dem_fault_sectors returns a fresh, dense list of labels or None entries;
batches without an embedded model return None. Corpus identity checks only text.
Resaving with equal embedded text preserves labels, including with
allow_dem_mismatch=True; different text writes all-null labels. An object
always supplies its own labels. Saving never changes the source batch.
Every save writes v2; new readers accept v1 and v2, while older installations
reject v2 files. loaded.format_version reports the version actually loaded.
Both results expose .projection. It is None when no projection was needed or
when a composition without a shared policy projects inside its members and has
no shared report. Text input has no fault-sector labels.
Circuits can supply the string attribute measurement_classes: a JSON list with
one entry per absolute measurement record in emission order. Each entry is null
(unclassed), or an object with required block, family, and round keys.
block is a non-empty opaque code-block name; family is a non-empty opaque base
check-family name or null (classified but untyped); round is an integer global
epoch and may be negative. Unknown object keys are ignored. For example:
[{"block":"memory","family":"X","round":-1}, null].
The base family identifies the stabilizer register before logical frame changes:
after a transversal H the register keeps its family although its physical
measurement basis flips. Block and round are currently validated only.
With classes present, circuit_definitions() and DEM construction resolve each
detector's references to absolute records, cancel even multiplicities, and derive
the common family of the remaining records. Empty support, an unclassed or
untyped remaining record, or differing families gives None. Cancelled records
do not contribute.
An explicit non-null detector fault_sector must equal the derived label,
including when derivation gives None; disagreement is an error. An absent or
null explicit label takes the derived value. Without classes, explicit labels
pass through unchanged. Empty explicit labels remain invalid.
The Rust and Python DemBuilder.with_measurement_classes_json manual route takes
classes in influence-map record order, which need not be stamped measurement-ID
order. The final measurement count must match the list length.
The normal manual Python route is DemBuilder(map).with_circuit_metadata(circuit):
it copies detectors, observables, classes and the measurement count together.
It copies attributes only, after checking them against the circuit: ids must be
unique, references must resolve, and attributes must agree with any annotations on
ids, measurements and labels. The influence map must hold the measurement records
of circuit.to_dag_circuit(), so build it from that DAG. Use
DetectorErrorModel.from_circuit for circuits defined by annotation alone.
Resolved circuit_definitions() detector dictionaries carry the effective labels,
including derived labels when explicit metadata is absent or null; disagreement
fails during definition resolution. A caller passing only
with_detectors_json(circuit.get_meta("detectors")) for a circuit whose labels
come from classes gets a DEM with no labels and no error. Pass the circuit metadata
instead, or supply the classes separately in the influence map's record order.
The default irreducible="refuse" rejects faults that cannot be decomposed and
reports their count and input indices. To remove those faults from the decoder's
model explicitly, use pymatching(correlated=True, irreducible="drop") or the
string "pymatching:irreducible=drop". Sampling still uses the original model.
Shots that fire a dropped fault can make some graph decoders fail on detectors
left without edges (#1266).
Alternatively, use a hyperedge-capable decoder such as bp_osd() or tesseract().
Effects with more than 12 detectors or reducible only with overlapping components
are refused under either policy; irreducible="drop" does not apply to them.
Use a hyperedge-capable decoder such as bp_osd() or tesseract() for these effects.
Supplied ^ decompositions remain supported and are used verbatim when every
component touches at most two detectors. Mixing them with raw hyperedges is an
error. Hybrid belief matching still takes separate full and decomposed models.
Windowed decoding projects the full model using the inner spec's policy before
windowing; beam search still requires graphlike input in its phase-1 windows.
A graph decoder in beam phase 2 projects the full residual model under Refuse.
Drop is rejected in compositions without a shared projection report, including
beam search and mixed graph/hypergraph ensembles. Every graph member must share
the policy and the composition must resolve to a shared projection before Drop
is allowed. Phase 2 may use a hyperedge-capable decoder selected through Rust
BeamSearchConfig.phase2 or pecos_rslib.decoders.beamsearch(phase2=...);
the beamsearch string grammar has no phase2 key.
See
Experimental Decoders for the Frontier and
BP-Trellis decoders, which additionally report a per-shot complementary gap,
and for provenance-based decomposition of a hyperedge model into a graphlike
one. Frontier's exact default-float masses are true unnormalized posteriors.
Under its integer maxlog_int metric (accepted by Python FrontierDecoder as
metric_mode="maxlog_int"; the committee remains float-only), terminal masses
are per-label best-route (Viterbi) masses, the gap is a route-mass margin, and
log_evidence is the winner's mass rather than evidence.
- Getting Started Guide - Main installation guide
- LLVM Setup Guide - For building with LLVM support
- Experimental Decoders - Frontier, BP-Trellis, complementary gap