decoder-bench

KO | EN

gitlite — search

#hacktoberfest #react #ai #typescript #golang #machine-learning #rust #linux #nodejs #windows #vue #pytorch #security #open-source

(★ 13)

Benchmarking decoders for QEC

decoder-bench 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# decoder-bench

[Paper](https://ieeexplore.ieee.org/abstract/document/11242095) &ndash;
[Zenodo](https://doi.org/10.5281/zenodo.16914504)

A benchmarking suite for quantum error correction (QEC) decoders, supporting multiple QEC codes, noise models, and measurement bases. `decoder-bench` generates datasets (in `h5` format) containing check matrices, syndromes, and observables, which can then be used to evaluate any decoder. These datasets can be generated for different noise models (code capacity/phenomenological/circuit-level) for memory experiments and only circuit-level noise for (surface code) Lattice Surgery experiments. Some premade datasets are publicly available on Zenodo (see [Premade datasets](#premade-datasets)).

We also include a Sinter-like sampler that can be used for running evaluations for different decoders using the datasets generated by `decoder-bench`. See [Using the datasets](#using-the-datasets).

Future work for this benchmarking suite is to add support for generating decoder traces for more use cases such as transversal operations and color code Lattice Surgery.

## Table of Contents

- [Features](#features)
- [Premade datasets](#premade-datasets)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Supported Codes](#supported-codes)
- [Noise Models](#noise-models)
- [Examples](#examples)
- [Using the datasets](#using-the-datasets)
- [License](#license)

## Features

- **Multiple Quantum Error Correcting Codes**: Memory experiments (Surface codes, QLDPC codes, Color codes), and Lattice Surgery circuits (only Surface codes, logical measurement operations)
- **Various Noise Models**: Code capacity, phenomenological, and circuit-level noise
- **Flexible Measurement Bases**: Support for both X and Z basis measurements  
- **High-Performance Simulation**: Built on top of [Stim](https://github.com/quantumlib/Stim)
- **Comprehensive Dataset Generation**: Generate large-scale syndrome datasets for decoder training and benchmarking
- **Configurable Parameters**: Adjustable code distances, error rates, and simulation parameters
- **Export Formats**: HDF5 output format for easy data analysis and sharing

## Premade datasets

Premade datasets generated using `decoder-bench` for different QEC codes and use-cases can be downloaded from [Zenodo](https://doi.org/10.5281/zenodo.16914504).

## Installation

### Option 1: Install as a Package (Recommended)

```bash
pip install git+https://github.com/satvikmaurya/decoder-bench.git
```

### Option 2: Manual Installation

```bash
git clone https://github.com/satvikmaurya/decoder-bench.git
cd decoder-bench
pip install .
```

### Prerequisites

- Python 3.10 or higher
- Required packages are automatically installed with pip install

## Quick Start

Generate a surface code dataset with circuit-level noise:

```bash
# Using the installed package command
decoder-bench-generate --code=surface --basis=z --noise=circuit -d 9 -p 0.001 --records=10000

# Or run the script directly
python decoder_bench/generator.py --code=surface --basis=z --noise=circuit -d 9 -p 0.001 --records=10000
```

## Usage

### Command Line Interface

The main interface is through the `generator.py` script:

```bash
python decoder_bench/generator.py [OPTIONS]
```

#### Required Arguments

- `--code`: Type of quantum code
  - `surface` - Surface codes with rotated layout
  - `qldpc` - Quantum Low-Density Parity-Check codes  
  - `color` - Color codes
  - `ls` - Lattice Surgery circuits
- `--basis`: Measurement basis (`x` or `z`)
- `--noise`: Noise model (`code_capacity`, `phenom`, or `circuit`)
- `--distance, -d`: Code distance (integer)
- `--depolarization, -p`: Error probability (float)

#### Optional Arguments

- `--iterations`: Maximum iterations (default: 100)
- `--records`: Number of syndrome records to generate (default: 50,000,000)
- `--output-dir`: Output directory for datasets (default: ../datasets)

### Python API

You can also use decoder-bench as a Python package:

```python
import decoder_bench
from decoder_bench.generator import gen_surface_circuit
from decoder_bench.dataset_gen import DatasetGen

# Generate surface code circuit
gen_surface_circuit((distance=7, error_rate=0.001, basis='z'))

# Or use the classes directly
import stim
from decoder_bench.dataset_gen import DatasetGen
from decoder_bench.common.noise import NoiseModel

circuit = stim.Circuit.generated('surface_code:rotated_memory_z', 
                                 distance=7, rounds=7)
circuit = NoiseModel.SI1000(0.001).noisy_circuit(circuit)
generator = DatasetGen(circuit, matchable=True, name='my_dataset')
generator.gen_syndromes(max_iterations=100, num_records=10000)
```

## Supported Codes

### Surface Codes

- **Rotated surface codes** with customizable distance and measurement basis
- Supports X and Z logical measurements
- Multiple noise models available

### QLDPC Codes

- **Bivariate Bicycle codes** with configurable parameters
- Code capacity and circuit-level noise models
- Support for both measurement bases

### Color Codes

- **Triangular lattice color codes**
- Automatic syndrome generation and error correction
- Built-in noise models

### Lattice Surgery

- Only surface codes
- **Multi-patch lattice surgery** simulations
- Variable gate latencies and error rates
- Fenced and runahead instruction scheduling policies
- Merge operations between logical qubits

## Noise Models

### Code Capacity

Perfect syndrome measurements with data qubit errors only.

### Phenomenological

Data qubit errors plus measurement errors, but no circuit-level details.

### Circuit-Level

Full circuit-level noise including:

- Gate errors (depolarization)
- Measurement errors  
- Idling errors with T1/T2 decoherence
- Variable gate latencies

## Examples

### Generate Surface Code Dataset

```bash
# Circuit-level noise, distance 7, 0.1% error rate
python decoder_bench/generator.py --code=surface --basis=z --noise=circuit -d 7 -p 0.001 --records=100000

# Code capacity noise, distance 9, 0.09% error rate  
python decoder_bench/generator.py --code=surface --basis=x --noise=code_capacity -d 9 -p 0.0009 --records=50000
```

### Generate QLDPC Dataset

```bash
# QLDPC with phenomenological noise
python decoder_bench/generator.py --code=qldpc --basis=z --noise=phenom -d 12 -p 0.005 --records=25000
```

### Generate Color Code Dataset

```bash
# Color code with circuit-level noise (basis ignored)
python decoder_bench/generator.py --code=color --basis=z --noise=circuit -d 7 -p 0.003 --records=75000
```

### Lattice Surgery Simulation

```bash
# Lattice surgery with Z-basis logical operations
python decoder_bench/generator.py --code=ls --basis=z --noise=circuit -d 5 -p 0.001 --records=10000
```

### Batch Generation

Generate multiple datasets with different parameters:

```bash
#!/bin/bash
for d in 5 7 9; do
    for p in 0.001 0.003 0.005; do
        python decoder_bench/generator.py --code=surface --basis=z --noise=circuit -d $d -p $p --records=10000
    done
done
```

## Output Format

Datasets are saved as HDF5 files with the following structure:

- **Syndromes**: Binary syndrome measurements
- **Metadata**: Code parameters, noise model, simulation settings
- **Observables**: Logical measurement outcomes

## Using the datasets

Not all decoders are fast, which is why samplers like [Sinter](https://pypi.org/project/sinter/) are necessary for sampling millions of shots to compute useful statistics. Since Sinter does not support reading from decoder traces containing syndromes, this repository has a custom Sinter-like [sampler](./decoder_bench/sampler.py) to read from a trace dumped by decoder-bench. Refer to [eval.py](./decoder_bench/eval.py) and [decoders.py](./decoder_bench/decoders.py) for running your own evaluations and using different decoders.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Citation

If you use decoder-bench in your research, please cite:

```bibtex
@inproceedings{Maurya2025decoderbench,
  title = {decoder-bench: Benchmarking Decoders for Quantum Error Correction},
  url = {http://dx.doi.org/10.1109/IISWC66894.2025.00032},
  DOI = {10.1109/iiswc66894.2025.00032},
  booktitle = {2025 IEEE International Symposium on Workload Characterization (IISWC)},
  publisher = {IEEE},
  author = {Maurya,  Satvik and Viszlai,  Joshua and Raveendran,  Nithin and Das,  Poulami and Tannu,  Swamit},
  year = {2025},
  month = oct,
  pages = {286–295}
}
```

## Credits

This tool uses code from the following repositories:

- [Stim](https://github.com/quantumlib/Stim)
- [SlidingWindowDecoder](https://github.com/gongaa/SlidingWindowDecoder)
- [honeycomb_threshold](https://github.com/Strilanc/honeycomb_threshold/tree/main/src)
- [BeliefMatching](https://github.com/oscarhiggott/BeliefMatching)

decoder-bench

decoder-bench 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

decoder-bench

decoder-bench 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README