Added stim circuits

README.md

@@ -42,6 +42,7 @@ python tesseract_sim/plotting/plot_acceptance_rates.py \
 ### Features
 
 - Circuit implementation of the [[16,4,4]] Tesseract subsystem color code [[1]](#references) in Stim, including encoding, error correction rounds and final measurements.
+- Pre-generated stim circuit files for common operations (see [`stim_circuits/`](stim_circuits/README.md) directory).
 - Simulation of an error correction experiment with configurable noise setting, rounds, shot and more.
 - Plotting: sweeping of different parameters and obtaining acceptance rate and logical success rate.
 
@@ -82,6 +83,13 @@ tesseract-code-stim/
 │   ├── plotting/            # Visualization and analysis
 │   │   └── plot_acceptance_rates.py  # Generate acceptance/success rate plots
 │   └── run.py               # Main simulation entry point
+├── stim_circuits/           # Pre-generated stim circuit files
+│   ├── encoding_9a.stim     # Encoding circuit for |++0000⟩ state
+│   ├── encoding_9b.stim     # Encoding circuit for |+0+0+0⟩ state
+│   ├── error_correction_round.stim  # Single EC round circuit
+│   ├── decoding.stim        # Final measurement and decoding
+│   ├── complete_experiment_*.stim   # Full experiment pipelines
+│   └── README.md            # Stim circuits documentation and usage
 ├── notebooks/               # Jupyter notebooks for experiments
 │   ├── encoding_circuits_visualization.ipynb    # Circuit visualization
 │   ├── entire_experiment_circuit.ipynb          # Complete experiment demo
@@ -102,6 +110,7 @@ tesseract-code-stim/
 - **`tesseract_sim/error_correction/`**: Manual decoder with correction rules and measurement rounds
 - **`tesseract_sim/noise/`**: Configurable noise injection for encoding and error correction phases
 - **`tesseract_sim/plotting/`**: Analysis and visualization tools for acceptance rates and logical success rates
+- **`stim_circuits/`**: Pre-generated stim circuit files for direct use with stim or other simulators
 - **`notebooks/`**: Interactive Jupyter notebooks for experiments and visualization
 - **`tests/`**: Comprehensive test suite covering all major functionality
 

stim_circuits/README.md

@@ -0,0 +1,118 @@
+# Tesseract Code Stim Circuit Files
+
+This directory contains pre-generated stim circuit files for common tesseract code operations. These files can be used independently with stim.
+**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.
+
+## Generated Files
+
+### 1. Encoding Circuits
+
+- **`encoding_9a.stim`** - Encoding circuit for the |++0000⟩ state (Fig 9a)
+  - 23 qubits total (16 data + 7 ancillas)
+  - Prepares the tesseract code in the |++0000⟩ logical state
+
+- **`encoding_9b.stim`** - Encoding circuit for the |+0+0+0⟩ state (Fig 9b) 
+  - 18 qubits total (16 data + 2 ancillas)
+  - Prepares the tesseract code in the |+0+0+0⟩ logical state
+
+### 2. Error Correction
+
+- **`error_correction_round.stim`** - Single round of error correction
+  - 18 qubits total (16 data + 2 ancillas)
+  - Measures stabilizers for both rows and columns
+  - Includes flagged syndrome extraction
+
+### 3. Decoding
+
+- **`decoding.stim`** - Final measurement and decoding by diving to two [[8,3,2]] color codes
+  - 18 qubits total (16 data + 2 ancillas)
+  - Splits the tesseract code into two [[8,3,2]] color codes
+  - Measures top half in X basis, bottom half in Z basis
+
+### 4. Complete Experiments
+
+- **`complete_experiment_9a.stim`** - Full experiment with 9a encoding
+  - Encoding (9a) → 3 rounds of error correction → decoding
+  - 23 qubits total
+
+- **`complete_experiment_9b.stim`** - Full experiment with 9b encoding  
+  - Encoding (9b) → 3 rounds of error correction → decoding
+  - 18 qubits total
+
+## Qubit Layout
+
+All circuits use a consistent qubit layout:
+
+```
+Data qubits (0-15) arranged in 4×4 grid:
+Row 1: 0  1  2  3   (y=0, x=0-3)
+Row 2: 4  5  6  7   (y=1, x=0-3)  
+Row 3: 8  9  10 11  (y=2, x=0-3)
+Row 4: 12 13 14 15  (y=3, x=0-3)
+
+Ancilla qubits: 16, 17, ... (at x=5, y=0,1,2,...)
+```
+
+## Usage Examples
+
+### Using with stim directly
+
+```bash
+# Simulate the complete 9b experiment with 1000 shots
+stim sample --shots 1000 --in complete_experiment_9a.stim
+```
+
+### Using in Python
+
+```python
+import stim
+
+# Load a circuit
+circuit = stim.Circuit.from_file("encoding_9a.stim")
+
+# Run simulation
+sampler = circuit.compile_sampler()
+samples = sampler.sample(shots=1000)
+
+# Get detector error model
+dem = circuit.detector_error_model()
+```
+
+### Combining circuits
+
+```python
+import stim
+
+# Load individual components
+encoding = stim.Circuit.from_file("encoding_9a.stim")
+ec_round = stim.Circuit.from_file("error_correction_round.stim")
+decoding = stim.Circuit.from_file("decoding.stim")
+
+# Combine into custom experiment
+custom_circuit = stim.Circuit()
+custom_circuit += encoding
+
+# Add noise channel
+custom_circuit.append("DEPOLARIZE1", range(16), 0.001)
+
+# Add multiple EC rounds
+for _ in range(5):  # 5 rounds instead of 3
+    custom_circuit += ec_round
+
+custom_circuit += decoding
+```
+
+## Generation
+
+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.
+
+To regenerate the files:
+
+```bash
+python stim_circuits/generate_stim_files.py
+```
+
+## Related Papers
+
+- "Demonstration of quantum computation and error correction with a tesseract code" - http://arxiv.org/abs/2409.04628
+- "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

@@ -0,0 +1,172 @@
+# Complete experiment: encoding 9a -> 3 EC rounds -> decoding
+# Generated from tesseract-code-stim project
+# Circuit has 23 qubits total
+# 
+# Qubit layout:
+# - Qubits 0-15: Data qubits arranged in 4x4 grid
+# - Qubits 16+: Ancilla qubits for measurements
+#
+# Coordinate system:
+# - Qubits 0-3: row 1 (y=0, x=0-3)
+# - Qubits 4-7: row 2 (y=1, x=0-3) 
+# - Qubits 8-11: row 3 (y=2, x=0-3)
+# - Qubits 12-15: row 4 (y=3, x=0-3)
+#
+
+QUBIT_COORDS(0, 0) 0
+QUBIT_COORDS(1, 0) 1
+QUBIT_COORDS(2, 0) 2
+QUBIT_COORDS(3, 0) 3
+QUBIT_COORDS(0, 1) 4
+QUBIT_COORDS(1, 1) 5
+QUBIT_COORDS(2, 1) 6
+QUBIT_COORDS(3, 1) 7
+QUBIT_COORDS(0, 2) 8
+QUBIT_COORDS(1, 2) 9
+QUBIT_COORDS(2, 2) 10
+QUBIT_COORDS(3, 2) 11
+QUBIT_COORDS(0, 3) 12
+QUBIT_COORDS(1, 3) 13
+QUBIT_COORDS(2, 3) 14
+QUBIT_COORDS(3, 3) 15
+QUBIT_COORDS(5, 0) 16
+QUBIT_COORDS(5, 1) 17
+QUBIT_COORDS(5, 2) 18
+QUBIT_COORDS(5, 3) 19
+QUBIT_COORDS(5, 4) 20
+QUBIT_COORDS(5, 5) 21
+QUBIT_COORDS(5, 6) 22
+TICK                    # Start encoding based on Fig. 9a
+H 0 1 2 3 4 8 12
+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
+R 18 19
+H 19
+CX 19 18 19 0 19 1 19 2 19 3 19 18
+TICK                        # Start error correction round 1
+R 16 17                     # Start measure row 1
+H 16
+CX 0 17 16 1 1 17 16 0 2 17 16 3 3 17 16 2
+H 16
+M 16 17
+R 16 17                     # Start measure row 2
+H 16
+CX 4 17 16 5 5 17 16 4 6 17 16 7 7 17 16 6
+H 16
+M 16 17
+R 16 17                     # Start measure row 3
+H 16
+CX 8 17 16 9 9 17 16 8 10 17 16 11 11 17 16 10
+H 16
+M 16 17
+R 16 17                     # Start measure row 4
+H 16
+CX 12 17 16 13 13 17 16 12 14 17 16 15 15 17 16 14
+H 16
+M 16 17
+R 16 17                     # Start measure column 1
+H 16
+CX 0 17 16 4 4 17 16 0 8 17 16 12 12 17 16 8
+H 16
+M 16 17
+R 16 17                     # Start measure column 2
+H 16
+CX 1 17 16 5 5 17 16 1 9 17 16 13 13 17 16 9
+H 16
+M 16 17
+R 16 17                     # Start measure column 3
+H 16
+CX 2 17 16 6 6 17 16 2 10 17 16 14 14 17 16 10
+H 16
+M 16 17
+R 16 17                     # Start measure column 4
+H 16
+CX 3 17 16 7 7 17 16 3 11 17 16 15 15 17 16 11
+H 16
+M 16 17
+TICK                        # Start error correction round 2
+R 16 17                     # Start measure row 1
+H 16
+CX 0 17 16 1 1 17 16 0 2 17 16 3 3 17 16 2
+H 16
+M 16 17
+R 16 17                     # Start measure row 2
+H 16
+CX 4 17 16 5 5 17 16 4 6 17 16 7 7 17 16 6
+H 16
+M 16 17
+R 16 17                     # Start measure row 3
+H 16
+CX 8 17 16 9 9 17 16 8 10 17 16 11 11 17 16 10
+H 16
+M 16 17
+R 16 17                     # Start measure row 4
+H 16
+CX 12 17 16 13 13 17 16 12 14 17 16 15 15 17 16 14
+H 16
+M 16 17
+R 16 17                     # Start measure column 1
+H 16
+CX 0 17 16 4 4 17 16 0 8 17 16 12 12 17 16 8
+H 16
+M 16 17
+R 16 17                     # Start measure column 2
+H 16
+CX 1 17 16 5 5 17 16 1 9 17 16 13 13 17 16 9
+H 16
+M 16 17
+R 16 17                     # Start measure column 3
+H 16
+CX 2 17 16 6 6 17 16 2 10 17 16 14 14 17 16 10
+H 16
+M 16 17
+R 16 17                     # Start measure column 4
+H 16
+CX 3 17 16 7 7 17 16 3 11 17 16 15 15 17 16 11
+H 16
+M 16 17
+TICK                        # Start error correction round 3
+R 16 17                     # Start measure row 1
+H 16
+CX 0 17 16 1 1 17 16 0 2 17 16 3 3 17 16 2
+H 16
+M 16 17
+R 16 17                     # Start measure row 2
+H 16
+CX 4 17 16 5 5 17 16 4 6 17 16 7 7 17 16 6
+H 16
+M 16 17
+R 16 17                     # Start measure row 3
+H 16
+CX 8 17 16 9 9 17 16 8 10 17 16 11 11 17 16 10
+H 16
+M 16 17
+R 16 17                     # Start measure row 4
+H 16
+CX 12 17 16 13 13 17 16 12 14 17 16 15 15 17 16 14
+H 16
+M 16 17
+R 16 17                     # Start measure column 1
+H 16
+CX 0 17 16 4 4 17 16 0 8 17 16 12 12 17 16 8
+H 16
+M 16 17
+R 16 17                     # Start measure column 2
+H 16
+CX 1 17 16 5 5 17 16 1 9 17 16 13 13 17 16 9
+H 16
+M 16 17
+R 16 17                     # Start measure column 3
+H 16
+CX 2 17 16 6 6 17 16 2 10 17 16 14 14 17 16 10
+H 16
+M 16 17
+R 16 17                     # Start measure column 4
+H 16
+CX 3 17 16 7 7 17 16 3 11 17 16 15 15 17 16 11
+H 16
+M 16 17
+TICK
+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
+H 0 1 2 3 4 5 6 7                           # Change top half's basis so its measured in the X basis
+M 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15     # Measure all physical qubits
+TICK