https://github.com/quantumlib/chromobius
Open-source implementation of a "mobius decoder" for colors codes used in quantum error correction (QEC)
https://github.com/quantumlib/chromobius
algorithms color-code google-quantum python qec-codes quantum quantum-computing quantum-error-correction
Last synced: 3 months ago
JSON representation
Open-source implementation of a "mobius decoder" for colors codes used in quantum error correction (QEC)
- Host: GitHub
- URL: https://github.com/quantumlib/chromobius
- Owner: quantumlib
- License: apache-2.0
- Created: 2023-10-15T07:38:43.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-26T22:04:46.000Z (6 months ago)
- Last Synced: 2025-06-04T07:52:23.120Z (4 months ago)
- Topics: algorithms, color-code, google-quantum, python, qec-codes, quantum, quantum-computing, quantum-error-correction
- Language: Python
- Homepage:
- Size: 8.64 MB
- Stars: 16
- Watchers: 2
- Forks: 5
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Chromobius: color code decoder
Chromobius is an implementation of a ["mobius decoder"](https://arxiv.org/abs/2108.11395), which approximates the color code decoding problem as a minimum weight matching problem.
Chromobius uses [PyMatching](https://github.com/oscarhiggott/PyMatching/) to solve the minimum weight matching problem.
See ((((the paper "New circuits and an open source decoder for the color code")))) for more details on how Chromobius works.
## How to use Chromobius
See the [**getting started notebook**](doc/getting_started.ipynb).
Also see the [python api reference](doc/chromobius_api_reference.md).
Programmers who want to edit and build Chromobius can check the [developer documentation](doc/developers.md).
## Example Snippets
### Decoding a shot with Chromobius
From python:
```python
import stim
import chromobius
import numpy as np
def count_mistakes(circuit: stim.Circuit, shots: int) -> int:
# Sample the circuit.
dets, actual_obs_flips = circuit.compile_detector_sampler().sample(
shots=shots,
separate_observables=True,
bit_packed=True,
)
# Decode with Chromobius.
decoder = chromobius.compile_decoder_for_dem(circuit.detector_error_model())
predicted_obs_flips = decoder.predict_obs_flips_from_dets_bit_packed(dets)
# Count mistakes.
return np.count_nonzero(np.any(predicted_obs_flips != actual_obs_flips, axis=1))
```
From the command line:
```bash
# Sample shots of detectors and observable flips.
stim detect \
--shots 100000 \
--in "example_circuit.stim" \
--out "dets.b8" \
--out_format "b8" \
--obs_out "obs_actual.txt" \
--obs_out_format "01"
# Extract a detector error model used to configure Chromobius.
stim analyze_errors \
--in "example_circuit.stim" \
--fold_loops \
--out "dem.dem"
# Decode the shots.
chromobius predict \
--dem "dem.dem" \
--in "dets.b8" \
--in_format "b8" \
--out "obs_predicted.txt" \
--out_format "01"
# Count the number of shots with a prediction mistake.
paste obs_actual.txt obs_predicted.txt \
| grep -Pv "^([01]*)\\s*\\1$" \
| wc -l
```
From python using sinter:
```python
import sinter
import chromobius
import os
tasks: list[sinter.Task] = ...
stats: list[sinter.TaskStats] = sinter.collect(
decoders=["chromobius"],
custom_decoders=chromobius.sinter_decoders(),
tasks=tasks,
num_workers=os.cpu_count(),
max_shots=100_000,
max_errors=100,
)
```
From the command line using sinter:
```bash
sinter collect \
--circuits "example_circuit.stim" \
--decoders chromobius \
--custom_decoders_module_function "chromobius:sinter_decoders" \
--max_shots 100_000 \
--max_errors 100
--processes auto \
--save_resume_filepath "stats.csv" \
```