planning-qec-workflows-with-mqt-qecc

name	planning-qec-workflows-with-mqt-qecc
description	Guides use of MQT QECC for toolkit-native code, decoder, color-code, and state-preparation workflows while keeping clear boundaries with Stim-native and qLDPC-native lanes.
version	0.1.0
author	QEC Research Skills
license	MIT
tags	["QEC","MQT","QECC","Decoders","QLDPC","Color Codes"]
dependencies	["qec-research","choosing-qec-decoders","studying-qldpc-codes-with-qldpc"]

Planning QEC Workflows With MQT QECC

What This Skill Is For

Use this skill when the task starts from MQT QECC's own toolkit objects and workflow families instead of a finished Stim detector-model artifact:

• build or inspect toolkit-native code objects,
• try union-find-style QLDPC decoding baselines,
• reason about the LightsOut color-code decoder lane,
• plan CSS state-preparation or ECC-transformed circuit studies,
• decide whether MQT QECC fits better than PyMatching, mwpf, qLDPC, or Stim-first tooling.

When To Use It Versus Alternatives

Use this skill when the main request is about:

• parity-check matrices and code objects that naturally live inside mqt.qecc.Code,
• decoder studies where UFHeuristic or other toolkit-native routines are part of the scientific method,
• triangular color-code studies that intentionally use the LightsOut or related MQT color-code lane,
• CSS-state-preparation synthesis where the code structure matters as much as the final circuit.

Use choosing-qec-decoders when the first question is decoder routing across several backends.

Use studying-qldpc-codes-with-qldpc when the task is broader code construction and structural analysis rather than MQT-specific execution planning.

Use building-stim-circuits when the workflow already starts from a Stim circuit or detector error model.

Required Artifacts And Assumptions

Expected inputs:

• a code description, parity-check matrices, or a named code family,
• the target lane: union-find decoding, color-code decoding, state preparation, or ECC-transformed circuits,
• the intended noise model and whether perfect syndrome measurements are acceptable,
• the desired output artifact: code object, decoder result, synthesized preparation circuit, or transformed OpenQASM circuit.

Expected outputs:

• an MQT QECC workflow plan,
• the upstream API surface that fits the task,
• explicit boundary notes about what should remain in MQT QECC versus what should hand off to Stim, PyMatching, or another decoder,
• a minimal example or smoke-test plan.

Assumptions to make explicit:

• whether the task is detector-model-centric or toolkit-native,
• whether the workload is qLDPC, color-code, CSS-state-preparation, or circuit rewriting,
• whether perfect-syndrome, phenomenological, or circuit-level details matter,
• whether the current repo is only planning the workflow or truly integrating it.

Standard Workflow Checklist

1. Read references/toolkit-fit.md before picking MQT QECC.
2. State which lane is intended: Code plus UFHeuristic, LightsOut color-code decoding, state-preparation synthesis, or apply_ecc.
3. Write down the code family, input artifact shape, and acceptable noise-model simplifications.
4. Keep toolkit-native artifacts explicit instead of flattening everything into a Stim DEM story.
5. Record whether the requested workflow stays local to MQT QECC or needs a later handoff into another backend.
6. Treat current support in this repo as documentation-first until a real adapter, smoke test, and health-check path exist.

Validation Loop

Before closing work:

1. confirm the selected MQT lane matches the task instead of being a generic "more QEC tools" choice,
2. confirm the code family and noise assumptions are explicit,
3. confirm any handoff to Stim or another decoder is recorded as a boundary, not hidden,
4. confirm no claim implies that MQT QECC is already integrated in the repo's executable baseline.

Common Issues And Fixes

Flattening toolkit-native work into DEM-only language

Problem: an MQT workflow gets described as though it were just another detector-model decoder.

Fix: keep Code, syndrome, color-code lattice, or CSS-synthesis artifacts visible. The point of MQT QECC is broader than a DEM consumer.

Choosing MQT QECC for the wrong workload

Problem: a graphlike Stim DEM baseline is routed into MQT QECC when PyMatching or fusion-blossom would be the cleaner route.

Fix: decide first whether the science needs toolkit-native code models or only a matching decoder over detector events.

Overclaiming color-code generality

Problem: the LightsOut lane gets presented as a decoder for arbitrary CSS or QLDPC workloads.

Fix: keep the color-code specialization explicit and record when a more general decoder is needed.

References

• references/api.md
• references/examples.md
• references/toolkit-fit.md
• ../choosing-qec-decoders/SKILL.md
• ../../04-qldpc/studying-qldpc-codes-with-qldpc/SKILL.md
• ../../docs/TOOLKIT_REGISTRY.md