{"id":26446552,"url":"https://github.com/quantumlib/tesseract-decoder","last_synced_at":"2025-03-18T12:18:22.271Z","repository":{"id":282947196,"uuid":"946710540","full_name":"quantumlib/tesseract-decoder","owner":"quantumlib","description":"A search-based decoder for quantum error correction (QEC)","archived":false,"fork":false,"pushed_at":"2025-03-17T19:52:20.000Z","size":769,"stargazers_count":9,"open_issues_count":2,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-17T20:26:13.037Z","etag":null,"topics":["a-star","algorithms","color-code","cpp","google-quantum","qec-codes","quantum","quantum-computing","quantum-error-correction","surface-code","syndrome-decoding"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quantumlib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":".github/SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-11T15:00:30.000Z","updated_at":"2025-03-17T20:21:53.000Z","dependencies_parsed_at":"2025-03-17T20:36:23.698Z","dependency_job_id":null,"html_url":"https://github.com/quantumlib/tesseract-decoder","commit_stats":null,"previous_names":["quantumlib/tesseract-decoder"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumlib%2Ftesseract-decoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumlib%2Ftesseract-decoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumlib%2Ftesseract-decoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumlib%2Ftesseract-decoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quantumlib","download_url":"https://codeload.github.com/quantumlib/tesseract-decoder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244217950,"owners_count":20417677,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a-star","algorithms","color-code","cpp","google-quantum","qec-codes","quantum","quantum-computing","quantum-error-correction","surface-code","syndrome-decoding"],"created_at":"2025-03-18T12:18:21.727Z","updated_at":"2025-03-18T12:18:22.261Z","avatar_url":"https://github.com/quantumlib.png","language":"C++","readme":"\u003cdiv align=\"center\"\u003e\n\n# Tesseract Decoder\n\nA Search-Based Decoder for Quantum Error Correction.\n\n[![Licensed under the Apache 2.0 open-source license](https://img.shields.io/badge/License-Apache%202.0-3c60b1.svg?logo=opensourceinitiative\\\u0026logoColor=white\\\u0026style=flat-square)](https://github.com/quantumlib/tesseract-decoder/blob/main/LICENSE)\n![C++](https://img.shields.io/badge/C++-20-fcbc2c?style=flat-square\u0026logo=C%2B%2B\u0026logoColor=white)\n\n[Installation](#installation) \u0026ndash;\n[Usage](#usage) \u0026ndash;\n[Help](#help) \u0026ndash;\n[Citation](#citation) \u0026ndash;\n[Contact](#contact)\n\n\u003c/div\u003e\n\nTesseract is a Most Likely Error decoder designed for Low Density Parity Check (LDPC) quantum\nerror-correcting codes. It applies pruning heuristics and manifold orientation techniques during a\nsearch over the error subsets to identify the most likely error configuration consistent with the\nobserved syndrome. Tesseract archives significant speed improvements over traditional integer\nprogramming-based decoders while maintaining comparable accuracy at moderate physical error rates.\n\nWe tested the Tesseract decoder for:\n\n*   Surface codes\n*   Color codes\n*   Bivariate-bicycle codes\n*   Transversal CNOT protocols for surface codes\n\n## Features\n\n*   **A\\* search:** deploys [A\\* search](https://en.wikipedia.org/wiki/A*_search_algorithm) while\n    running a [Dijkstra algorithm](https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm) with early\n    stop for high performance.\n*   **Stim and DEM Support:** processes [Stim](https://github.com/quantumlib/stim) circuit files and\n    [Detector Error Model\n    (DEM)](https://github.com/quantumlib/Stim/blob/main/doc/file_format_dem_detector_error_model.md)\n    files with arbitrary error models.\n*   **Parallel Decoding:** uses multithreading to accelerate the decoding process, making it\n    suitable for large-scale simulations.\n*   **Efficient Beam Search:** implements a [beam search](https://en.wikipedia.org/wiki/Beam_search)\n    algorithm to minimize decoding cost and enhance efficiency.\n*   **Sampling and Shot Range Processing:** supports sampling shots from circuits and processing\n    specific ranges of shots for flexible experiment setups.\n*   **Detailed Statistics:** provides comprehensive statistics output, including shot counts, error\n    counts, and processing times.\n*   **Heuristics**: includes flexible heuristic options: `--beam`, `--det-penalty`,\n    `--beam-climbing`, `--no-revisit-dets`, `--at-most-two-errors-per-detector` and `--pqlimit` to\n    improve performance while maintaining a low logical error rate. To learn more about these\n    options, use `./bazel-bin/tesseract/tesseract --help`\n\n## Installation\n\nTesseract relies on the following external libraries:\n\n*   [argparse](https://github.com/p-ranav/argparse): For command-line argument parsing.\n*   [nlohmann/json](https://github.com/nlohmann/json): For JSON handling (used for statistics output).\n*   [Stim](https://github.com/quantumlib/stim): For quantum circuit simulation and error model\n    handling.\n\n### Build Instructions\n\nTesseract uses [Bazel](https://bazel.build/) as its build system. To build the decoder:\n\n```bash\nbazel build tesseract:all\n```\n\n## Usage\n\nThe file `tesseract_main.cc` provides the main entry point for Tesseract Decoder. It can decode\nerror events from Stim circuits, DEM files, and pre-existing detection event files.\n\nBasic Usage:\n\n```bash\n./tesseract --circuit CIRCUIT_FILE.stim --sample-num-shots N --print-stats\n```\n\nExample with Advanced Options:\n\n```bash\n./tesseract \\\n        --pqlimit 1000000 \\\n        --at-most-two-errors-per-detector \\\n        --det-order-seed 232852747 \\\n        --circuit circuit_file.stim \\\n        --sample-seed 232856747 \\\n        --sample-num-shots 10000 \\\n        --threads 32 \\\n        --print-stats \\\n        --beam 23 \\\n        --num-det-orders 1 \\\n        --shot-range-begin 582 \\\n        --shot-range-end 583\n```\n\n### Example Usage\n\nSampling Shots from a Circuit:\n\n```bash\n./tesseract --circuit surface_code.stim --sample-num-shots 1000 --out predictions.01 --out-format 01\n```\n\nUsing a Detection Event File:\n\n```bash\n./tesseract --in events.01 --in-format 01 --dem surface_code.dem --out decoded.txt\n```\n\nUsing a Detection Event File and Observable Flips:\n\n```bash\n./tesseract --in events.01 --in-format 01 --obs_in obs.01 --obs-in-format 01 --dem surface_code.dem --out decoded.txt\n```\n\nTesseract supports reading and writing from all of Stim's standard [output\nformats](https://github.com/quantumlib/Stim/blob/main/doc/result_formats.md).\n\n### Performance Optimization\n\nHere are some tips for improving performance:\n\n*   *Parallelism over shots*: increase `--threads` to leverage multicore processors for faster\n    decoding.\n*   *Beam Search*: use `--beam` to control the trade-off between accuracy and speed. Smaller beam sizes\n    result in faster decoding but potentially lower accuracy.\n*   *Beam Climbing*: enable `--beam-climbing` for enhanced cost-based decoding.\n*   *At most two errors per detector*: enable `--at-most-two-errors-per-detector` to improve\n    performance.\n*   *Priority Queue limit*: use `--pqlimit` to limit the size of the priority queue.\n\n### Output Formats\n\n*   *Observable flips output*: predictions of logical errors.\n*   *DEM usage frequency output*: if `--dem-out` is specified, outputs estimated error frequencies.\n*   *Statistics output*: includes number of shots, errors, low confidence shots, and processing time.\n\n## Help\n\n*   Do you have a feature request or want to report a bug? [Open an issue on\n    GitHub] to report it!\n*   Do you have a code contribution? Read our [contribution guidelines], then\n    open a [pull request]!\n\n[Open an issue on GitHub]: https://github.com/quantumlib/tesseract-decoder/issues/new/choose\n[contribution guidelines]: https://github.com/quantumlib/tesseract-decoder/blob/main/CONTRIBUTING.md\n[pull request]: https://help.github.com/articles/about-pull-requests\n\nWe are committed to providing a friendly, safe, and welcoming environment for\nall. Please read and respect our [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Citation\n\nWhen publishing articles or otherwise writing about Tesseract Decoder, please\ncite the following:\n\n```latex\n@misc{beni2025tesseractdecoder,\n    title={Tesseract: A Search-Based Decoder for Quantum Error Correction},\n    author = {Aghababaie Beni, Laleh and Higgott, Oscar and Shutty, Noah},\n    year={2025},\n    eprint={2503.10988},\n    archivePrefix={arXiv},\n    primaryClass={quant-ph},\n    doi = {10.48550/arXiv.2503.10988},\n    url={https://arxiv.org/abs/2503.10988},\n}\n```\n\n## Contact\n\nFor any questions or concerns not addressed here, please email \u003cquantum-oss-maintainers@google.com\u003e.\n\n## Disclaimer\n\nTesseract Decoder is not an officially supported Google product. This project is not eligible for\nthe [Google Open Source Software Vulnerability Rewards\nProgram](https://bughunters.google.com/open-source-security).\n\nCopyright 2025 Google LLC.\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://quantumai.google\"\u003e\n    \u003cimg width=\"15%\" alt=\"Google Quantum AI\"\n         src=\"./docs/images/quantum-ai-vertical.svg\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n","funding_links":[],"categories":["Quantum error correction"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantumlib%2Ftesseract-decoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquantumlib%2Ftesseract-decoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantumlib%2Ftesseract-decoder/lists"}