| name | simulating-cc-code-surgery-protocols |
| description | Guides color-code and related surgery-protocol simulation using local surgery implementations, with explicit matrix, circuit, detector-model, and decoder validation stages. |
| version | 0.1.0 |
| author | QEC Research Skills |
| license | MIT |
| tags | ["QEC","Surgery","Color Code","Stim","BP-OSD"] |
| dependencies | ["qec-research","building-stim-circuits","decoding-with-ldpc"] |
Simulating CC Code Surgery Protocols
What This Skill Is For
Use this skill when the task is to build, inspect, or validate a surgery protocol similar to the local color-code surgery stack:
- construct connection-code matrices,
- generate exact X- or Z-type surgery circuits,
- extract detector error models,
- run a decoded smoke test before scaling,
- stage validation carefully before any broader sweep workflow.
When To Use It Versus Alternatives
Use this skill when the protocol begins from matrix-level surgery design and ends in a decoded Stim workflow.
Use building-stim-circuits when the circuit structure is already fixed.
Use decoding-with-ldpc when the detector-model artifacts already exist and the task is decoder-only.
Required Artifacts And Assumptions
Expected inputs:
- surgery type (
X or Z),
- code family or code name,
- connection-code data such as
H_a' and H_b',
- noise model and round counts,
- whether the task is semantic verification, DEM extraction, or decoded performance.
Expected outputs:
- a matrix-layer plan,
- a circuit-generation plan,
- DEM and decoder handoff notes,
- a smoke-test plan before any sweep.
Assumptions to make explicit:
- whether the task follows the
cc_surgery matrix/circuit conventions,
- whether BP-OSD is the intended first decoder,
- whether the workflow needs only the
cc_surgery matrix/circuit/decoder path or a more general future adapter.
Standard Workflow Checklist
- Read
references/local-repo-workflow.md and decide whether the request is best matched by the cc_surgery lane
- Start at the matrix layer: pick example data or construct new
H_a' and H_b'.
- Check commutation and measured-observable counts before generating any noisy circuit.
- Build the exact surgery circuit with explicit noise and round counts.
- Compile the detector error model and sample a decoded smoke test before any sweep.
- Only after the smoke path works, move to
sweep.py, plot_threshold.py, or broader sinter-style batch workflows.
Validation Loop
Before closing work:
- confirm matrix commutation or analogous structural checks passed,
- confirm the exact circuit builder and noise model are named explicitly,
- confirm DEM extraction happened before decoder benchmarking claims,
- confirm the first run is a smoke test, not a threshold claim.
Common Issues And Fixes
Starting from sweeps instead of invariants
Problem: the workflow jumps directly to large runs.
Fix: run semantic and matrix checks first.
Overfitting to one private implementation
Problem: the workflow depends on details of a non-public local implementation instead of portable principles.
Fix: keep only the reusable ideas: staged validation, explicit measurement scheduling, logical deformation bookkeeping, DEM bookkeeping, and batch simulation design.
Decoder-first reasoning
Problem: BP-OSD configuration is discussed before the circuit and DEM are stable.
Fix: freeze the matrix and circuit layers first, then decode.
References
