{"id":24124633,"url":"https://github.com/watermarkhu/qsurface","last_synced_at":"2025-04-05T10:07:18.993Z","repository":{"id":38889702,"uuid":"178845138","full_name":"watermarkhu/qsurface","owner":"watermarkhu","description":"Python package for simulation and visualization of quantum error-correction on surface codes. The package provides the ability to inspect the error-correcting code during the decoding process, and tools to benchmark the decoder.","archived":false,"fork":false,"pushed_at":"2025-03-04T07:54:08.000Z","size":4288,"stargazers_count":66,"open_issues_count":21,"forks_count":29,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T09:08:24.320Z","etag":null,"topics":["quantum-error-correction","surface-code"],"latest_commit_sha":null,"homepage":"https://qsurface.readthedocs.io/en/latest","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/watermarkhu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-01T11:04:12.000Z","updated_at":"2025-03-21T20:48:13.000Z","dependencies_parsed_at":"2023-01-29T17:30:48.166Z","dependency_job_id":null,"html_url":"https://github.com/watermarkhu/qsurface","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watermarkhu%2Fqsurface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watermarkhu%2Fqsurface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watermarkhu%2Fqsurface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watermarkhu%2Fqsurface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/watermarkhu","download_url":"https://codeload.github.com/watermarkhu/qsurface/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247318744,"owners_count":20919484,"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":["quantum-error-correction","surface-code"],"created_at":"2025-01-11T14:34:11.283Z","updated_at":"2025-04-05T10:07:18.957Z","avatar_url":"https://github.com/watermarkhu.png","language":"Python","funding_links":[],"categories":["Quantum error correction"],"sub_categories":[],"readme":"\n# Qsurface\n\n[![PyPI version](https://img.shields.io/pypi/v/qsurface?color=blue)](https://pypi.org/project/qsurface/)\n![Build](https://github.com/watermarkhu/qsurface/workflows/Build/badge.svg)\n[![Documentation Status](https://readthedocs.org/projects/qsurface/badge/?version=latest)](https://qsurface.readthedocs.io/en/latest/?badge=latest)\n[![codecov](https://codecov.io/gh/watermarkhu/Qsurface/branch/master/graph/badge.svg?token=CWLVPDFF2L)](https://codecov.io/gh/watermarkhu/qsurface)\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/watermarkhu/qsurface/master?filepath=examples.ipynb)\n![License](https://img.shields.io/pypi/l/qsurface)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4247617.svg)](https://doi.org/10.5281/zenodo.4247617)\n[![Unitary Fund](https://img.shields.io/badge/Supported%20By-UNITARY%20FUND-brightgreen.svg?style=flat-the-badge)](http://unitary.fund)\n\nQsurface is a simulation package for the surface code, and is designed to modularize 3 aspects of a surface code simulation.\n\n1. The surface code\n2. The error model\n3. The used decoder\n\nNew types of surface codes, error modules and decoders can be added to Qsurface by using the included templates for each of the three core module categories.\n\nThe current included decoders are:\n\n* The *Mininum-Weight Perfect Matching* (`mwpm`) decoder.\n* [Delfosse's and Nickerson's](https://arxiv.org/pdf/1709.06218.pdf) *Union-Find* (`unionfind`) decoder, which has *almost-linear* worst-case time complexity.\n* Our modification to the Union-Find decoder; the *Union-Find Node-Suspension* (`ufns`) decoder, which improves the threshold of the Union-Find decoder to near MWPM performance, while retaining quasi-linear worst-case time complexity.\n\nThe compatibility of these decoders with the included surface codes are listed below.\n\n| Decoders  | `toric` code | `planar` code |\n|-----------|--------------|---------------|\n|`mwpm`     |✅            |✅             |\n|`unionfind`|✅            |✅             |\n|`ufns`     |✅            |✅             |\n\n# Installation\n\nAll required packages can be installed through:\n\n```bash\npip install qsurface\n```\n\n## Requirements\n\n* Python 3.7+\n* [Tkinter](https://docs.python.org/3/library/tkinter.html) or [PyQt5](https://riverbankcomputing.com/software/pyqt/intro) for interactive plotting.\n* Matplotlib 3.4+ for plotting on a 3D lattice (Refers to a future release of matplotlib, see [pull request](https://github.com/matplotlib/matplotlib/pull/18816))\n\n### MWPM decoder\n\nThe MWPM decoder utilizes `networkx` for finding the minimal weights in a fully connected graph. This implementation is however rather slow compared to Kolmogorov's [Blossom V](https://pub.ist.ac.at/~vnk/software.html) algorithm. Blossom V has its own license and is thus not included with Qsurface. We do provided a single function to download and compile Blossom V, and to setup the integration with Qsurface automatically.\n\n```python\n\u003e\u003e\u003e from qsurface.decoders import mwpm\n\u003e\u003e\u003e mwpm.get_blossomv()\n```\n\n# Usage\n\nTo simulate the toric code and simulate with bitflip error for 10 iterations and decode with the MWPM decoder:\n\n```python\n\u003e\u003e\u003e from qsurface.main import initialize, run\n\u003e\u003e\u003e code, decoder = initialize((6,6), \"toric\", \"mwpm\", enabled_errors=[\"pauli\"])\n\u003e\u003e\u003e run(code, decoder, iterations=10, error_rates = {\"p_bitflip\": 0.1})\n{'no_error': 8}\n```\n\nBenchmarking of decoders can be enabled by attaching a *benchmarker* object to the decoder. See the docs for the syntax and information to setup benchmarking.\n\n```python\n\u003e\u003e\u003e from qsurface.main import initialize, run\n\u003e\u003e\u003e benchmarker = BenchmarkDecoder({\"decode\":\"duration\"})\n\u003e\u003e\u003e run(code, decoder, iterations=10, error_rates = {\"p_bitflip\": 0.1}, benchmark=benchmarker)\n{'no_error': 8,\n'benchmark': {'success_rate': [10, 10],\n'seed': 12447.413636559,\n'durations': {'decode': {'mean': 0.00244155000000319,\n'std': 0.002170364089572033}}}}\n```\n\n## Plotting\n\nThe figures in Qsurface allows for step-by-step visualization of the surface code simulation (and if supported the decoding process). Each figure logs its history such that the user can move backwards in time to view past states of the surface (and decoder). Press `h` when the figure is open for more information.\n\n```python\n\u003e\u003e\u003e from qsurface.main import initialize, run\n\u003e\u003e\u003e code, decoder = initialize((6,6), \"toric\", \"mwpm\", enabled_errors=[\"pauli\"], plotting=True, initial_states=(0,0))\n\u003e\u003e\u003e run(code, decoder, error_rates = {\"p_bitflip\": 0.1, \"p_phaseflip\": 0.1}, decode_initial=False)\n```\n\n![Interactive plotting on a 6x6 toric code.](https://raw.githubusercontent.com/watermarkhu/qsurface/master/images/toric-2d.gif \"Iteractive plotting on a 2d axis\")\n\nPlotting will be performed on a 3D axis if faulty measurements are enabled.\n\n```python\n\u003e\u003e\u003e code, decoder = initialize((3,3), \"toric\", \"mwpm\", enabled_errors=[\"pauli\"], faulty_measurements=True, plotting=True, initial_states=(0,0))\n\u003e\u003e\u003e run(code, decoder, error_rates = {\"p_bitflip\": 0.05, \"p_bitflip_plaq\": 0.05}, decode_initial=False)\n```\n\n![Interactive plotting on a toric code with faulty measurements.](https://raw.githubusercontent.com/watermarkhu/qsurface/master/images/toric-3d.gif \"Iteractive plotting on a 3d axis\")\n\nIn IPython, inline images are created for each iteration of the plot, which can be tested in the [example notebook](https://mybinder.org/v2/gh/watermarkhu/qsurface/master?filepath=examples.ipynb).\n\n## Command line interface\n\nSimulations can also be initiated from the command line\n\n```bash\n$ python -m qsurface -e pauli -D mwpm -C toric simulation --p_bitflip 0.1 -n 10\n{'no_error': 8}\n```\n\nFor more information on command line interface:\n\n```bash\n$ python -m qsurface -h\nusage: qsurface\n...\n```\n\n*This project is proudly funded by the [Unitary Fund](https://unitary.fund/).*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwatermarkhu%2Fqsurface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwatermarkhu%2Fqsurface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwatermarkhu%2Fqsurface/lists"}