decoding-with-fusion-blossom

name	decoding-with-fusion-blossom
description	Guides exact-MWPM graphlike decoding with fusion-blossom, including erasure-aware matching updates, while keeping clear boundaries with PyMatching and non-graphlike decoder lanes.
version	0.1.0
author	QEC Research Skills
license	MIT
tags	["QEC","fusion-blossom","MWPM","Decoders"]
dependencies	["qec-research","building-stim-circuits","choosing-qec-decoders"]

Decoding With fusion-blossom

What This Skill Is For

Use this skill when the task is still a matching-graph problem but you want the fusion-blossom lane specifically:

• plan an exact-MWPM comparison against PyMatching,
• keep graphlike Stim workflows honest about when erasure information can be represented as matching-weight updates,
• explain the sparse decoding-graph design instead of treating fusion-blossom as "just another matching decoder",
• prepare a future adapter without claiming the repo already integrates it.

When To Use It Versus Alternatives

Use this skill when the workload is:

• rooted in a graphlike detector model,
• still scientifically acceptable as a matching reduction,
• better framed as exact MWPM or erasure-aware matching than as a fast executable baseline.

Prefer decoding-with-pymatching when the goal is the repo's current integrated matching lane.

Prefer choosing-qec-decoders when the main question is whether the problem should stay in the matching lane at all.

Do not use this skill to flatten hypergraph, color-code-specialized, or full-circuit heralded-erasure workloads that belong to mwpf, chromobius, or other richer lanes.

Current Repo Boundary

This repo does not yet ship a fusion-blossom adapter or smoke test.

The correct current use is:

• plan a fusion-blossom workflow precisely,
• record why exact MWPM or erasure-aware matching matters,
• leave the result in the "adapter-planned" state unless the environment and service lane are added.

Required Artifacts And Assumptions

Expected future repo inputs:

• DetectorModelBundle,
• TrajectoryBundle,
• optional erasure-side information only when it can truly be encoded as a matching-graph update.

Assumptions to make explicit:

• the detector model is graphlike,
• the scientific claim tolerates a matching reduction,
• any erasure handling stays inside the matching graph instead of requiring the full parent circuit.

Standard Workflow Checklist

1. Read research-state.yaml for the current decoder-roadmap assumptions.
2. Check servers/resources/decoder_capability_matrix.yaml and servers/resources/decoder_workload_templates.yaml.
3. Record why PyMatching is insufficient for the task.
4. Record whether the target study is exact-MWPM comparison, erasure-aware matching, or tutorial/visualization work.
5. Keep the summary explicit that this is a planned lane, not an integrated repo backend.

Validation Loop

Before closing work:

1. confirm the problem remains graphlike,
2. confirm erasure information does not require a richer full-circuit decoder,
3. confirm the writeup says "planned fusion-blossom lane" instead of implying executable repo support,
4. confirm the claimed value is exact MWPM or matching-graph ergonomics, not universal decoding scope.

Common Issues And Fixes

Treating exact MWPM as universal decoding

Problem: fusion-blossom is proposed for a workload whose main difficulty is hypergraph structure or full-circuit heralding, not exact matching.

Fix: route back through choosing-qec-decoders and check whether the problem should leave the matching lane entirely.

Confusing erasure-aware matching with general erasure decoding

Problem: a heralded-erasure workflow is described as matching-compatible without checking whether the side information survives as edge-weight updates.

Fix: say explicitly whether the erasure model is matching-representable. If it is not, move toward mwpf or a protocol-specific erasure lane.

Overclaiming repo support

Problem: a user-facing answer sounds like the repo can already run fusion-blossom.

Fix: keep the language narrow. This skill distills the upstream lane and how to adopt it; it does not mean the adapter already exists here.

References

• references/api.md
• references/examples.md
• docs/TOOLKIT_REGISTRY.md
• servers/resources/decoder_capability_matrix.yaml
• servers/resources/decoder_workload_templates.yaml