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.

C++

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 --pqlimit to 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 --threads to leverage multicore processors for faster decoding.
Beam Search: use --beam to control the trade-off between accuracy and speed. Smaller beam sizes result in faster decoding but potentially lower accuracy.
Beam Climbing: enable --beam-climbing for enhanced cost-based decoding.
At most two errors per detector: enable --at-most-two-errors-per-detector to improve performance.
Priority Queue limit: use --pqlimit to limit the size of the priority queue.

Output Formats

Observable flips output: predictions of logical errors.
DEM usage frequency output: if --dem-out is 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.

Metadata

Release files for tesseract-decoder 0.1.1.dev20250831005033

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for tesseract-decoder 0.1.1.dev20250831005033
File	Interpreter	ABI	Platform	Reset
tesseract_decoder-0.1.1.dev20250831005033-py312-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl 3.5 MB Aug 31, 2025	Python 3.12	none	Linux glibc 2.39+ x86-64, Linux glibc 2.17+ x86-64	Details
tesseract_decoder-0.1.1.dev20250831005033-py312-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl 3.6 MB Aug 31, 2025	Python 3.12	none	Linux glibc 2.35+ x86-64, Linux glibc 2.17+ x86-64	Details
tesseract_decoder-0.1.1.dev20250831005033-py312-none-macosx_11_0_arm64.whl 3.2 MB Aug 31, 2025	Python 3.12	none	macOS 11.0+ ARM64	Details
tesseract_decoder-0.1.1.dev20250831005033-py312-none-macosx_10_13_x86_64.whl 3.1 MB Aug 31, 2025	Python 3.12	none	macOS 10.13+ x86-64	Details
tesseract_decoder-0.1.1.dev20250831005033-py311-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl 3.5 MB Aug 31, 2025	Python 3.11	none	Linux glibc 2.17+ x86-64, Linux glibc 2.39+ x86-64	Details
tesseract_decoder-0.1.1.dev20250831005033-py311-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl 3.6 MB Aug 31, 2025	Python 3.11	none	Linux glibc 2.17+ x86-64, Linux glibc 2.35+ x86-64	Details
tesseract_decoder-0.1.1.dev20250831005033-py311-none-macosx_11_0_arm64.whl 3.2 MB Aug 31, 2025	Python 3.11	none	macOS 11.0+ ARM64	Details
tesseract_decoder-0.1.1.dev20250831005033-py311-none-macosx_10_13_x86_64.whl 3.1 MB Aug 31, 2025	Python 3.11	none	macOS 10.13+ x86-64	Details
tesseract_decoder-0.1.1.dev20250831005033-py310-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl 3.5 MB Aug 31, 2025	Python 3.10	none	Linux glibc 2.39+ x86-64, Linux glibc 2.17+ x86-64	Details
tesseract_decoder-0.1.1.dev20250831005033-py310-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl 3.6 MB Aug 31, 2025	Python 3.10	none	Linux glibc 2.35+ x86-64, Linux glibc 2.17+ x86-64	Details
tesseract_decoder-0.1.1.dev20250831005033-py310-none-macosx_11_0_arm64.whl 3.2 MB Aug 31, 2025	Python 3.10	none	macOS 11.0+ ARM64	Details
tesseract_decoder-0.1.1.dev20250831005033-py310-none-macosx_10_13_x86_64.whl 3.1 MB Aug 31, 2025	Python 3.10	none	macOS 10.13+ x86-64	Details

Total release size: 40.3 MB

Release files / tesseract_decoder-0.1.1.dev20250831005033-py312-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-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	`cdb93f2af4d9bd95897cfb30e893de019e239b3bc5c4637d8ad07e97d1f5e956`
BLAKE2b-256 checksum How to use checksums	`ebc660a21e17b8fcd2e1d3173fa58e2a373f6c4916d2aa9e6297fb98a50daa69`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`

Release files / tesseract_decoder-0.1.1.dev20250831005033-py312-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-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	`2800413a1ea26f9d962d270913f535ff5237a6a8ccdee3a4b82368f745789f2f`
BLAKE2b-256 checksum How to use checksums	`b71f8105c9c26278b8c7d355ac73652c9c8ab122e7c142bcc87b2697a0ff47ca`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`

