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.
For installation:
pip install tesseract-decoder
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]}")
Good Starting Points for Tesseract Configurations:
The Tesseract paper recommends two setup for starting your exploration with tesseract:
(1) Long-beam setup:
tesseract_config = tesseract.TesseractConfig(
dem=dem,
pqlimit=1_000_000,
det_beam=20,
beam_climbing=True,
num_det_orders=21,
det_order=tesseract_decoder.utils.DetOrder.DetIndex,
no_revisit_dets=True,
)
(2) Short-beam setup:
tesseract_config = tesseract.TesseractConfig(
dem=dem,
pqlimit=200_000,
det_beam=15,
beam_climbing=True,
num_det_orders=16,
det_order=tesseract_decoder.utils.DetOrder.DetIndex,
no_revisit_dets=True,
)
For det_order, you can use two other options of DetIndex and DetCoordinate as well.
These values balance decoding speed and accuracy across the benchmarks reported in the paper and can be adjusted for specific use cases.
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.dev20250927194541
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.dev20250927194541-py313-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
1a1b6b65357c1c068dc029e3784104efc23362bc7ca91045fd4f5975c1403433
|
|
BLAKE2b-256 checksum How to use checksums |
d4b7404f49a4d4345f276094a513a6d1efda9eda82bb83fd54400b50e00e15c2
|
| 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.dev20250927194541-py313-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
fb53d5c5ca5c510fd660bfc758bcad549bc853972faebfb699c3acaf3ad32d53
|
|
BLAKE2b-256 checksum How to use checksums |
b1e36bd3c27aba6040f5ca08fa320cda489c91ddfd2bec26d438389b9aeab0b5
|
| 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.dev20250927194541-py313-none-macosx_11_0_arm64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
8740278ea1b586b4795ede109babe1ec310fd5852f1fd1a8083df2b163fe5ea9
|
|
BLAKE2b-256 checksum How to use checksums |
1523f046eb2137fcb9138c1117791045478fb7633e69b20b0c9ba5bdce726366
|
| 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.dev20250927194541-py313-none-macosx_10_13_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
55680d259c16c9760685320f198de3ddfd2c22ee6ca8e0074a3637e0f4086ae3
|
|
BLAKE2b-256 checksum How to use checksums |
a70e4b8b668a618464bd447c0551f3d083b90261406eff2b8e430758fbfb5bbc
|
| 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.dev20250927194541-py312-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
41e067f7842c1bab13f31cdd066dfd56fa1758f04984908571b928af88bfb980
|
|
BLAKE2b-256 checksum How to use checksums |
1016ad0a75dacfff650edd42dec6661814a66a082680a7e4ddd84d727d3ab7d5
|
| 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.dev20250927194541-py312-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
c8ab6e59c7938580947f597773c1e80f9445274cb70e56dcde45127da63a12cd
|
|
BLAKE2b-256 checksum How to use checksums |
3055c4284089d18d62841932295d6963ed0f8831735cb9829ebc1c66ad2b7325
|
| 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.dev20250927194541-py312-none-macosx_11_0_arm64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
78024e2cc0f99b36e17316c38dad13f0e0a1aba74709e2b6471fae1c58470bc6
|
|
BLAKE2b-256 checksum How to use checksums |
e6a856c6ae0b027e3c202ad93ec6bd0963127956c93578de84e36f3c20739656
|
| 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.dev20250927194541-py312-none-macosx_10_13_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
5315be1fb9a2882495eeb80006635d08fef01cc00854d6001b07a70cf5c73482
|
|
BLAKE2b-256 checksum How to use checksums |
7bb6692e2df1256a405fc63bd692b79feb3d4ce82854992086c2ddb6778370a1
|
| 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.dev20250927194541-py311-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
3a74b5c49bfa3b5d17230f3de33b77536ed739ed4b190bb043ec279c8a3162f3
|
|
BLAKE2b-256 checksum How to use checksums |
c20e394ec1ab9d83596c0a71375985d30087af88f9d2c7c810cffecd78bfcb52
|
| 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.dev20250927194541-py311-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
b5558c3a95bd8108235b05f199994afd4c0d758cb5d689af3439bfa00d88af19
|
|
BLAKE2b-256 checksum How to use checksums |
1b8afa3f602f79894f09024f73d9cc6f3dea842485dbc3038fb28d20d51ac6d4
|
| 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.dev20250927194541-py311-none-macosx_11_0_arm64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
59b8d5306067fef19b5fe7c4537766b1644f4576f3d4f03a292277d9fa8d775c
|
|
BLAKE2b-256 checksum How to use checksums |
85625b94645b3174e12c2074e6d864bcdc56e28644b2bd32d9dce034f8e15f9e
|
| 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.dev20250927194541-py311-none-macosx_10_13_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
8c685f079bb019b9efd530334cfdd2c5086395732ef1c038eb777857e8c67f56
|
|
BLAKE2b-256 checksum How to use checksums |
7e83765e4e4ca160302f04c714a2bcd675de585881614c79747d540518f46ff7
|
| 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.dev20250927194541-py310-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
0cbeacf7e56bfdbe5a295f94a0ae26ff7a18dd15cce56559e1e7310d9d7a7301
|
|
BLAKE2b-256 checksum How to use checksums |
18fad9d3ab2b7d50f87cbe077795d13cd1e70ec4caa0de406b63184fc7db2f23
|
| 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.dev20250927194541-py310-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
ec2927d5bc158129b2021c25397e248cf34ef55153fb2559becce2de9cbab868
|
|
BLAKE2b-256 checksum How to use checksums |
24bb79df5031f280fa8cd27b80117012d2a5020a70d20325e641defc27cef83d
|
| 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.dev20250927194541-py310-none-macosx_11_0_arm64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
bf346116b42f66bb903e0251fe05ce33384bd7b7d2dd209e213683508c8cb8c5
|
|
BLAKE2b-256 checksum How to use checksums |
31ec9e189aaa5a693e820849be2c8a4e508400759b1b4dccf1323dd396e29cde
|
| 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.dev20250927194541-py310-none-macosx_10_13_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250927194541-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 |
597762e1da62a6ab654052fed94ec9e987ae648bfaa579d99d4f058d7f1353bc
|
|
BLAKE2b-256 checksum How to use checksums |
cd40f030407476930955c18eef17c57c95d4f726465ac528658896c123f85bf4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.23
|
