Pre-release
This release is a pre-release and may not be stable for production use.
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.
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 quantum-oss-maintainers@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.dev20250801001043
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 37.8 MB
Release files / tesseract_decoder-0.1.1.dev20250801001043-py312-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py312-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.3 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.39+ x86-64 Python 3.12 |
|
SHA-256 checksum How to use checksums |
0aefa3d1269757548a9dad3b0633b4071d3deb0a102f28b1a922fc93a57fda6b
|
|
BLAKE2b-256 checksum How to use checksums |
27d4466496194ffc3d26b6ed8ff263f5a0b54e15153eb302c5af7f2e0738e114
|
| Upload date | |
|
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.dev20250801001043-py312-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py312-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.35+ x86-64 Python 3.12 |
|
SHA-256 checksum How to use checksums |
f75657dc25cfd2474f4469a478d07d4b23a13c21f0426148d3fc79f83a150ff1
|
|
BLAKE2b-256 checksum How to use checksums |
058f7a8557371150558fc565445d54616c7826cfbebe7bb6ab9785ca2c086a4f
|
| Upload date | |
|
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.dev20250801001043-py312-none-macosx_11_0_arm64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py312-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | Python 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
8e52752cdc4e4527ad9df470fad80a3b6f93e7de3a6d6ed41e7a0192e8f030c3
|
|
BLAKE2b-256 checksum How to use checksums |
ecc82b3d098c98b5dcd5b2aa940990f2962f2d37cdf52a7cc0af11d5560ebaaa
|
| Upload date | |
|
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.dev20250801001043-py312-none-macosx_10_13_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py312-none-macosx_10_13_x86_64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | Python 3.12 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
4fccb533c6ef0afc961984f28f3021831deaff75b675eac6c7db7724049ba244
|
|
BLAKE2b-256 checksum How to use checksums |
3ddd0a44e4a8324d322ae36c779672d6d8ed06533c2bd88ae8ec74c3b5353631
|
| Upload date | |
|
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.dev20250801001043-py311-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py311-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.3 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.39+ x86-64 Python 3.11 |
|
SHA-256 checksum How to use checksums |
c2210e1a1f023745c5b972043c3bf8f119477795623339fa7231973b48cbc212
|
|
BLAKE2b-256 checksum How to use checksums |
56130da010b572e4c126c7f34695757f117f274e38cb0be86711813ad3599042
|
| Upload date | |
|
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.dev20250801001043-py311-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py311-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.35+ x86-64 Python 3.11 |
|
SHA-256 checksum How to use checksums |
9e0e8fd580a7bcc3b4e16bf8025b7d7d146624a2ba0d6bb3ba41f7f5f425fd49
|
|
BLAKE2b-256 checksum How to use checksums |
225ec7401d1f501545b8e1de6f6cfba3b517214b0d0f0411b264aff257726a2d
|
| Upload date | |
|
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.dev20250801001043-py311-none-macosx_11_0_arm64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py311-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | Python 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
9502e07406f9574c6a3aafba0db2d2f5eb4d4b3a479f7e739cbb5e8aedec1b23
|
|
BLAKE2b-256 checksum How to use checksums |
ed0982538ef137c52355063f32f80fcdd547092efdb8033efb0a96274b8ccafd
|
| Upload date | |
|
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.dev20250801001043-py311-none-macosx_10_13_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py311-none-macosx_10_13_x86_64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | Python 3.11 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
ff595d1ed80848f84e65e0714e147754171816993218dc8ae02fe0b53d20a30c
|
|
BLAKE2b-256 checksum How to use checksums |
f02e5082e49f7eabd2c6a8e681c86b688cd964f7038a2847456d7c78dc619b08
|
| Upload date | |
|
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.dev20250801001043-py310-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py310-none-manylinux_2_39_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.3 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.39+ x86-64 Python 3.10 |
|
SHA-256 checksum How to use checksums |
64e42fbbcf86538454f7feeb6ca795d5acbcab2dc5d684ed5235243fad2b7d5b
|
|
BLAKE2b-256 checksum How to use checksums |
ac469dbdf9f51763d16b7de8a67eab5e8c3cdd421d43142e92a9e11e14737c07
|
| Upload date | |
|
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.dev20250801001043-py310-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py310-none-manylinux_2_35_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | Linux glibc 2.17+ x86-64 Linux glibc 2.35+ x86-64 Python 3.10 |
|
SHA-256 checksum How to use checksums |
be25fe924f8e0e7a7d924b3dd3e79245e9a07909dfc77e3daf0a8eb54acbc4a5
|
|
BLAKE2b-256 checksum How to use checksums |
bcbf6c0410b065afd1a08ecedcb9eb97b6e1bb0f2c9b2343927baa85c0bcb90b
|
| Upload date | |
|
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.dev20250801001043-py310-none-macosx_11_0_arm64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py310-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | Python 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
462d5b52cfbde2be49885d219c6649b880aa969aaf8252627338392c3f5fe929
|
|
BLAKE2b-256 checksum How to use checksums |
eacddadecc443185fa06a4ed95c7bdc4e86d81c91f89e2a68d53a05b68236913
|
| Upload date | |
|
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.dev20250801001043-py310-none-macosx_10_13_x86_64.whl
| Download URL | tesseract_decoder-0.1.1.dev20250801001043-py310-none-macosx_10_13_x86_64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | Python 3.10 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
4b373cd2ade7f09cab4b4087d6bebad0bd19ee7c81ff9e2320c42e489e17da25
|
|
BLAKE2b-256 checksum How to use checksums |
1daf6a80cfd6fab829a25af40c8c3a9877a3c404ed2b51b9ee9d58c0bf7ffc36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.9.23
|
