simulating-erasure-qubit-protocols

name	simulating-erasure-qubit-protocols
description	Guides erasure-aware Stim simulation using the local Erasure_qubit-1 repo, with explicit separation between latent-erasure sampling, approximate decoding circuits, posterior or multi-check processing, and small local smoke runs.
version	0.1.0
author	QEC Research Skills
license	MIT
tags	["QEC","Erasure","Stim","Sinter","Surface Code","HGP"]
dependencies	["qec-research","building-stim-circuits","decoding-with-ldpc"]

Simulating Erasure-Qubit Protocols

What This Skill Is For

Use this skill when the task is to reproduce or adapt erasure-aware circuit simulations similar to the local Erasure_qubit-1 repo:

• build erasure-aware Stim circuits,
• separate latent-erasure sampling from decoding-model construction,
• use single-check, multi-check, posterior, or sliding-window variants,
• run a small local smoke test before any large sweep.

When To Use It Versus Alternatives

Use this skill when the main issue is erasure information, erasure-detection events, or posterior-informed decoding.

Use building-stim-circuits when the task is generic Stim authoring with no erasure-specific logic.

Use decoding-with-ldpc when the detector model already exists and erasure modeling is not the active design problem.

Required Artifacts And Assumptions

Expected inputs:

• code family or parity-check matrices,
• erasure, depolarizing, and erasure-detection parameters,
• whether the run is single-check, multi-check, posterior, or sliding-window,
• local versus cluster-scale intent.

Expected outputs:

• an erasure-workflow plan,
• explicit sampling-circuit versus decoding-circuit notes,
• decoder configuration notes,
• a smoke-test configuration.

Assumptions to make explicit:

• whether the core builder is HGP-style (H1, H2) or rotated-surface-code style,
• whether the decoder uses sliding-window BP-OSD, posterior-informed matching, or multi-check processing,
• whether the run is optimized for local speed (osd_0) or cluster performance (osd_cs with higher order).

Standard Workflow Checklist

1. Read references/local-repo-workflow.md.
2. Identify the intended subworkflow: src/ for HGP coloration plus sliding-window decoding, multi_check/ for true-process versus approximate-decoder separation, multi_check1/ for alternate or exact multi-check variants, or BP_multi_check/ for posterior and BP-assisted branches.
3. Keep latent-erasure sampling and approximate decoding-circuit construction as separate steps.
4. Start with a small-shot run and only then widen shot count, check count, or OSD order.
5. Record the exact erasure parameters and decoder configuration before comparing runs.
6. Preserve syndrome, posterior, or erasure-detection artifacts instead of only reporting final logical error rates.

Validation Loop

Before closing work:

1. confirm the workflow names both the sampling circuit and the decoding circuit,
2. confirm erasure, depolarizing, and detection-noise parameters are explicit,
3. confirm the local-versus-cluster decoder setting is stated,
4. confirm the first run is a smoke test, not a production threshold claim.

Common Issues And Fixes

Sampling/decoding collapse

Problem: one circuit is treated as both the true noisy process and the decoding model.

Fix: follow the local repo pattern and separate them explicitly.

Decoder configuration drift

Problem: OSD settings change across runs without being tracked.

Fix: write down osd_method, order, window, commit, and check-count choices.

Jumping straight to multi-check sweeps

Problem: large multi-check runs start before a small local path works.

Fix: smoke test a tiny instance first.

Launching multiprocessing from stdin

Problem: the src/sinter_decoding.py path is launched from an inline stdin snippet and Python spawn workers fail to recover the entry script.

Fix: run the real script or module path directly, or reduce to a single-worker local smoke harness before scaling back up to the repo's sinter.collect(...) path.

References

• references/api.md
• references/examples.md
• references/local-repo-workflow.md
• ../../01-circuits/building-stim-circuits/SKILL.md
• ../../02-decoders/decoding-with-ldpc/SKILL.md
• ../../docs/TOOLKIT_REGISTRY.md