| name | choosing-qec-decoders |
| description | Provides guidance for choosing among QEC decoder backends such as ldpc, PyMatching, fusion-blossom, Chromobius, MWPF, tesseract-decoder, and MQT QECC based on artifact shape, code family, noise model, and validation goals. |
| version | 0.1.0 |
| author | QEC Research Skills |
| license | MIT |
| tags | ["QEC","Decoders","Routing","Stim"] |
| dependencies | ["qec-research","building-stim-circuits","decoding-with-ldpc","decoding-with-pymatching","decoding-with-fusion-blossom","decoding-with-tesseract-decoder"] |
Choosing QEC Decoders
What This Skill Is For
Use this skill when the main question is decoder selection, not decoder execution:
- choose a decoder backend before implementing a new adapter,
- route a
Stim detector-model workflow to a compatible decoder family,
- distinguish graphlike matching decoders from color-code, hypergraph, or search-based decoders,
- avoid overclaiming that one decoder is universal across surface-code, color-code, and QLDPC studies.
Core Routing Questions
Answer these before naming a backend:
- Is the primary artifact a graphlike detector error model, a raw parity-check matrix, a non-graphlike or hypergraph object, or a full circuit with heralded side information?
- Is the code family repetition, surface, color, generic CSS, or QLDPC?
- Is the noise model code-capacity-like, phenomenological, circuit-level, or erasure-aware?
- Do you need a fast benchmark baseline, an exact matching answer, a color-code-specialized decoder, or a hypergraph-capable route?
- Does the environment constraint rule out the package entirely?
Routing Defaults
- Use
ldpc-bposd for the repo's current executable baseline and for parity-check-like baseline comparisons.
- Use
decoding-with-pymatching for the repo's current executable matching lane.
- Use
decoding-with-fusion-blossom when the detector model is graphlike and the task specifically wants exact MWPM or erasure-aware matching updates while staying in the matching lane.
- Use
chromobius when the workload is color-code-specific and the approximation to a matching problem is part of the intended method.
- Use
mwpf when higher-order structure matters, the workload is closer to general QLDPC decoding, or heralded-erasure context from the full circuit must be preserved.
- Use
decoding-with-tesseract-decoder when a search-based or small-instance baseline is more important than throughput.
- Use
mqt.qecc when the workflow is broader than a single Stim detector model and you need a more general QEC toolkit spanning code construction and decoder experiments.
Standard Workflow Checklist
- Read
research-state.yaml for the current decoder-lane assumptions and open questions.
- Check
servers/resources/decoder_capability_matrix.yaml for the current backend fit summary.
- Classify the input artifact shape before discussing runtime or accuracy.
- Record which decoder constraints are scientifically acceptable for the task and which are not.
- Record why the selected backend fits better than the obvious alternatives.
Common Failure Modes
Treating graphlike matching as universal
Problem: a decoder that expects graphlike matching structure is proposed for a workload with hyperedges, rich correlations, or circuit-side heralding information.
Fix: stop and classify the artifact shape first. Do not flatten the problem just because a matching decoder is already installed.
Forgetting code-family specialization
Problem: a color-code-specific decoder is presented as a drop-in option for arbitrary CSS or QLDPC workloads.
Fix: record whether the backend is generic, color-code-specialized, or intentionally tuned to a narrower family.
Ignoring environment truth
Problem: a package is recommended without checking whether the current Python or wheel support makes it plausible in this repo.
Fix: use docs/TOOLKIT_REGISTRY.md and keep package fit separate from algorithmic desirability.
References
