Skip to content

Commit 7bcdb6f

Browse files
DeDuckProjectDeDuckProject
authored
Added stim circuits (#8)
1 parent db20fed commit 7bcdb6f

9 files changed

Lines changed: 820 additions & 0 deletions

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ python tesseract_sim/plotting/plot_acceptance_rates.py \
4242
### Features
4343

4444
- Circuit implementation of the [[16,4,4]] Tesseract subsystem color code [[1]](#references) in Stim, including encoding, error correction rounds and final measurements.
45+
- Pre-generated stim circuit files for common operations (see [`stim_circuits/`](stim_circuits/README.md) directory).
4546
- Simulation of an error correction experiment with configurable noise setting, rounds, shot and more.
4647
- Plotting: sweeping of different parameters and obtaining acceptance rate and logical success rate.
4748

@@ -82,6 +83,13 @@ tesseract-code-stim/
8283
│ ├── plotting/ # Visualization and analysis
8384
│ │ └── plot_acceptance_rates.py # Generate acceptance/success rate plots
8485
│ └── run.py # Main simulation entry point
86+
├── stim_circuits/ # Pre-generated stim circuit files
87+
│ ├── encoding_9a.stim # Encoding circuit for |++0000⟩ state
88+
│ ├── encoding_9b.stim # Encoding circuit for |+0+0+0⟩ state
89+
│ ├── error_correction_round.stim # Single EC round circuit
90+
│ ├── decoding.stim # Final measurement and decoding
91+
│ ├── complete_experiment_*.stim # Full experiment pipelines
92+
│ └── README.md # Stim circuits documentation and usage
8593
├── notebooks/ # Jupyter notebooks for experiments
8694
│ ├── encoding_circuits_visualization.ipynb # Circuit visualization
8795
│ ├── entire_experiment_circuit.ipynb # Complete experiment demo
@@ -102,6 +110,7 @@ tesseract-code-stim/
102110
- **`tesseract_sim/error_correction/`**: Manual decoder with correction rules and measurement rounds
103111
- **`tesseract_sim/noise/`**: Configurable noise injection for encoding and error correction phases
104112
- **`tesseract_sim/plotting/`**: Analysis and visualization tools for acceptance rates and logical success rates
113+
- **`stim_circuits/`**: Pre-generated stim circuit files for direct use with stim or other simulators
105114
- **`notebooks/`**: Interactive Jupyter notebooks for experiments and visualization
106115
- **`tests/`**: Comprehensive test suite covering all major functionality
107116

‎stim_circuits/README.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Tesseract Code Stim Circuit Files
2+
3+
This directory contains pre-generated stim circuit files for common tesseract code operations. These files can be used independently with stim.
4+
**An important note** is that the calculation of the Pauli frame is not included in these files, since it is achieved by classical computation done using Python code, outside of the Stim runtime. This means that running these circuits will not do the actual correction at the end. Check the Python code for the complete implementation.
5+
6+
## Generated Files
7+
8+
### 1. Encoding Circuits
9+
10+
- **`encoding_9a.stim`** - Encoding circuit for the |++0000⟩ state (Fig 9a)
11+
- 23 qubits total (16 data + 7 ancillas)
12+
- Prepares the tesseract code in the |++0000⟩ logical state
13+
14+
- **`encoding_9b.stim`** - Encoding circuit for the |+0+0+0⟩ state (Fig 9b)
15+
- 18 qubits total (16 data + 2 ancillas)
16+
- Prepares the tesseract code in the |+0+0+0⟩ logical state
17+
18+
### 2. Error Correction
19+
20+
- **`error_correction_round.stim`** - Single round of error correction
21+
- 18 qubits total (16 data + 2 ancillas)
22+
- Measures stabilizers for both rows and columns
23+
- Includes flagged syndrome extraction
24+
25+
### 3. Decoding
26+
27+
- **`decoding.stim`** - Final measurement and decoding by diving to two [[8,3,2]] color codes
28+
- 18 qubits total (16 data + 2 ancillas)
29+
- Splits the tesseract code into two [[8,3,2]] color codes
30+
- Measures top half in X basis, bottom half in Z basis
31+
32+
### 4. Complete Experiments
33+
34+
- **`complete_experiment_9a.stim`** - Full experiment with 9a encoding
35+
- Encoding (9a) → 3 rounds of error correction → decoding
36+
- 23 qubits total
37+
38+
- **`complete_experiment_9b.stim`** - Full experiment with 9b encoding
39+
- Encoding (9b) → 3 rounds of error correction → decoding
40+
- 18 qubits total
41+
42+
## Qubit Layout
43+
44+
All circuits use a consistent qubit layout:
45+
46+
```
47+
Data qubits (0-15) arranged in 4×4 grid:
48+
Row 1: 0 1 2 3 (y=0, x=0-3)
49+
Row 2: 4 5 6 7 (y=1, x=0-3)
50+
Row 3: 8 9 10 11 (y=2, x=0-3)
51+
Row 4: 12 13 14 15 (y=3, x=0-3)
52+
53+
Ancilla qubits: 16, 17, ... (at x=5, y=0,1,2,...)
54+
```
55+
56+
## Usage Examples
57+
58+
### Using with stim directly
59+
60+
```bash
61+
# Simulate the complete 9b experiment with 1000 shots
62+
stim sample --shots 1000 --in complete_experiment_9a.stim
63+
```
64+
65+
### Using in Python
66+
67+
```python
68+
import stim
69+
70+
# Load a circuit
71+
circuit = stim.Circuit.from_file("encoding_9a.stim")
72+
73+
# Run simulation
74+
sampler = circuit.compile_sampler()
75+
samples = sampler.sample(shots=1000)
76+
77+
# Get detector error model
78+
dem = circuit.detector_error_model()
79+
```
80+
81+
### Combining circuits
82+
83+
```python
84+
import stim
85+
86+
# Load individual components
87+
encoding = stim.Circuit.from_file("encoding_9a.stim")
88+
ec_round = stim.Circuit.from_file("error_correction_round.stim")
89+
decoding = stim.Circuit.from_file("decoding.stim")
90+
91+
# Combine into custom experiment
92+
custom_circuit = stim.Circuit()
93+
custom_circuit += encoding
94+
95+
# Add noise channel
96+
custom_circuit.append("DEPOLARIZE1", range(16), 0.001)
97+
98+
# Add multiple EC rounds
99+
for _ in range(5): # 5 rounds instead of 3
100+
custom_circuit += ec_round
101+
102+
custom_circuit += decoding
103+
```
104+
105+
## Generation
106+
107+
These files were generated using `generate_stim_files.py`, which uses the existing tesseract-code-stim Python implementation to build the circuits and export them to stim format.
108+
109+
To regenerate the files:
110+
111+
```bash
112+
python stim_circuits/generate_stim_files.py
113+
```
114+
115+
## Related Papers
116+
117+
- "Demonstration of quantum computation and error correction with a tesseract code" - http://arxiv.org/abs/2409.04628
118+
- "The smallest interesting colour code" by Earl Campbell - https://earltcampbell.com/2016/09/26/the-smallest-interesting-colour-code/

‎stim_circuits/complete_experiment_9a.stim‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Complete experiment: encoding 9a -> 3 EC rounds -> decoding
2+
# Generated from tesseract-code-stim project
3+
# Circuit has 23 qubits total
4+
#
5+
# Qubit layout:
6+
# - Qubits 0-15: Data qubits arranged in 4x4 grid
7+
# - Qubits 16+: Ancilla qubits for measurements
8+
#
9+
# Coordinate system:
10+
# - Qubits 0-3: row 1 (y=0, x=0-3)
11+
# - Qubits 4-7: row 2 (y=1, x=0-3)
12+
# - Qubits 8-11: row 3 (y=2, x=0-3)
13+
# - Qubits 12-15: row 4 (y=3, x=0-3)
14+
#
15+
16+
QUBIT_COORDS(0, 0) 0
17+
QUBIT_COORDS(1, 0) 1
18+
QUBIT_COORDS(2, 0) 2
19+
QUBIT_COORDS(3, 0) 3
20+
QUBIT_COORDS(0, 1) 4
21+
QUBIT_COORDS(1, 1) 5
22+
QUBIT_COORDS(2, 1) 6
23+
QUBIT_COORDS(3, 1) 7
24+
QUBIT_COORDS(0, 2) 8
25+
QUBIT_COORDS(1, 2) 9
26+
QUBIT_COORDS(2, 2) 10
27+
QUBIT_COORDS(3, 2) 11
28+
QUBIT_COORDS(0, 3) 12
29+
QUBIT_COORDS(1, 3) 13
30+
QUBIT_COORDS(2, 3) 14
31+
QUBIT_COORDS(3, 3) 15
32+
QUBIT_COORDS(5, 0) 16
33+
QUBIT_COORDS(5, 1) 17
34+
QUBIT_COORDS(5, 2) 18
35+
QUBIT_COORDS(5, 3) 19
36+
QUBIT_COORDS(5, 4) 20
37+
QUBIT_COORDS(5, 5) 21
38+
QUBIT_COORDS(5, 6) 22
39+
TICK # Start encoding based on Fig. 9a
40+
H 0 1 2 3 4 8 12
41+
CX 4 20 4 5 4 6 4 7 4 20 8 21 8 9 8 10 8 11 8 21 12 22 12 13 12 14 12 15 12 22 0 16 1 17 2 18 3 19 0 4 1 5 2 6 3 7 0 8 1 9 2 10 3 11 0 12 1 13 2 14 3 15 0 16 1 17 2 18 3 19
42+
R 18 19
43+
H 19
44+
CX 19 18 19 0 19 1 19 2 19 3 19 18
45+
TICK # Start error correction round 1
46+
R 16 17 # Start measure row 1
47+
H 16
48+
CX 0 17 16 1 1 17 16 0 2 17 16 3 3 17 16 2
49+
H 16
50+
M 16 17
51+
R 16 17 # Start measure row 2
52+
H 16
53+
CX 4 17 16 5 5 17 16 4 6 17 16 7 7 17 16 6
54+
H 16
55+
M 16 17
56+
R 16 17 # Start measure row 3
57+
H 16
58+
CX 8 17 16 9 9 17 16 8 10 17 16 11 11 17 16 10
59+
H 16
60+
M 16 17
61+
R 16 17 # Start measure row 4
62+
H 16
63+
CX 12 17 16 13 13 17 16 12 14 17 16 15 15 17 16 14
64+
H 16
65+
M 16 17
66+
R 16 17 # Start measure column 1
67+
H 16
68+
CX 0 17 16 4 4 17 16 0 8 17 16 12 12 17 16 8
69+
H 16
70+
M 16 17
71+
R 16 17 # Start measure column 2
72+
H 16
73+
CX 1 17 16 5 5 17 16 1 9 17 16 13 13 17 16 9
74+
H 16
75+
M 16 17
76+
R 16 17 # Start measure column 3
77+
H 16
78+
CX 2 17 16 6 6 17 16 2 10 17 16 14 14 17 16 10
79+
H 16
80+
M 16 17
81+
R 16 17 # Start measure column 4
82+
H 16
83+
CX 3 17 16 7 7 17 16 3 11 17 16 15 15 17 16 11
84+
H 16
85+
M 16 17
86+
TICK # Start error correction round 2
87+
R 16 17 # Start measure row 1
88+
H 16
89+
CX 0 17 16 1 1 17 16 0 2 17 16 3 3 17 16 2
90+
H 16
91+
M 16 17
92+
R 16 17 # Start measure row 2
93+
H 16
94+
CX 4 17 16 5 5 17 16 4 6 17 16 7 7 17 16 6
95+
H 16
96+
M 16 17
97+
R 16 17 # Start measure row 3
98+
H 16
99+
CX 8 17 16 9 9 17 16 8 10 17 16 11 11 17 16 10
100+
H 16
101+
M 16 17
102+
R 16 17 # Start measure row 4
103+
H 16
104+
CX 12 17 16 13 13 17 16 12 14 17 16 15 15 17 16 14
105+
H 16
106+
M 16 17
107+
R 16 17 # Start measure column 1
108+
H 16
109+
CX 0 17 16 4 4 17 16 0 8 17 16 12 12 17 16 8
110+
H 16
111+
M 16 17
112+
R 16 17 # Start measure column 2
113+
H 16
114+
CX 1 17 16 5 5 17 16 1 9 17 16 13 13 17 16 9
115+
H 16
116+
M 16 17
117+
R 16 17 # Start measure column 3
118+
H 16
119+
CX 2 17 16 6 6 17 16 2 10 17 16 14 14 17 16 10
120+
H 16
121+
M 16 17
122+
R 16 17 # Start measure column 4
123+
H 16
124+
CX 3 17 16 7 7 17 16 3 11 17 16 15 15 17 16 11
125+
H 16
126+
M 16 17
127+
TICK # Start error correction round 3
128+
R 16 17 # Start measure row 1
129+
H 16
130+
CX 0 17 16 1 1 17 16 0 2 17 16 3 3 17 16 2
131+
H 16
132+
M 16 17
133+
R 16 17 # Start measure row 2
134+
H 16
135+
CX 4 17 16 5 5 17 16 4 6 17 16 7 7 17 16 6
136+
H 16
137+
M 16 17
138+
R 16 17 # Start measure row 3
139+
H 16
140+
CX 8 17 16 9 9 17 16 8 10 17 16 11 11 17 16 10
141+
H 16
142+
M 16 17
143+
R 16 17 # Start measure row 4
144+
H 16
145+
CX 12 17 16 13 13 17 16 12 14 17 16 15 15 17 16 14
146+
H 16
147+
M 16 17
148+
R 16 17 # Start measure column 1
149+
H 16
150+
CX 0 17 16 4 4 17 16 0 8 17 16 12 12 17 16 8
151+
H 16
152+
M 16 17
153+
R 16 17 # Start measure column 2
154+
H 16
155+
CX 1 17 16 5 5 17 16 1 9 17 16 13 13 17 16 9
156+
H 16
157+
M 16 17
158+
R 16 17 # Start measure column 3
159+
H 16
160+
CX 2 17 16 6 6 17 16 2 10 17 16 14 14 17 16 10
161+
H 16
162+
M 16 17
163+
R 16 17 # Start measure column 4
164+
H 16
165+
CX 3 17 16 7 7 17 16 3 11 17 16 15 15 17 16 11
166+
H 16
167+
M 16 17
168+
TICK
169+
CX 0 12 1 13 2 14 3 15 4 8 5 9 6 10 7 11 # row-transversal CNOT from row 1 -> 4, row 2 -> 3
170+
H 0 1 2 3 4 5 6 7 # Change top half's basis so its measured in the X basis
171+
M 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 # Measure all physical qubits
172+
TICK

0 commit comments

Comments
 (0)