decoding-with-pymatching

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:

• DecoderResult.

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

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 bundle was compiled with require_graphlike=True.
4. Confirm the detector-model and trajectory artifacts come from the same source circuit.
5. Package the result as a DecoderResult artifact instead of returning raw predictions inline.

Validation Loop

Before closing work:

1. confirm the graphlike-DEM assumption is recorded,
2. confirm the detector-model and trajectory bundles are compatible,
3. confirm the decoder configuration is recorded,
4. 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

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