Pre-release
This release is a pre-release and may not be stable for production use.
Tesseract Decoder
A Search-Based Decoder for Quantum Error Correction.
Installation – Usage – Python Interface – Paper – Help – Citation – Contact
Tesseract is a Most Likely Error decoder designed for Low Density Parity Check (LDPC) quantum error-correcting codes. It applies pruning heuristics and manifold orientation techniques during a search over the error subsets to identify the most likely error configuration consistent with the observed syndrome. Tesseract achieves significant speed improvements over traditional integer programming-based decoders while maintaining comparable accuracy at moderate physical error rates.
We tested the Tesseract decoder for:
- Surface codes
- Color codes
- Bivariate-bicycle codes
- Transversal CNOT protocols for surface codes
Features
- A* search: deploys A* search while running a Dijkstra algorithm with early stop for high performance.
- Stim and DEM Support: processes Stim circuit files and Detector Error Model (DEM) files with arbitrary error models. Zero-probability error instructions are automatically removed when a DEM is loaded.
- Parallel Decoding: uses multithreading to accelerate the decoding process, making it suitable for large-scale simulations.
- Efficient Beam Search: implements a beam search
algorithm to minimize decoding cost and enhance efficiency.
Sampling and Shot Range Processing: supports sampling shots from circuits. When a detection
error model is provided without an accompanying circuit, Tesseract requires detection events from
files using
--in. The decoder can also process specific shot ranges for flexible experiment setups. - Detailed Statistics: provides comprehensive statistics output, including shot counts, error counts, and processing times.
- Heuristics: includes flexible heuristic options:
--beam,--det-penalty,--beam-climbing,--no-revisit-dets,--at-most-two-errors-per-detector, and--pqlimitto improve performance while maintaining a low logical error rate. To learn more about these options, use./bazel-bin/src/tesseract --help - Visualization tool: open the viz directory in your browser to view decoding results. See viz/README.md for instructions on generating the visualization JSON.
Installation
Tesseract relies on the following external libraries:
- argparse: For command-line argument parsing.
- nlohmann/json: For JSON handling (used for statistics output).
- Stim: For quantum circuit simulation and error model handling.
Build Instructions
Tesseract uses Bazel as its build system. To build the decoder:
bazel build src:all
Running Tests
Unit tests are executed with Bazel. Run the quick test suite using:
bazel test //src:all
By default the tests use reduced parameters and finish in under 30 seconds. To run a more exhaustive suite with additional shots and larger distances, set:
TESSERACT_LONG_TESTS=1 bazel test //src:all
Usage
The file tesseract_main.cc provides the main entry point for Tesseract Decoder. It can decode
error events from Stim circuits, DEM files, and pre-existing detection event files.
Basic Usage:
./tesseract --circuit CIRCUIT_FILE.stim --sample-num-shots N --print-stats
To decode pre-generated detection events, provide the input file using
--in SHOTS_FILE --in-format FORMAT.
Example with Advanced Options:
./tesseract \
--pqlimit 1000000 \
--at-most-two-errors-per-detector \
--det-order-seed 232852747 \
--circuit circuit_file.stim \
--sample-seed 232856747 \
--sample-num-shots 10000 \
--threads 32 \
--print-stats \
--beam 23 \
--num-det-orders 1 \
--shot-range-begin 582 \
--shot-range-end 583
Example Usage
Sampling Shots from a Circuit:
./tesseract --circuit surface_code.stim --sample-num-shots 1000 --out predictions.01 --out-format 01
Using a Detection Event File:
./tesseract --in events.01 --in-format 01 --dem surface_code.dem --out decoded.txt
Using a Detection Event File and Observable Flips:
./tesseract --in events.01 --in-format 01 --obs_in obs.01 --obs-in-format 01 --dem surface_code.dem --out decoded.txt
Tesseract supports reading and writing from all of Stim's standard output formats.
Performance Optimization
Here are some tips for improving performance:
- Parallelism over shots: increase
--threadsto leverage multicore processors for faster decoding. - Beam Search: use
--beamto control the trade-off between accuracy and speed. Smaller beam sizes result in faster decoding but potentially lower accuracy. - Beam Climbing: enable
--beam-climbingfor enhanced cost-based decoding. - At most two errors per detector: enable
--at-most-two-errors-per-detectorto improve performance. - Priority Queue limit: use
--pqlimitto limit the size of the priority queue.
Output Formats
- Observable flips output: predictions of logical errors.
- DEM usage frequency output: if
--dem-outis specified, outputs estimated error frequencies. - Statistics output: includes number of shots, errors, low confidence shots, and processing time.
Python Interface
Full Python wrapper documentation
This repository contains the C++ implementation of the Tesseract quantum error correction decoder, along with a Python wrapper. The Python wrapper/interface exposes the decoding algorithms and helper utilities, allowing Python users to leverage this high-performance decoding algorithm.
The following example demonstrates how to create and use the Tesseract decoder using the Python interface.
from tesseract_decoder import tesseract
import stim
import numpy as np
# 1. Define a detector error model (DEM)
dem = stim.DetectorErrorModel("""
error(0.1) D0 D1 L0
error(0.2) D1 D2 L1
detector(0, 0, 0) D0
detector(1, 0, 0) D1
detector(2, 0, 0) D2
""")
# 2. Create the decoder configuration
config = tesseract.TesseractConfig(dem=dem, det_beam=50)
# 3. Create a decoder instance
decoder = config.compile_decoder()
# 4. Simulate detector outcomes
syndrome = np.array([0, 1, 1], dtype=bool)
# 5a. Decode to observables
flipped_observables = decoder.decode(syndrome)
print(f"Flipped observables: {flipped_observables}")
# 5b. Alternatively, decode to errors
decoder.decode_to_errors(syndrome)
predicted_errors = decoder.predicted_errors_buffer
# Indices of predicted errors
print(f"Predicted errors indices: {predicted_errors}")
# Print properties of predicted errors
for i in predicted_errors:
print(f" {i}: {decoder.errors[i]}")
Help
- Do you have a feature request or want to report a bug? Open an issue on GitHub to report it!
- Do you have a code contribution? Read our contribution guidelines, then open a pull request!
We are committed to providing a friendly, safe, and welcoming environment for all. Please read and respect our Code of Conduct.
Citation
When publishing articles or otherwise writing about Tesseract Decoder, please cite the following:
@misc{beni2025tesseractdecoder,
title={Tesseract: A Search-Based Decoder for Quantum Error Correction},
author = {Aghababaie Beni, Laleh and Higgott, Oscar and Shutty, Noah},
year={2025},
eprint={2503.10988},
archivePrefix={arXiv},
primaryClass={quant-ph},
doi = {10.48550/arXiv.2503.10988},
url={https://arxiv.org/abs/2503.10988},
}
Contact
For any questions or concerns not addressed here, please email tesseract-decoder-dev@google.com.
Disclaimer
Tesseract Decoder is not an officially supported Google product. This project is not eligible for the Google Open Source Software Vulnerability Rewards Program.
Copyright 2025 Google LLC.
1 maintainer
Metadata
1 maintainer
Release files for tesseract-decoder 0.1.1.dev20250905183630
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 53.4 MB
Release files / tesseract_decoder-0.1.1.dev20250905183630-py313-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py313-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.5 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.39+ x86-64 Python 3.13 |
|
SHA-256 checksum How to use checksums |
008906a8eccfc5fc8ff8805a7d894c392cfb50b26189f227c499c7f65efd2025
|
|
BLAKE2b-256 checksum How to use checksums |
1fc27d8e63028798f563f72bd3378598c77a72a2c71b8fbbef5bf18f1ec01206
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py313-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py313-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.35+ x86-64 Python 3.13 |
|
SHA-256 checksum How to use checksums |
5b865568d4c3a46eab448de102bfd3c055215a0e231ac98b86442f4a4a2cf44f
|
|
BLAKE2b-256 checksum How to use checksums |
6687d0360a132106846045c65f604f00c1e34553cf52f0b85094663a9353266c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py313-none-macosx_11_0_arm64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py313-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | Python 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
07a7aabf087862a2ec608dc3759bb287b7eaf32bfb1245271b1ee119b43b1ece
|
|
BLAKE2b-256 checksum How to use checksums |
360feb2c6cb2d3ca08c3ff0fd63627e50aa3dedcf9943f0aab2043c1bd169790
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py313-none-macosx_10_13_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py313-none-macosx_10_13_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | Python 3.13 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
4cd4b07121791fb062111898734c20f0d992da5af26fe65cf1618504ff5dc6b0
|
|
BLAKE2b-256 checksum How to use checksums |
6c3642590ccab5ef8d8e75bd8af77edd1c4e244fab4b8655b332a488122af9c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py312-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py312-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.5 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.39+ x86-64 Python 3.12 |
|
SHA-256 checksum How to use checksums |
17e1ccf6f4bd94833488e246c9291abe67b5203686b1c191f5af11aa2c6adfb5
|
|
BLAKE2b-256 checksum How to use checksums |
f973d7ae8138fc7f6e752c74ade806440b05ca62a4e2aaca2a69a991d2635662
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py312-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py312-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.35+ x86-64 Python 3.12 |
|
SHA-256 checksum How to use checksums |
7705cba0f8cefe56485f37dff3c82d9ef5fef2e5ad0422adef0879c870f93118
|
|
BLAKE2b-256 checksum How to use checksums |
eccbdd793daa7a609ecb59ac2e8faebe25d186d58b0eb11cfb9b8cbf45c8e972
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py312-none-macosx_11_0_arm64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py312-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | Python 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
7b024fb73e3e5b969c212dd4bd0bfabf475dc62a7d2ce57b39501b0e935284f8
|
|
BLAKE2b-256 checksum How to use checksums |
6d8da516403ecf50b839046d543ff94705d0060ed0a5acaf2347ee550535c0d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py312-none-macosx_10_13_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py312-none-macosx_10_13_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | Python 3.12 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
0947596efd98d260b16f4f65442af494abe171dc63c2123bc32ef8b636594085
|
|
BLAKE2b-256 checksum How to use checksums |
0960485c4ccd233f200606c6f8e02d43d99b36b914eea0447acf24b99268094a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py311-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py311-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.5 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.39+ x86-64 Python 3.11 |
|
SHA-256 checksum How to use checksums |
d84469fff9799cdb8486c53735777f9dbc2b3bc61b200b6c40285294917033dd
|
|
BLAKE2b-256 checksum How to use checksums |
8a835f8cabb50b88f10037a9df0ec4b3c9ef49516ea35773ff0053a0c738c52d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py311-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py311-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.35+ x86-64 Python 3.11 |
|
SHA-256 checksum How to use checksums |
cd95eea9e2dfb935c8bf5a15efc3de1aee603e92707f11dbc543aed43f2aaba5
|
|
BLAKE2b-256 checksum How to use checksums |
5796ac6c16da5bbcd2f963ac01c9c96ef790d7675e5824b28e9767b48dfd3893
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py311-none-macosx_11_0_arm64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py311-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.2 MB |
| Tags | Python 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
99c8567ed4567133027cd5b35820db535b5026a5bfba212eaf42b093ac775976
|
|
BLAKE2b-256 checksum How to use checksums |
d287b9595a0cf38ee7098ac7f0c87af7afec7960f08cbbf52b9dc5ed9ac7a7d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py311-none-macosx_10_13_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py311-none-macosx_10_13_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | Python 3.11 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
181d8cff706e3b1315af39c976731f480b3753528fefbda1e7556c9b6f246e68
|
|
BLAKE2b-256 checksum How to use checksums |
bb4df24c4f5ccf4d251f93fe31db9af1058e5af673953f90a9f559d7cf8368ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py310-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py310-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.5 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.39+ x86-64 Python 3.10 |
|
SHA-256 checksum How to use checksums |
8358e9943cd65bc814864e8fc197312bd1ddb168ff13da2cbf5f51e0b78c2f24
|
|
BLAKE2b-256 checksum How to use checksums |
da997564214d6c3a5a4e5ac44ec1c6754231303d95603d951c9affc69e3a6f25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py310-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py310-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.35+ x86-64 Python 3.10 |
|
SHA-256 checksum How to use checksums |
037ecb214255d04ec6dd8976a48207125e365507616b37ebc72cd88eb8c3b6e5
|
|
BLAKE2b-256 checksum How to use checksums |
7fdf58a300d936d7810d71a5009498a334a8aa6a241a66db461990ee7333c4bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py310-none-macosx_11_0_arm64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py310-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.2 MB |
| Tags | Python 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a5dc032555dac4805f77dfd683efb2fd3e5609140b931469d4f90033900bb9af
|
|
BLAKE2b-256 checksum How to use checksums |
7038c16b25592355102d32fbf9f65025751ea873badd5e5b58bc01e1398cd562
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
Release files / tesseract_decoder-0.1.1.dev20250905183630-py310-none-macosx_10_13_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250905183630-py310-none-macosx_10_13_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | Python 3.10 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
005d2e188124a6a4d4fb5ad3be725e1295f34a598dddf48af332354440642aa6
|
|
BLAKE2b-256 checksum How to use checksums |
166ff3adc52ae5bad35686ebef416d6a3f364126838add6c6533255118c5f36a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
