Skip to content

Commit 7472fe7

Browse files
ChanceSiyuanclaude
ChanceSiyuan
and
claude
committed
Add minimum working example and pipeline illustration
- Add minimal_example.py with complete end-to-end demonstration - Add PIPELINE_ILLUSTRATION.md with visual pipeline diagrams - Include detailed explanations of each step - Show data flow and file formats - Provide conceptual understanding of the pipeline Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 369de2b commit 7472fe7

2 files changed

Lines changed: 563 additions & 0 deletions

File tree

‎examples/PIPELINE_ILLUSTRATION.md‎

Lines changed: 371 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,371 @@
1+
# Pipeline Illustration: From Circuit to Decoder
2+
3+
## Overview
4+
5+
This document illustrates the complete pipeline for quantum error correction with belief propagation decoding.
6+
7+
```
8+
┌─────────────┐
9+
│ START │
10+
└──────┬──────┘
11+
│
12+
▼
13+
┌─────────────────────────────────────────────────────────┐
14+
│ STEP 1: Generate Noisy Circuit │
15+
│ ───────────────────────────────────────────────────── │
16+
│ Input: distance=3, rounds=3, p=0.01, task="z" │
17+
│ Output: Stim circuit (.stim file) │
18+
│ │
19+
│ What it does: │
20+
│ - Creates a surface code circuit │
21+
│ - Adds depolarizing noise (p=0.01) to all operations │
22+
│ - Includes syndrome measurements and logical readout │
23+
└──────────────────────┬──────────────────────────────────┘
24+
│
25+
▼
26+
┌─────────────────────────────────────────────────────────┐
27+
│ STEP 2: Extract Detector Error Model (DEM) │
28+
│ ───────────────────────────────────────────────────── │
29+
│ Input: Circuit │
30+
│ Output: DEM (.dem file) │
31+
│ │
32+
│ What it does: │
33+
│ - Analyzes circuit to find all error mechanisms │
34+
│ - Determines which errors trigger which detectors │
35+
│ - Creates error(p) D1 D2 ... instructions │
36+
│ │
37+
│ Example DEM entry: │
38+
│ error(0.01) D0 D5 L0 │
39+
│ ↑ ↑ ↑ ↑ │
40+
│ │ │ │ └─ Flips logical observable │
41+
│ │ │ └──── Triggers detector 5 │
42+
│ │ └─────── Triggers detector 0 │
43+
│ └──────────────────── Probability 1% │
44+
└──────────────────────┬──────────────────────────────────┘
45+
│
46+
▼
47+
┌─────────────────────────────────────────────────────────┐
48+
│ STEP 3: Build Parity Check Matrix H │
49+
│ ───────────────────────────────────────────────────── │
50+
│ Input: DEM │
51+
│ Output: H matrix, priors, obs_flip │
52+
│ │
53+
│ What it does: │
54+
│ - Converts DEM to matrix form for BP decoder │
55+
│ - H[i,j] = 1 if error j triggers detector i │
56+
│ - priors[j] = probability of error j │
57+
│ - obs_flip[j] = 1 if error j flips observable │
58+
│ │
59+
│ Example: │
60+
│ H = [[1, 0, 1, 0, ...], ← Detector 0 │
61+
│ [0, 1, 1, 0, ...], ← Detector 1 │
62+
│ ...] │
63+
│ ↑ ↑ ↑ ↑ │
64+
│ Error mechanisms │
65+
└──────────────────────┬──────────────────────────────────┘
66+
│
67+
▼
68+
┌─────────────────────────────────────────────────────────┐
69+
│ STEP 4: Sample Syndromes │
70+
│ ───────────────────────────────────────────────────── │
71+
│ Input: Circuit, num_shots │
72+
│ Output: Syndromes, Observables (.npz file) │
73+
│ │
74+
│ What it does: │
75+
│ - Runs circuit num_shots times │
76+
│ - Records which detectors fire (syndrome) │
77+
│ - Records if logical qubit flips (observable) │
78+
│ │
79+
│ Example (1 shot): │
80+
│ Syndrome: [0, 1, 1, 0, 0, 1, 0, ...] │
81+
│ ↑ ↑ ↑ ↑ │
82+
│ Detectors 1, 2, 5 fired │
83+
│ Observable: 0 (no logical error) │
84+
└──────────────────────┬──────────────────────────────────┘
85+
│
86+
▼
87+
┌─────────────────────────────────────────────────────────┐
88+
│ STEP 5: Decode (BP Decoder) │
89+
│ ───────────────────────────────────────────────────── │
90+
│ Input: H, priors, syndrome │
91+
│ Output: Predicted observable flip │
92+
│ │
93+
│ What it does: │
94+
│ - Uses belief propagation on H matrix │
95+
│ - Infers most likely error pattern │
96+
│ - Predicts if errors flip logical observable │
97+
│ │
98+
│ Algorithm: │
99+
│ 1. Initialize beliefs from priors │
100+
│ 2. Pass messages between detectors and errors │
101+
│ 3. Iterate until convergence │
102+
│ 4. Decode to most likely error pattern │
103+
│ 5. Check if errors flip observable │
104+
└──────────────────────┬──────────────────────────────────┘
105+
│
106+
▼
107+
┌─────────────────────────────────────────────────────────┐
108+
│ STEP 6: Evaluate │
109+
│ ───────────────────────────────────────────────────── │
110+
│ Input: Predicted observable, Actual observable │
111+
│ Output: Success/Failure │
112+
│ │
113+
│ Success criterion: │
114+
│ Predicted == Actual → Decoding succeeded │
115+
│ Predicted != Actual → Logical error │
116+
│ │
117+
│ Metrics: │
118+
│ Logical error rate = (# failures) / (# shots) │
119+
└──────────────────────┬──────────────────────────────────┘
120+
│
121+
▼
122+
┌───────┐
123+
│ END │
124+
└───────┘
125+
```
126+
127+
## Data Flow Diagram
128+
129+
```
130+
Circuit Parameters Noisy Circuit Detector Error Model
131+
───────────────── ────────────── ────────────────────
132+
distance = 3 ──→ .stim file ──→ .dem file
133+
rounds = 3 (quantum ops) (error→detector map)
134+
p = 0.01 + noise model
135+
task = "z"
136+
│
137+
▼
138+
Parity Check Matrix
139+
───────────────────
140+
H: (24 × 286)
141+
priors: (286,)
142+
obs_flip: (286,)
143+
│
144+
▼
145+
Syndrome Samples ◄────────────────────────── BP Decoder Input
146+
──────────────── ────────────────
147+
.npz file H + syndrome
148+
syndromes: (N, 24) │
149+
observables: (N,) ▼
150+
Decoder Output
151+
──────────────
152+
predicted_obs: (N,)
153+
│
154+
▼
155+
Evaluation
156+
──────────
157+
accuracy
158+
logical_error_rate
159+
```
160+
161+
## Key Concepts Explained
162+
163+
### 1. Circuit → DEM: Why do we need this?
164+
165+
**Problem:** The circuit describes quantum operations, but we need to know:
166+
- Which errors can occur?
167+
- Which detectors do they trigger?
168+
- Do they cause logical errors?
169+
170+
**Solution:** The DEM extracts this information automatically.
171+
172+
**Example:**
173+
```
174+
Circuit says: "Apply CNOT gate with 1% depolarizing noise"
175+
DEM says: "This can cause 3 types of errors:
176+
- X error on control (triggers D0, D1)
177+
- Z error on target (triggers D2, D3)
178+
- Y error on both (triggers D0, D1, D2, D3, L0)"
179+
```
180+
181+
### 2. DEM → H Matrix: Why convert to matrix form?
182+
183+
**Problem:** DEM is a list of error instructions. BP decoder needs matrix operations.
184+
185+
**Solution:** Convert to parity check matrix H.
186+
187+
**Example:**
188+
```
189+
DEM:
190+
error(0.01) D0 D1
191+
error(0.01) D1 D2
192+
error(0.01) D0 D2 L0
193+
194+
H Matrix:
195+
E0 E1 E2
196+
D0 [ 1 0 1 ]
197+
D1 [ 1 1 0 ]
198+
D2 [ 0 1 1 ]
199+
200+
obs_flip: [0, 0, 1] ← Only E2 flips observable
201+
```
202+
203+
### 3. Circuit → Syndromes: What are we sampling?
204+
205+
**Problem:** We need training/test data for the decoder.
206+
207+
**Solution:** Run the circuit many times, record outcomes.
208+
209+
**What happens in one shot:**
210+
1. Initialize qubits in |0⟩ state
211+
2. Apply gates (with noise)
212+
3. Measure syndromes (detectors fire if errors occurred)
213+
4. Measure logical qubit (did it flip?)
214+
215+
**Example:**
216+
```
217+
Shot 1: Syndrome = [0,1,1,0,...], Observable = 0
218+
Shot 2: Syndrome = [1,0,0,1,...], Observable = 0
219+
Shot 3: Syndrome = [0,0,1,1,...], Observable = 1 ← Logical error!
220+
...
221+
```
222+
223+
### 4. H + Syndrome → Decoder: How does BP work?
224+
225+
**Input:**
226+
- H matrix (which errors trigger which detectors)
227+
- Syndrome (which detectors actually fired)
228+
- Priors (how likely is each error?)
229+
230+
**Process:**
231+
1. Start with prior beliefs about errors
232+
2. Update beliefs based on which detectors fired
233+
3. Pass messages between detectors and errors
234+
4. Iterate until beliefs converge
235+
5. Choose most likely error pattern
236+
237+
**Output:**
238+
- Predicted error pattern
239+
- Predicted observable flip
240+
241+
### 5. Predicted vs Actual: How do we evaluate?
242+
243+
**Success:** Predicted observable == Actual observable
244+
- Decoder correctly identified the error pattern
245+
- Logical qubit is protected
246+
247+
**Failure:** Predicted observable != Actual observable
248+
- Decoder made a mistake
249+
- Logical error occurred
250+
251+
**Metric:** Logical error rate = P(failure)
252+
253+
## File Formats
254+
255+
### Circuit File (.stim)
256+
```
257+
QUBIT_COORDS(0, 0) 0
258+
QUBIT_COORDS(1, 0) 1
259+
...
260+
R 0 1 2 3
261+
DEPOLARIZE1(0.01) 0 1 2 3
262+
CX 0 1
263+
DEPOLARIZE2(0.01) 0 1
264+
...
265+
DETECTOR(0, 0, 0) rec[-1]
266+
OBSERVABLE_INCLUDE(0) rec[-1]
267+
```
268+
269+
### DEM File (.dem)
270+
```
271+
error(0.01) D0 D1
272+
error(0.01) D1 D2
273+
error(0.01) D0 D2 L0
274+
...
275+
```
276+
277+
### Syndrome Database (.npz)
278+
```python
279+
{
280+
'syndromes': array([[0, 1, 1, 0, ...], # Shot 0
281+
[1, 0, 0, 1, ...], # Shot 1
282+
...]),
283+
'observables': array([0, 0, 1, ...]),
284+
'metadata': '{"distance": 3, "rounds": 3, ...}'
285+
}
286+
```
287+
288+
## Complete Example
289+
290+
### Input Parameters
291+
```python
292+
distance = 3
293+
rounds = 3
294+
p = 0.01
295+
task = "z"
296+
num_shots = 1000
297+
```
298+
299+
### Generated Files
300+
```
301+
datasets/noisy_circuits/
302+
├── sc_d3_r3_p0010_z.stim # Circuit (2.5 KB)
303+
├── sc_d3_r3_p0010_z.dem # DEM (15 KB)
304+
└── sc_d3_r3_p0010_z.npz # Syndromes (3 KB)
305+
```
306+
307+
### Data Shapes
308+
```
309+
Circuit: ~100 operations
310+
DEM: 24 detectors, 286 error mechanisms
311+
H matrix: (24, 286)
312+
Syndromes: (1000, 24)
313+
Observables: (1000,)
314+
```
315+
316+
### Expected Results
317+
```
318+
Detection rate: ~3-5%
319+
Logical error rate: ~0.5-1% (without decoder)
320+
~0.1-0.3% (with good decoder)
321+
```
322+
323+
## Running the Pipeline
324+
325+
### Command Line
326+
```bash
327+
# Generate everything at once
328+
uv run generate-noisy-circuits \
329+
--distance 3 \
330+
--p 0.01 \
331+
--rounds 3 5 7 \
332+
--task z \
333+
--generate-dem \
334+
--generate-syndromes 1000
335+
```
336+
337+
### Python API
338+
```python
339+
from bpdecoderplus.circuit import generate_circuit
340+
from bpdecoderplus.dem import extract_dem, build_parity_check_matrix
341+
from bpdecoderplus.syndrome import sample_syndromes
342+
343+
# Generate circuit
344+
circuit = generate_circuit(distance=3, rounds=3, p=0.01, task="z")
345+
346+
# Extract DEM and build H
347+
dem = extract_dem(circuit)
348+
H, priors, obs_flip = build_parity_check_matrix(dem)
349+
350+
# Sample syndromes
351+
syndromes, observables = sample_syndromes(circuit, num_shots=1000)
352+
353+
# Now ready for decoder!
354+
```
355+
356+
## Next Steps
357+
358+
1. **Implement BP Decoder** (Issue #3)
359+
- Use H matrix and priors
360+
- Implement message passing
361+
- Decode syndromes to error patterns
362+
363+
2. **Evaluate Decoder**
364+
- Compare predicted vs actual observables
365+
- Compute logical error rate
366+
- Compare with other decoders (MWPM, Neural)
367+
368+
3. **Optimize Performance**
369+
- Tune BP hyperparameters (damping, iterations)
370+
- Try BP+OSD for better accuracy
371+
- Scale to larger codes (d=5, d=7)

0 commit comments

Comments
 (0)