{"id":13751475,"url":"https://github.com/yaleqc/qtcodes","last_synced_at":"2026-04-02T03:20:10.189Z","repository":{"id":42978361,"uuid":"273963713","full_name":"yaleqc/qtcodes","owner":"yaleqc","description":"Qiskit Topological Codes","archived":false,"fork":false,"pushed_at":"2022-06-23T05:21:18.000Z","size":76914,"stargazers_count":98,"open_issues_count":19,"forks_count":45,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-12-16T01:41:39.737Z","etag":null,"topics":["decoder","ibm","qiskit","qiskit-tutorial","quantum-computing","quantum-error-correction","surface-code","topological-quantum-computation"],"latest_commit_sha":null,"homepage":"https://yaleqc.com/qtcodes/reference/qtcodes/","language":"Jupyter Notebook","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/yaleqc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-21T18:42:53.000Z","updated_at":"2025-10-20T12:51:34.000Z","dependencies_parsed_at":"2022-08-27T21:01:35.910Z","dependency_job_id":null,"html_url":"https://github.com/yaleqc/qtcodes","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/yaleqc/qtcodes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaleqc%2Fqtcodes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaleqc%2Fqtcodes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaleqc%2Fqtcodes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaleqc%2Fqtcodes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yaleqc","download_url":"https://codeload.github.com/yaleqc/qtcodes/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaleqc%2Fqtcodes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31295062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T01:43:37.129Z","status":"online","status_checked_at":"2026-04-02T02:00:08.535Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["decoder","ibm","qiskit","qiskit-tutorial","quantum-computing","quantum-error-correction","surface-code","topological-quantum-computation"],"created_at":"2024-08-03T09:00:46.066Z","updated_at":"2026-04-02T03:20:10.121Z","avatar_url":"https://github.com/yaleqc.png","language":"Jupyter Notebook","funding_links":[],"categories":["Community"],"sub_categories":[],"readme":"# qtcodes\n*Qiskit Topological Codes*\n\n[![License](https://img.shields.io/github/license/yaleqc/qtcodes.svg?style=popout-square)](https://opensource.org/licenses/Apache-2.0)\n[![](https://img.shields.io/github/release/yaleqc/qtcodes.svg?style=popout-square)](https://github.com/yaleqc/qtcodes/releases)\n[![](https://img.shields.io/pypi/dm/qtcodes.svg?style=popout-square)](https://pypi.org/project/qtcodes/)\n\n## Installation\n\n*Conda users, please make sure to `conda install pip` before running any pip installation if you want to install `qtcodes` into your conda environment.*\n\n`qtcodes` is published on PyPI. So, to install, simply run:\n\n```bash\npip install qtcodes\n```\nIf you also want to download the dependencies needed to run optional tutorials, please use `pip install qtcodes[dev]` or `pip install 'qtcodes[dev]'` (for `zsh` users).\n\n\nTo check if the installation was successful, run:\n\n```python\n\u003e\u003e\u003e import qtcodes as qtc\n```\n\n## Building from source\n\nTo build `qtcodes` from source, pip install using:\n\n```bash\ngit clone https://github.com/yaleqc/qtcodes.git\ncd qtcodes\npip install --upgrade .\n```\n\nIf you also want to download the dependencies needed to run optional tutorials, please use `pip install --upgrade .[dev]` or `pip install --upgrade '.[dev]'` (for `zsh` users).\n\n\n#### Installation for Devs\n\nIf you intend to contribute to this project, please install `qtcodes` in editable mode as follows:\n```bash\ngit clone https://github.com/yaleqc/qtcodes.git\ncd qtcodes\npip install -e .[dev]\n```\nPlease use `pip install -e '.[dev]'` if you are a `zsh` user.\n\n#### Building documentation locally\n\nSet yourself up to use the `[dev]` dependencies. Then, from the command line run:\n```bash\nmkdocs build\n```\n\n---\n\n## Motivation\n\nQuantum computation is an inherently noisy process. Scalable quantum computers will require fault-tolerance to implement useful computation. There are many proposed approaches to this, but one promising candidate is the family of *topological quantum error correcting codes*.\n\nCurrently, the [`qiskit.ignis.verification.topological_codes`](https://qiskit.org/documentation/apidoc/verification.html#topological-codes) module provides a general framework for QEC and implements one specific example, the *repetition code*. Qiskit Topological Codes builds out the `qtcodes` module into a diverse family of QEC encoders and decoders, supporting the repetition code, XXXX/ZZZZ (XXZZ) rotated surface code, and the XZZX rotated surface code.\n\nInspired by the [Qiskit Textbook](https://qiskit.org/textbook/ch-quantum-hardware/error-correction-repetition-code.html), we've written a full set of [jupyter notebook tutorials](https://github.com/yaleqc/qtcodes/tree/master/tutorials) to demonstrate the [circuit encoders](https://github.com/yaleqc/qtcodes/tree/master/qtcodes/circuits), [graph decoders](https://github.com/yaleqc/qtcodes/tree/master/qtcodes/fitters), and [benchmarking tools](https://github.com/yaleqc/qtcodes/tree/master/qtcodes/tools/benchmarking.py) that compose Qiskit Topological Codes. These tutorials both demonstrate the elegance of QEC codes as well as the utility of this package -- please check them out!\n\n## Codebase\n\n\u003cp align=\"center\"\u003e\n\u003cimg width=\"300\" alt=\"surface code teaser\" src=\"https://user-images.githubusercontent.com/10100490/130364540-58ec18b5-6e97-4625-a0ff-e8990f47782f.jpg\"\u003e\u003cbr\u003e\n\u003cdiv flush=\"left\"\u003e\u003cb\u003eFig 1.\u003c/b\u003e Rotated XXXX/ZZZZ (XXZZ) Surface Code. ZZZZ/ZZ syndromes in red, XXXX/XX syndromes in purple, physical errors in green, and syndrome hits in yellow.\u003c/div\u003e\n\u003c/p\u003e\n\nTopological QEC codes disperse, and thus protect, one quantum bit of logical information across many physical qubits. The classical repetition code distributes 1 bit of logical information across multiple imperfect physical bits (e.g. logical 0 is 000...0 and logical 1 is 111...1). In the classical repetition logical 0 bit, for example, a few physical bits may flip to 1, but the majority will very likely stay in 0, thus preserving the logical 0 bit. Similarly, the surface code protects one logical qubit in a grid of imperfect physical qubits against Pauli errors.\n\nThe `qtcodes` module can be broken down into `circuits` (encoders) and `fitters` (decoders). Additionally, unittests can be found in `tests` and benchmarking tools in `qtcodes/tools`.\n\n\n\u003e The rotated surface code is based on the earlier theoretical idea of a [toric code](https://decodoku.blogspot.com/2016/03/6-toric-code.html), with periodic boundary conditions instead of open boundary conditions. This has been shown to be largely identical, but embedding a surface code on an actual device is much easier.\n\n### Circuits\n\nThe `qtcodes.circuits` sub-module contains classes such as `XXZZQubit`, `XZZXQubit`, and `RepetitionQubit`, which each allow users to construct and manipulate circuits encoding one logical qubit using a particular QEC code.\n\nFor example, we can create and apply a logical X onto a `RepetitionQubit` as follows\n\n```python\nfrom qtcodes import RepetitionQubit\nqubit = RepetitionQubit({\"d\":3},\"t\")\nqubit.reset_z()\nqubit.stabilize()\nqubit.x()\nqubit.stabilize()\nqubit.readout_z()\nqubit.draw(output='mpl', fold=150)\n```\n![Repetition Code Qubit](https://user-images.githubusercontent.com/10100490/130364536-756c5e53-ef73-4564-8b44-6b978325fe9c.png)\n\n`qtcodes.circuits.circ` also allows users to create  `TopologicalRegister`s (treg: a collection of topological qubits) and `TopologicalCircuit`s (tcirc: a circuit built using a treg), the analog of `QuantumRegister` and `QuantumCircuit`.\n\nWe can, for example, create a tcirc and treg out of two `RepetitionQubit`s.\n\n```python\nfrom qtcodes import TopologicalRegister, TopologicalCircuit\ntreg = TopologicalRegister(ctypes=[REPETITION, REPETITION], params=[{\"d\": 3}, {\"d\": 3}])\ncirc = TopologicalCircuit(treg)\ncirc.x(treg[0])\ncirc.stabilize(treg[1])\ncirc.x(1)\ncirc.draw(output='mpl', fold=500)\n```\n\n![Repetition Code TCirc](https://user-images.githubusercontent.com/10100490/130364537-473de90a-6ed2-48a7-924f-00dd1fbce3e4.png)\n\nLearn more about circuits through encoder tutorials such as this [one](https://github.com/yaleqc/qtcodes/tree/master/tutorials/xxzz/1-circuits.ipynb) for the XXXX/ZZZZ rotated surface code.\n\n### Fitters\n\nTopological codes aim to build better (read: less noisy) logical qubits out of many imperfect physical qubits. This improvement is enabled by decoding schemes that can detect and thus correct for errors on a code's constituent physical qubits.\n\nThe Qiskit Topological Codes package leverages Minimum-Weight Perfect Matching Graph Decoding to efficiently correct logical qubit readout.\n\n\nFor example, we can decode the syndrome hits in Fig 1 and fine the most probable error chains (data qubit flips) corresponding to these syndrome hits.\n\n```python\n#d: surface code side length, T: number of rounds\ndecoder = RotatedDecoder({\"d\":5,\"T\":1})\nall_syndromes = {\"X\": [(0,1.5,.5),(0,.5,1.5)], \"Z\": [(0,0.5,0.5),(0,1.5,1.5),(0,1.5,3.5), (0,3.5,3.5)]}\nmatches = {}\n\nfor syndrome_key, syndromes in all_syndromes.items():\n    print(f\"{syndrome_key} Syndrome Graph\")\n    error_graph = decoder._make_error_graph(syndromes,syndrome_key)\n    print(\"Error Graph\")\n    decoder.draw(error_graph)\n    matches[syndrome_key] = decoder._run_mwpm(error_graph)\n    matched_graph = decoder._run_mwpm_graph(error_graph)\n    print(\"Matched Graph\")\n    decoder.draw(matched_graph)\n    print(f\"Matches: {matches[syndrome_key]}\")\n    print(\"\\n===\\n\")\n```\n\n\u003cp align=\"middle\" style=\"background:#fff\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/10100490/130364532-93f60a0f-1636-4967-b324-6745e23a003a.png\" width=\"49%\" align=\"top\"/\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/10100490/130364534-4316ef5a-38f4-4d67-83b9-dde62e2bf8c2.png\" width=\"49%\" align=\"top\"/\u003e\n\u003c/p\u003e\n\nIn this way, Qiskit Topological Codes uses graph decoding to find and correct for the most probable set of errors (error chains).\n\nThe careful reader will notice that connecting syndrome hits in the most probable set of \"error chains\" does not uniquely specify the underlying physical qubits that underwent physical errors (i.e. there are multiple shortest paths between two syndrome hits). It turns out, by the nuances of how topological codes store  logical information (i.e. codespace), in most cases the exact path across physical qubits doesn't matter when correcting for an error chain. Read more about this in this [tutorial](https://github.com/yaleqc/qtcodes/tree/master/tutorials/xxzz/2-fitters.ipynb) on Decoding for XXZZ Qubits!\n\n### Benchmarking\n\nFinally, the efficiency and efficacy of the Qiskit Topological Codes package is demonstrated through benchmark simulations achieving threshold for the Repetition, XXZZ, and XZZX topological codes. Here, threshold is defined as the maximum physical error rate (i.e. imperfection level of physical qubits) below which larger surface codes perform better than smaller surface codes.\n\n\u003cp align=\"middle\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/10100490/130364554-7e1536f2-a6be-4487-b0dc-651af1a861b9.png\" width=\"32%\" /\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/10100490/130364555-3f84d008-851b-42db-a8fc-e9af5864586d.png\" width=\"32%\" /\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/10100490/130364556-32375c1c-2be0-4707-a44d-cfa080265800.png\" width=\"32%\" /\u003e\u003cbr\u003e\n  \u003cdiv flush=\"left\"\u003e\n  \u003cb\u003eFig. 2\u003c/b\u003e By simulating circuits with errors inserted between two rounds of stabilizing measurements, we are able to extract a logical error rate for each code for a given physical error rate (quality of physical qubit) and surface code size. In particular, threshold is shown for the repetition code (left), XXZZ code (center), and XZZX code (right).\u003c/div\u003e\n\u003c/p\u003e\n\nExplore the benchmarking [tools](https://github.com/yaleqc/qtcodes/tree/master/qtcodes/tools/benchmarking.py) and [simulations](https://github.com/yaleqc/qtcodes/tree/master/data/) to see how the graphs in Fig. 2 were created.\n\n## Future Directions\n\n*Checkout [issues](https://github.com/yaleqc/qtcodes/issues) to see what we are working on these days!*\n\n## Acknowledgements\n\n**Core Devs:** [Shantanu Jha](https://github.com/Phionx), [Amir Ebrahimi](https://github.com/amirebrahimi), [Jeffrey Gong](https://github.com/jeffreyjgong)\n\nThanks to our mentor [James Wootton](https://github.com/quantumjim) (IBM) for invaluable feedback and support since the inception of this project at the IBM Qiskit - Summer Jam Hackathon 2020.\n\nThanks also to [Matthew Treinish](https://github.com/mtreinish) from the [retworkx](https://github.com/Qiskit/retworkx) team for helping onboard and support this project.\n\n**Alums:** [Henry Liu](https://github.com/liuhenry), [Shraddha Singh](https://github.com/shraggy), [Will Sun](https://github.com/muirheadmaster), [Andy Ding](https://github.com/ZhenghaoDing), [Jessie Chen](https://github.com/JazzyCH), [Aaron Householder](https://github.com/aaronhouseholder), [Allen Mi](https://github.com/Allenator)\n\n\n## References\n\n*Here's some reading material that we found particularly useful:*\n- Presentation [slides](https://docs.google.com/presentation/d/17JGXswqiTvsd_d_-Hkp3OGoYrOkaw2UQ2W538c1ibvU/edit?usp=sharing) and [video](https://www.youtube.com/watch?v=jb1qD0pZbF4\u0026ab_channel=Qiskit) about this package to the Qiskit Advocate community at the November 2020 Qiskit Advocate Demo Session.\n- [Surface Codes: Towards Practical Large-Scale Quantum Computation](https://arxiv.org/abs/1208.0928)\n- [Stabilizer Codes and Quantum Error Correction](https://arxiv.org/pdf/quant-ph/9705052.pdf)\n- [Multi-path Summation for Decoding 2D Topological Codes](https://quantum-journal.org/wp-content/uploads/2018/10/q-2018-10-19-102.pdf)\n- [Qiskit Textbook - Introduction to Quantum Error Correction using Repetition Codes](https://qiskit.org/textbook/ch-quantum-hardware/error-correction-repetition-code.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyaleqc%2Fqtcodes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyaleqc%2Fqtcodes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyaleqc%2Fqtcodes/lists"}