decoding-with-ldpc

name	decoding-with-ldpc
description	Provides guidance for decoding Stim-derived detector models and sampled trajectories with ldpc-based baseline decoders, starting with a narrow BPOSD lane and explicit compatibility checks.
version	0.1.0
author	QEC Research Skills
license	MIT
tags	["QEC","ldpc","Decoders","Detector Models"]
dependencies	["qec-research","building-stim-circuits"]

Decoding With ldpc

What This Skill Is For

Use this skill when a task needs a concrete baseline decoding workflow over registered QEC artifacts:

• decode a DetectorModelBundle plus matching TrajectoryBundle,
• measure logical error counts from sampled trajectories,
• package decoder outputs into registry-backed result artifacts,
• surface compatibility limits before claiming a benchmark path is valid.

When To Use It Versus Alternatives

Use this skill for the initial decoder lane when the workflow is:

• rooted in Stim detector models,
• compatible with an ldpc parity-check view,
• narrow enough that a baseline BPOSD decoder is an honest first comparison point.

Prefer future lomatching, mle-decoder, or benchmark workflows when the task needs correlated decoding, exact baselines, richer runtime comparisons, or multi-decoder sweeps.

Prefer choosing-qec-decoders when the main problem is backend selection across graphlike matching, color-code, hypergraph, erasure-aware, or search-based decoder families.

Do not describe this lane as "the decoder abstraction" for the whole repo. It is the first executable decoder slice, not the universal decoder interface.

Required Artifacts And Assumptions

Expected inputs:

• a DetectorModelBundle,
• a matching TrajectoryBundle,
• an explicit decoder configuration or an explicit decision to use defaults.

Expected outputs:

• DecoderResult.

Assumptions to make explicit:

• whether the detector model is expected to be graphlike,
• whether the detector and trajectory artifacts come from the same parent circuit,
• whether the result is being used as a baseline measurement or only as a smoke-check.

Standard Workflow Checklist

1. Read research-state.yaml and confirm the current decoder-lane assumptions.
2. Check servers/contracts/qec_decoders_mcp.yaml for the intended tool surface.
3. Confirm the detector-model and trajectory artifacts come from the same circuit source.
4. Keep the decoder output in DecoderResult artifacts instead of returning shot-level payloads inline.
5. Record whether the run is only a baseline BPOSD result or part of a broader benchmark story.

Validation Loop

Before closing work:

1. confirm the detector-model and trajectory bundles are compatible,
2. confirm the decoder configuration is recorded,
3. confirm the reported logical error metric is tied to actual sampled observables,
4. confirm the result is described as an ldpc baseline lane, not a repo-wide decoder truth.

Common Issues And Fixes

Artifact mismatch

Problem: the detector-model and trajectory bundles do not share the same source circuit.

Fix: stop and rebuild one of the inputs instead of decoding across incompatible artifacts.

Hidden graphlike assumption

Problem: the decode path silently assumes graphlike detector-model structure.

Fix: record whether undecomposed hyperedges are allowed and keep the default strict unless the task explicitly needs otherwise.

Benchmark overclaim

Problem: one successful BPOSD run gets described like a full decoder evaluation pipeline.

Fix: keep the summary narrow and record what still needs a benchmark lane, transport binding, or multi-decoder comparison.

References

• references/api.md
• references/examples.md
• docs/ARTIFACT_MODEL.md
• docs/TOOLKIT_REGISTRY.md
• servers/contracts/qec_decoders_mcp.yaml