| name | decoding-with-pymatching |
| description | Provides guidance for decoding graphlike Stim detector models and sampled trajectories with PyMatching, using the repo's registry-backed decoder service and explicit graphlike-DEM constraints. |
| version | 0.1.0 |
| author | QEC Research Skills |
| license | MIT |
| tags | ["QEC","PyMatching","Decoders","Detector Models"] |
| dependencies | ["qec-research","building-stim-circuits","choosing-qec-decoders"] |
Decoding With PyMatching
What This Skill Is For
Use this skill when a task needs an executable matching-based decoder lane over
registered QEC artifacts:
- decode a graphlike
DetectorModelBundle plus matching TrajectoryBundle,
- run a fast MWPM-style baseline over
Stim detector events,
- keep the run packaged as a registry-backed
DecoderResult,
- make the graphlike-reduction assumption explicit before using the result in a
paper or benchmark narrative.
When To Use It Versus Alternatives
Use this skill when the workflow is:
- rooted in
Stim detector models,
- scientifically acceptable as a graphlike matching problem,
- better served by MWPM-style decoding than by BP+OSD, search-based, or
hypergraph-aware routes.
Prefer decoding-with-ldpc when the goal is
the repo's parity-check-oriented baseline lane.
Prefer choosing-qec-decoders when the
main problem is backend selection across matching, color-code-specialized,
hypergraph-aware, erasure-aware, or search-based decoder families.
Do not present this lane as a universal decoder abstraction. It is the repo's
graphlike matching lane.
Required Artifacts And Assumptions
Expected inputs:
- a
DetectorModelBundle built with require_graphlike=True,
- a matching
TrajectoryBundle,
- a
decoder_config or an explicit decision to use the batch-decode default.
Expected outputs:
Assumptions to make explicit:
- the DEM was exported in graphlike form,
- flattening the workload into a matching graph is scientifically acceptable,
- the detector-model and trajectory artifacts come from the same parent
circuit.
Standard Workflow Checklist
- Read
research-state.yaml and confirm the
current decoder-lane assumptions.
- Check
servers/contracts/qec_decoders_mcp.yaml
for the intended tool surface.
- Confirm the detector-model bundle was compiled with
require_graphlike=True.
- Confirm the detector-model and trajectory artifacts come from the same
source circuit.
- Package the result as a
DecoderResult artifact instead of returning raw
predictions inline.
Validation Loop
Before closing work:
- confirm the graphlike-DEM assumption is recorded,
- confirm the detector-model and trajectory bundles are compatible,
- confirm the decoder configuration is recorded,
- confirm the result is described as a
PyMatching lane, not as a general
QLDPC decoder result.
Common Issues And Fixes
Non-graphlike detector model
Problem: the DEM artifact was compiled without graphlike decomposition or still
contains structure that does not fit the matching reduction.
Fix: rebuild the detector model with require_graphlike=True and stop if that
projection is not scientifically acceptable.
Matching used as a universal answer
Problem: a graphlike matching result gets reused for a color-code-specialized,
hypergraph, or heralded-erasure workload that needs a richer decoder story.
Fix: route back through choosing-qec-decoders
and record why the matching reduction is or is not valid.
Benchmark overclaim
Problem: one successful MWPM run gets described as if the repo already ships a
full benchmark lane.
Fix: keep the summary narrow and record that multi-decoder aggregation still
belongs to the benchmark layer.
References
