choosing-qec-decoders

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:

1. 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?
2. Is the code family repetition, surface, color, generic CSS, or QLDPC?
3. Is the noise model code-capacity-like, phenomenological, circuit-level, or erasure-aware?
4. Do you need a fast benchmark baseline, an exact matching answer, a color-code-specialized decoder, or a hypergraph-capable route?
5. 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

1. Read research-state.yaml for the current decoder-lane assumptions and open questions.
2. Check servers/resources/decoder_capability_matrix.yaml for the current backend fit summary.
3. Classify the input artifact shape before discussing runtime or accuracy.
4. Record which decoder constraints are scientifically acceptable for the task and which are not.
5. 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

• references/api.md
• references/examples.md
• ../decoding-with-pymatching/SKILL.md
• ../decoding-with-fusion-blossom/SKILL.md
• ../decoding-with-tesseract-decoder/SKILL.md
• ../planning-qec-workflows-with-mqt-qecc/SKILL.md
• docs/TOOLKIT_REGISTRY.md
• servers/resources/decoder_capability_matrix.yaml
• servers/resources/decoder_workload_templates.yaml