Release files / tesseract_decoder-0.1.1.dev20250831005033-py312-none-macosx_11_0_arm64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-py312-none-macosx_11_0_arm64.whl
Size	3.2 MB
Tags	Python 3.12 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`c65246f2fa286e3d4e9d5c5748bc090aaef0ad4a97d3acf365a3d1b1e1bf09ec`
BLAKE2b-256 checksum How to use checksums	`06a4feae2d664da1e88952c817aae0e98c479d3e384866172d99332a80477ee0`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`

Release files / tesseract_decoder-0.1.1.dev20250831005033-py312-none-macosx_10_13_x86_64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-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	`69e79e1575f9464dab9f371aced8a8494eb4d3365840e5a96600f60af6139597`
BLAKE2b-256 checksum How to use checksums	`b6f72828ee0159e6241be7bb88ae9a284a3da0082ea39b8aa97c131008752f7d`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`

Release files / tesseract_decoder-0.1.1.dev20250831005033-py311-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-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	`64e060cdd0acc435f11e16f4299c0d2ccab146e818bd77f64b6ea3ec61043943`
BLAKE2b-256 checksum How to use checksums	`207f16bac686267dab8936746a7a8bd79efbfab394369469899ac20cfcb56585`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`

Release files / tesseract_decoder-0.1.1.dev20250831005033-py311-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-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	`f0fd11eebd543fbe4b087bfb7a451e11a94e3e1f619b4545398bd0ccb0c2cd9f`
BLAKE2b-256 checksum How to use checksums	`4129b7cdd92732b1719103215425eb38d5f86dd5d2cf9352a98a38c586270215`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`

Release files / tesseract_decoder-0.1.1.dev20250831005033-py311-none-macosx_11_0_arm64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-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	`fa39762a640a04c243c71be13f9e8dc806fb8d3eba6c20a254dd111db4bd2edd`
BLAKE2b-256 checksum How to use checksums	`b69c865c30e29916e00d8f645ffe3b21a746d725c5b08c1b461ba4f3ebb5fca4`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`

Release files / tesseract_decoder-0.1.1.dev20250831005033-py311-none-macosx_10_13_x86_64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-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	`861b74d3cce72c0f6bd4397fa1d548a0eaaf4e571beddff156b335005affeade`
BLAKE2b-256 checksum How to use checksums	`90115395c591b91cfb58e14f6a9d2f7036a57326510d9611590b808b6eb7c7a8`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`

Release files / tesseract_decoder-0.1.1.dev20250831005033-py310-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-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	`c39ae65b276b21442bebf0836d4bd3a15f1139e8a6afe490294e7762dddfcbd9`
BLAKE2b-256 checksum How to use checksums	`79995d2076428a0db2d087ac9f32827279751b414ae6e9b347eeb11b42cd7768`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`

Release files / tesseract_decoder-0.1.1.dev20250831005033-py310-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-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	`ef6fd643c86d6c9e4c71a0af75cec00edc4aa97bf5c9672d1ddd46c11c87de66`
BLAKE2b-256 checksum How to use checksums	`1597db9239a467989c23a0e00ae131bf6b75fa9ddf32df34ab4e2f1c0546ed70`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`

Release files / tesseract_decoder-0.1.1.dev20250831005033-py310-none-macosx_11_0_arm64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-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	`cd2a3cfb51bfbae6118ff8f096c049464fbce729d83cd144b99dcbce5cd320a3`
BLAKE2b-256 checksum How to use checksums	`78b6f2bad9c029eb2da81af86e7c75c67548fb987155e91916a135e48496a396`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`

Release files / tesseract_decoder-0.1.1.dev20250831005033-py310-none-macosx_10_13_x86_64.whl

Download URL	tesseract_decoder-0.1.1.dev20250831005033-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	`9b292f7a1626694a185f4269de192aaf80acf77b2ddf1f086a7c6cdf4d27edb6`
BLAKE2b-256 checksum How to use checksums	`fbf16f817cf3005034918d64b23fa15c6eb80c6d63cd29ce2756a681f6ac09fe`
Upload date	Aug 31, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`