# co-swiper

**Repository Path**: xusun000/co-swiper

## Basic Information

- **Project Name**: co-swiper
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-05
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QEC Pipeline

A modular, extensible pipeline for quantum error correction (QEC) simulation and decoding analysis.

This project provides a complete workflow from **circuit generation** (via [Stim](https://github.com/quantumlib/Stim)) to **syndrome decoding** (via [PyMatching](https://github.com/oscarhiggott/PyMatching)) and **threshold estimation**.

---

## Features

- **Multiple QEC Codes**: Surface code, Repetition code, Toric code (planned), Color code (planned), Custom circuits
- **Unified Interface**: Single `QECPipeline` class orchestrates the entire workflow
- **High Performance**: Leverages Stim for fast simulation and PyMatching v2 for ultra-fast MWPM decoding
- **Batch Decoding**: `decode_batch()` for efficient processing of many shots
- **Threshold Analysis**: Built-in tools for threshold estimation and visualization
- **Extensible Design**: Easy to add new codes, decoders, or analyzers

---

## Installation

```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

Dependencies:
- `stim` >= 1.14.0
- `pymatching` >= 2.1.0
- `numpy` >= 1.24.0
- `matplotlib` >= 3.7.0
- `sinter` >= 1.14.0 (optional)

---

## Quick Start

```python
from qec_pipeline import QECPipeline, CircuitConfig

# 1. Configure the circuit
config = CircuitConfig(
    code_type="surface_code",
    distance=5,
    rounds=5,
    error_prob=0.005,
    basis="memory_x",
    rotated=True,
)

# 2. Build and run the pipeline
pipeline = QECPipeline(config)
result = pipeline.run(num_shots=10000)

# 3. Analyze results
print(f"Logical Error Rate: {result.logical_error_rate:.4f} ± {result.std_error:.4f}")
```

---

## Project Structure

```
.
├── qec_pipeline/           # Main package
│   ├── __init__.py
│   ├── circuits.py         # Circuit generation (Stim wrappers)
│   ├── simulator.py        # Stim simulator wrapper
│   ├── decoder.py          # PyMatching MWPM decoder
│   ├── analyzer.py         # Threshold analysis & plotting
│   ├── pipeline.py         # Main QECPipeline orchestrator
│   └── utils.py            # Utility functions
├── examples/               # Example scripts
│   ├── quickstart.py       # Minimal example
│   ├── surface_code_threshold.py  # Threshold estimation
│   ├── repetition_code_demo.py    # Repetition code demo
│   └── compare_codes.py           # Multi-code comparison
├── outputs/                # Generated plots and data
├── requirements.txt
└── README.md
```

---

## Examples

### 1. Quick Start
```bash
python examples/quickstart.py
```

### 2. Threshold Estimation (Surface Code)
```bash
python examples/surface_code_threshold.py
```

This script:
- Simulates rotated surface codes with distances [3, 5, 7]
- Scans physical error rates from 0.001 to 0.02
- Decodes with PyMatching
- Plots the threshold curve
- Saves results to `outputs/surface_code_threshold.json`

### 3. Code Comparison
```bash
python examples/compare_codes.py
```

Compares surface code (X/Z basis) vs repetition code at the same physical error rate.

### 4. Custom Circuit
```python
import stim
from qec_pipeline import QECPipeline, CircuitConfig

# Build your own Stim circuit
custom_circuit = stim.Circuit("""
    R 0 1 2
    H 0
    CNOT 0 1
    CNOT 0 2
    H 0
    M 0 1 2
""")

config = CircuitConfig(
    code_type="custom",
    distance=3,
    rounds=1,
    error_prob=0.01,
    custom_circuit=custom_circuit,
)

pipeline = QECPipeline(config)
result = pipeline.run(num_shots=1000)
```

---

## Supported Codes

| Code Type | Status | Parameters |
|-----------|--------|------------|
| `surface_code` | ✅ Ready | `distance`, `rounds`, `basis`, `rotated` |
| `repetition_code` | ✅ Ready | `distance`, `rounds` |
| `toric_code` | 🚧 Planned | — |
| `color_code` | 🚧 Planned | — |
| `custom` | ✅ Ready | `custom_circuit` (stim.Circuit) |

---

## API Reference

### `QECPipeline`

Main orchestrator class.

```python
# Single simulation
pipeline = QECPipeline(config)
result = pipeline.run(num_shots=10000)

# Threshold sweep (class method)
threshold_result = QECPipeline.run_threshold_sweep(
    code_type="surface_code",
    distances=[3, 5, 7],
    error_probs=np.linspace(0.001, 0.02, 10),
    num_shots=10000,
)

# Distance scaling (class method)
scaling_results = QECPipeline.run_distance_scaling(
    code_type="surface_code",
    distances=[3, 5, 7, 9],
    error_prob=0.005,
    num_shots=10000,
)
```

### `CircuitConfig`

Configuration dataclass for circuit generation.

```python
CircuitConfig(
    code_type="surface_code",      # Code type
    distance=5,                     # Code distance
    rounds=5,                       # Syndrome rounds
    error_prob=0.001,              # Physical error rate
    basis="memory_x",              # X or Z basis (surface code)
    rotated=True,                  # Rotated vs unrotated
)
```

### `ThresholdAnalyzer`

Analysis and visualization tools.

```python
analyzer = ThresholdAnalyzer()
analyzer.add_results(results)

# Plot threshold sweep
analyzer.plot_threshold_sweep(
    threshold_result,
    save_path="outputs/threshold.png",
    yscale="log",
)

# Plot distance scaling
analyzer.plot_distance_scaling(
    error_prob=0.005,
    save_path="outputs/scaling.png",
)

# Generate text report
report = analyzer.generate_report([threshold_result])
print(report)
```

---

## Performance Notes

- **Circuit Generation**: Fast, typically < 10ms for distance < 20
- **Simulation**: Stim compiles circuits to optimized C++ code
- **Decoding**: PyMatching v2 is 100-1000x faster than v0.7
- **Batch Decoding**: Use `decode_batch()` instead of Python loops for >1000 shots
- **Bit Packing**: Enable `bit_packed=True` for large shot counts to reduce memory

Example timings (M1 Mac, single core):
- Surface code d=5, rounds=5: ~0.03s for 10,000 shots
- Surface code d=17: ~1μs per round of syndrome extraction

---

## Extending the Pipeline

### Adding a New Code

1. Add the code type to `SUPPORTED_CODES` in `circuits.py`
2. Implement a `_your_code(cls, config)` classmethod in `CircuitGenerator`
3. Return a valid `stim.Circuit` with detectors and observables defined

### Adding a New Decoder

1. Create a new class in `decoder.py` (e.g., `UnionFindDecoder`)
2. Implement `decode()` and `decode_batch()` methods
3. Update `QECPipeline` to use the new decoder

### Adding a New Analyzer

1. Create new methods in `analyzer.py` or subclass `ThresholdAnalyzer`
2. Add plotting methods using matplotlib

---

## Citation

If you use this pipeline in your research, please cite the underlying libraries:

- **Stim**: Gidney, C. (2021). *Stim: a fast stabilizer circuit simulator*. Quantum 5, 497.
- **PyMatching v2**: Higgott, O. & Gidney, C. (2022). *PyMatching v2*. GitHub repository.

---

## License

MIT License (or specify your preferred license)

---

## Acknowledgements

This pipeline builds on the excellent work of:
- Craig Gidney (Stim, PyMatching v2)
- Oscar Higgott (PyMatching)
- The quantum error correction community