From 8ee7f00dc2fea9dae549f74c3dbe5a71bb2ecb2c Mon Sep 17 00:00:00 2001 From: Mark Shui Hu Date: Tue, 17 Nov 2020 21:08:15 +0100 Subject: [PATCH] release as qsurface (#34) (re)release as qsurface --- .github/workflows/python-package.yml | 4 +- .gitignore | 3 +- README.md | 46 +++++++++---------- docs/source/codes/elements.rst | 2 +- docs/source/codes/planar.rst | 8 ++-- docs/source/codes/template.rst | 8 ++-- docs/source/codes/toric.rst | 8 ++-- docs/source/conf.py | 2 +- docs/source/decoders/mwpm.rst | 8 ++-- docs/source/decoders/template.rst | 2 +- docs/source/decoders/ufns.rst | 12 ++--- docs/source/decoders/unionfind.rst | 20 ++++---- docs/source/errors/erasure.rst | 2 +- docs/source/errors/pauli.rst | 2 +- docs/source/errors/template.rst | 2 +- docs/source/index.rst | 2 +- docs/source/main.rst | 2 +- docs/source/others/plot.rst | 2 +- docs/source/threshold.rst | 2 +- examples.ipynb | 21 +++++---- manifest.in | 2 +- {opensurfacesim => qsurface}/__init__.py | 2 +- {opensurfacesim => qsurface}/__main__.py | 6 +-- .../codes/__init__.py | 0 {opensurfacesim => qsurface}/codes/_icons.py | 0 .../codes/_template/__init__.py | 0 .../codes/_template/plot.py | 0 .../codes/_template/sim.py | 6 +-- .../codes/elements.py | 0 .../codes/planar/__init__.py | 0 .../codes/planar/plot.py | 0 .../codes/planar/sim.py | 2 +- .../codes/rotated/__init__.py | 0 .../codes/toric/__init__.py | 0 .../codes/toric/plot.py | 0 .../codes/toric/sim.py | 0 .../decoders/__init__.py | 0 .../decoders/_template.py | 2 +- .../decoders/decoders.ini | 0 .../decoders/mwpm/__init__.py | 4 +- .../decoders/mwpm/blossom5/LICENSE | 0 .../decoders/mwpm/blossom5/Makefile | 0 .../decoders/mwpm/blossom5/pyInterface.cpp | 0 .../decoders/mwpm/plot.py | 0 .../decoders/mwpm/sim.py | 2 +- .../decoders/ufns/__init__.py | 0 .../decoders/ufns/elements.py | 6 +-- .../decoders/ufns/plot.py | 4 +- .../decoders/ufns/sim.py | 6 +-- .../decoders/unionfind/__init__.py | 4 +- .../decoders/unionfind/elements.py | 0 .../decoders/unionfind/plot.py | 4 +- .../decoders/unionfind/sim.py | 2 +- .../errors/__init__.py | 0 {opensurfacesim => qsurface}/errors/_icons.py | 0 .../errors/_template.py | 0 .../errors/erasure.py | 0 {opensurfacesim => qsurface}/errors/pauli.py | 0 {opensurfacesim => qsurface}/main.py | 4 +- {opensurfacesim => qsurface}/plot.py | 0 {opensurfacesim => qsurface}/threshold.py | 2 +- setup.py | 12 ++--- tests/test_cli.py | 2 +- tests/test_code.py | 2 +- tests/test_main.py | 2 +- tests/test_mplbackends.py | 2 +- tests/test_mwpm.py | 4 +- tests/test_threshold.py | 4 +- tests/test_ufns.py | 4 +- tests/test_unionfind.py | 4 +- tests/variables.py | 4 +- 71 files changed, 131 insertions(+), 125 deletions(-) rename {opensurfacesim => qsurface}/__init__.py (85%) rename {opensurfacesim => qsurface}/__main__.py (98%) rename {opensurfacesim => qsurface}/codes/__init__.py (100%) rename {opensurfacesim => qsurface}/codes/_icons.py (100%) rename {opensurfacesim => qsurface}/codes/_template/__init__.py (100%) rename {opensurfacesim => qsurface}/codes/_template/plot.py (100%) rename {opensurfacesim => qsurface}/codes/_template/sim.py (98%) rename {opensurfacesim => qsurface}/codes/elements.py (100%) rename {opensurfacesim => qsurface}/codes/planar/__init__.py (100%) rename {opensurfacesim => qsurface}/codes/planar/plot.py (100%) rename {opensurfacesim => qsurface}/codes/planar/sim.py (98%) rename {opensurfacesim => qsurface}/codes/rotated/__init__.py (100%) rename {opensurfacesim => qsurface}/codes/toric/__init__.py (100%) rename {opensurfacesim => qsurface}/codes/toric/plot.py (100%) rename {opensurfacesim => qsurface}/codes/toric/sim.py (100%) rename {opensurfacesim => qsurface}/decoders/__init__.py (100%) rename {opensurfacesim => qsurface}/decoders/_template.py (98%) rename {opensurfacesim => qsurface}/decoders/decoders.ini (100%) rename {opensurfacesim => qsurface}/decoders/mwpm/__init__.py (88%) rename {opensurfacesim => qsurface}/decoders/mwpm/blossom5/LICENSE (100%) rename {opensurfacesim => qsurface}/decoders/mwpm/blossom5/Makefile (100%) rename {opensurfacesim => qsurface}/decoders/mwpm/blossom5/pyInterface.cpp (100%) rename {opensurfacesim => qsurface}/decoders/mwpm/plot.py (100%) rename {opensurfacesim => qsurface}/decoders/mwpm/sim.py (99%) rename {opensurfacesim => qsurface}/decoders/ufns/__init__.py (100%) rename {opensurfacesim => qsurface}/decoders/ufns/elements.py (85%) rename {opensurfacesim => qsurface}/decoders/ufns/plot.py (93%) rename {opensurfacesim => qsurface}/decoders/ufns/sim.py (96%) rename {opensurfacesim => qsurface}/decoders/unionfind/__init__.py (64%) rename {opensurfacesim => qsurface}/decoders/unionfind/elements.py (100%) rename {opensurfacesim => qsurface}/decoders/unionfind/plot.py (98%) rename {opensurfacesim => qsurface}/decoders/unionfind/sim.py (99%) rename {opensurfacesim => qsurface}/errors/__init__.py (100%) rename {opensurfacesim => qsurface}/errors/_icons.py (100%) rename {opensurfacesim => qsurface}/errors/_template.py (100%) rename {opensurfacesim => qsurface}/errors/erasure.py (100%) rename {opensurfacesim => qsurface}/errors/pauli.py (100%) rename {opensurfacesim => qsurface}/main.py (98%) rename {opensurfacesim => qsurface}/plot.py (100%) rename {opensurfacesim => qsurface}/threshold.py (99%) diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index 69c1773a..89c240d3 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -39,14 +39,14 @@ jobs: flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics - name: Test with pytest, check coverage run: | - pytest --cov=opensurfacesim tests/ --cov-report=xml -m "not plotting" + pytest --cov=qsurface tests/ --cov-report=xml -m "not plotting" - name: Upload coverage to Codecov uses: codecov/codecov-action@v1 with: file: ./coverage.xml flags: unittests env_vars: OS,PYTHON - name: codecov-opensurfacesim + name: codecov-qsurface fail_ci_if_error: false path_to_write_report: ./codecov_report.gz verbose: true \ No newline at end of file diff --git a/.gitignore b/.gitignore index e398829d..e293016c 100644 --- a/.gitignore +++ b/.gitignore @@ -7,7 +7,8 @@ !requirements.txt !pytest.ini test.py -opensurfacesim/decoders/mwpm/blossom5-v2.05.src/ +qsurface/decoders/mwpm/blossom5-v2.05.src/ +!qsurface/decoders/decoders.ini .python-version .vscode/ diff --git a/README.md b/README.md index acf04662..663e481e 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,22 @@ -# opensurfacesim - -[![PyPI version](https://img.shields.io/pypi/v/opensurfacesim?color=blue)](https://pypi.org/project/opensurfacesim/) -![Build](https://github.com/watermarkhu/opensurfacesim/workflows/Build/badge.svg) -[![Documentation Status](https://readthedocs.org/projects/opensurfacesim/badge/?version=latest)](https://opensurfacesim.readthedocs.io/en/latest/?badge=latest) -[![codecov](https://codecov.io/gh/watermarkhu/OpenSurfaceSim/branch/master/graph/badge.svg?token=CWLVPDFF2L)](https://codecov.io/gh/watermarkhu/OpenSurfaceSim) -[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/watermarkhu/opensurfacesim/master?filepath=examples.ipynb) -![License](https://img.shields.io/pypi/l/opensurfacesim) +# Qsurface + +[![PyPI version](https://img.shields.io/pypi/v/qsurface?color=blue)](https://pypi.org/project/qsurface/) +![Build](https://github.com/watermarkhu/qsurface/workflows/Build/badge.svg) +[![Documentation Status](https://readthedocs.org/projects/qsurface/badge/?version=latest)](https://qsurface.readthedocs.io/en/latest/?badge=latest) +[![codecov](https://codecov.io/gh/watermarkhu/Qsurface/branch/master/graph/badge.svg?token=CWLVPDFF2L)](https://codecov.io/gh/watermarkhu/qsurface) +[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/watermarkhu/qsurface/master?filepath=examples.ipynb) +![License](https://img.shields.io/pypi/l/qsurface) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4247617.svg)](https://doi.org/10.5281/zenodo.4247617) [![Unitary Fund](https://img.shields.io/badge/Supported%20By-UNITARY%20FUND-brightgreen.svg?style=flat-the-badge)](http://unitary.fund) -Opensurfacesim is a simulation package for the surface code, and is designed to modularize 3 aspects of a surface code simulation. +Qsurface is a simulation package for the surface code, and is designed to modularize 3 aspects of a surface code simulation. 1. The surface code 2. The error model 3. The used decoder -New types of surface codes, error modules and decoders can be added to opensurfacesim by using the included templates for each of the three core module categories. +New 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. The current included decoders are: @@ -37,7 +37,7 @@ The compatibility of these decoders with the included surface codes are listed b All required packages can be installed through: ```bash -pip install opensurfacesim +pip install qsurface ``` ## Requirements @@ -48,10 +48,10 @@ pip install opensurfacesim ### MWPM decoder -The 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 opensurfacesim. We do provided a single function to download and compile Blossom V, and to setup the integration with opensurfacesim automatically. +The 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. ```python ->>> from opensurfacesim.decoders import mwpm +>>> from qsurface.decoders import mwpm >>> mwpm.get_blossomv() ``` @@ -60,7 +60,7 @@ The MWPM decoder utilizes `networkx` for finding the minimal weights in a fully To simulate the toric code and simulate with bitflip error for 10 iterations and decode with the MWPM decoder: ```python ->>> from opensurfacesim.main import initialize, run +>>> from qsurface.main import initialize, run >>> code, decoder = initialize((6,6), "toric", "mwpm", enabled_errors=["pauli"]) >>> run(code, decoder, iterations=10, error_rates = {"p_bitflip": 0.1}) {'no_error': 8} @@ -69,7 +69,7 @@ To simulate the toric code and simulate with bitflip error for 10 iterations and Benchmarking of decoders can be enabled by attaching a *benchmarker* object to the decoder. See the docs for the syntax and information to setup benchmarking. ```python ->>> from opensurfacesim.main import initialize, run +>>> from qsurface.main import initialize, run >>> benchmarker = BenchmarkDecoder({"decode":"duration"}) >>> run(code, decoder, iterations=10, error_rates = {"p_bitflip": 0.1}, benchmark=benchmarker) {'no_error': 8, @@ -81,15 +81,15 @@ Benchmarking of decoders can be enabled by attaching a *benchmarker* object to t ## Plotting -The figures in opensurfacesim 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. +The 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. ```python ->>> from opensurfacesim.main import initialize, run +>>> from qsurface.main import initialize, run >>> code, decoder = initialize((6,6), "toric", "mwpm", enabled_errors=["pauli"], plotting=True, initial_states=(0,0)) >>> run(code, decoder, error_rates = {"p_bitflip": 0.1, "p_phaseflip": 0.1}, decode_initial=False) ``` -![Interactive plotting on a 6x6 toric code.](https://raw.githubusercontent.com/watermarkhu/OpenSurfaceSim/master/images/toric-2d.gif "Iteractive plotting on a 2d axis") +![Interactive plotting on a 6x6 toric code.](https://raw.githubusercontent.com/watermarkhu/qsurface/master/images/toric-2d.gif "Iteractive plotting on a 2d axis") Plotting will be performed on a 3D axis if faulty measurements are enabled. @@ -98,24 +98,24 @@ Plotting will be performed on a 3D axis if faulty measurements are enabled. >>> run(code, decoder, error_rates = {"p_bitflip": 0.05, "p_bitflip_plaq": 0.05}, decode_initial=False) ``` -![Interactive plotting on a toric code with faulty measurements.](https://raw.githubusercontent.com/watermarkhu/OpenSurfaceSim/master/images/toric-3d.gif "Iteractive plotting on a 3d axis") +![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") -In 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/opensurfacesim/master?filepath=examples.ipynb). +In 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). ## Command line interface Simulations can also be initiated from the command line ```bash -$ python -m opensurfacesim -e pauli -D mwpm -C toric simulation --p_bitflip 0.1 -n 10 +$ python -m qsurface -e pauli -D mwpm -C toric simulation --p_bitflip 0.1 -n 10 {'no_error': 8} ``` For more information on command line interface: ```bash -$ python -m opensurfacesim -h -usage: opensurfacesim +$ python -m qsurface -h +usage: qsurface ... ``` diff --git a/docs/source/codes/elements.rst b/docs/source/codes/elements.rst index f8132ee7..7f989e0a 100644 --- a/docs/source/codes/elements.rst +++ b/docs/source/codes/elements.rst @@ -1,7 +1,7 @@ Code elements ------------- -.. automodule:: opensurfacesim.codes.elements +.. automodule:: qsurface.codes.elements :member-order: bysource :inherited-members: :members: diff --git a/docs/source/codes/planar.rst b/docs/source/codes/planar.rst index 88d59c8d..61af6686 100644 --- a/docs/source/codes/planar.rst +++ b/docs/source/codes/planar.rst @@ -4,12 +4,12 @@ Planar code Simulation ^^^^^^^^^^ -.. autoclass:: opensurfacesim.codes.planar.sim.PerfectMeasurements +.. autoclass:: qsurface.codes.planar.sim.PerfectMeasurements :member-order: bysource :inherited-members: :members: -.. autoclass:: opensurfacesim.codes.planar.sim.FaultyMeasurements +.. autoclass:: qsurface.codes.planar.sim.FaultyMeasurements :member-order: bysource :inherited-members: :members: @@ -17,9 +17,9 @@ Simulation Plotting ^^^^^^^^ -.. autoclass:: opensurfacesim.codes.planar.plot.PerfectMeasurements +.. autoclass:: qsurface.codes.planar.plot.PerfectMeasurements :member-order: bysource :inherited-members: :members: -.. autoclass:: opensurfacesim.codes.planar.plot.FaultyMeasurements \ No newline at end of file +.. autoclass:: qsurface.codes.planar.plot.FaultyMeasurements \ No newline at end of file diff --git a/docs/source/codes/template.rst b/docs/source/codes/template.rst index 0e1b23f3..5e796bdc 100644 --- a/docs/source/codes/template.rst +++ b/docs/source/codes/template.rst @@ -4,12 +4,12 @@ Template code Simulation ^^^^^^^^^^ -.. autoclass:: opensurfacesim.codes._template.sim.PerfectMeasurements +.. autoclass:: qsurface.codes._template.sim.PerfectMeasurements :member-order: bysource :inherited-members: :members: -.. autoclass:: opensurfacesim.codes._template.sim.FaultyMeasurements +.. autoclass:: qsurface.codes._template.sim.FaultyMeasurements :member-order: bysource :inherited-members: :members: @@ -17,9 +17,9 @@ Simulation Plotting ^^^^^^^^ -.. autoclass:: opensurfacesim.codes._template.plot.PerfectMeasurements +.. autoclass:: qsurface.codes._template.plot.PerfectMeasurements :member-order: bysource :inherited-members: :members: -.. autoclass:: opensurfacesim.codes._template.plot.FaultyMeasurements \ No newline at end of file +.. autoclass:: qsurface.codes._template.plot.FaultyMeasurements \ No newline at end of file diff --git a/docs/source/codes/toric.rst b/docs/source/codes/toric.rst index ad07838c..a5b44978 100644 --- a/docs/source/codes/toric.rst +++ b/docs/source/codes/toric.rst @@ -4,12 +4,12 @@ Toric code Simulation ^^^^^^^^^^ -.. autoclass:: opensurfacesim.codes.toric.sim.PerfectMeasurements +.. autoclass:: qsurface.codes.toric.sim.PerfectMeasurements :member-order: bysource :inherited-members: :members: -.. autoclass:: opensurfacesim.codes.toric.sim.FaultyMeasurements +.. autoclass:: qsurface.codes.toric.sim.FaultyMeasurements :member-order: bysource :inherited-members: :members: @@ -17,9 +17,9 @@ Simulation Plotting ^^^^^^^^ -.. autoclass:: opensurfacesim.codes.toric.plot.PerfectMeasurements +.. autoclass:: qsurface.codes.toric.plot.PerfectMeasurements :member-order: bysource :inherited-members: :members: -.. autoclass:: opensurfacesim.codes.toric.plot.FaultyMeasurements \ No newline at end of file +.. autoclass:: qsurface.codes.toric.plot.FaultyMeasurements \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 160a0a5b..6ceb17e9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -17,7 +17,7 @@ # -- Project information ----------------------------------------------------- -project = "Open Surface code Simulations" +project = "Qsurface" copyright = "2020, Mark Shui Hu" author = "Mark Shui Hu" diff --git a/docs/source/decoders/mwpm.rst b/docs/source/decoders/mwpm.rst index 8a604731..0f27cd99 100644 --- a/docs/source/decoders/mwpm.rst +++ b/docs/source/decoders/mwpm.rst @@ -1,18 +1,18 @@ Information ----------- -.. automodule:: opensurfacesim.decoders.mwpm +.. automodule:: qsurface.decoders.mwpm :members: Simulation ---------- -.. autoclass:: opensurfacesim.decoders.mwpm.sim.Toric +.. autoclass:: qsurface.decoders.mwpm.sim.Toric :member-order: bysource :inherited-members: :members: -.. autoclass:: opensurfacesim.decoders.mwpm.sim.Planar +.. autoclass:: qsurface.decoders.mwpm.sim.Planar :member-order: bysource :inherited-members: :members: @@ -21,7 +21,7 @@ Simulation Plotting -------- -.. automodule:: opensurfacesim.decoders.mwpm.plot +.. automodule:: qsurface.decoders.mwpm.plot :member-order: bysource :members: diff --git a/docs/source/decoders/template.rst b/docs/source/decoders/template.rst index 955550c6..d5ef04e8 100644 --- a/docs/source/decoders/template.rst +++ b/docs/source/decoders/template.rst @@ -1,7 +1,7 @@ Template decoder ================ -.. automodule:: opensurfacesim.decoders._template +.. automodule:: qsurface.decoders._template :member-order: bysource :inherited-members: :members: \ No newline at end of file diff --git a/docs/source/decoders/ufns.rst b/docs/source/decoders/ufns.rst index 90686c08..9270d0fa 100644 --- a/docs/source/decoders/ufns.rst +++ b/docs/source/decoders/ufns.rst @@ -1,10 +1,10 @@ Information ----------- -.. automodule:: opensurfacesim.decoders.ufns +.. automodule:: qsurface.decoders.ufns :members: -.. automodule:: opensurfacesim.decoders.ufns.elements +.. automodule:: qsurface.decoders.ufns.elements :member-order: bysource :members: @@ -14,18 +14,18 @@ Simulation The following description also applies to `.ufns.sim.Planar`. -.. autoclass:: opensurfacesim.decoders.ufns.sim.Toric +.. autoclass:: qsurface.decoders.ufns.sim.Toric :member-order: bysource :inherited-members: :members: -.. autoclass:: opensurfacesim.decoders.ufns.sim.Planar +.. autoclass:: qsurface.decoders.ufns.sim.Planar Plotting -------- -.. autoclass:: opensurfacesim.decoders.ufns.plot.Toric +.. autoclass:: qsurface.decoders.ufns.plot.Toric -.. autoclass:: opensurfacesim.decoders.ufns.plot.Planar +.. autoclass:: qsurface.decoders.ufns.plot.Planar .. [hu2020thesis] Hu, Mark Shui, *Quasilinear Time Decoding Algorithm for Topological Codes with High Error Threshold*, DOI: 10.13140/RG.2.2.13495.96162, 2020. \ No newline at end of file diff --git a/docs/source/decoders/unionfind.rst b/docs/source/decoders/unionfind.rst index aead1cee..49b19932 100644 --- a/docs/source/decoders/unionfind.rst +++ b/docs/source/decoders/unionfind.rst @@ -3,10 +3,10 @@ Information ----------- -.. automodule:: opensurfacesim.decoders.unionfind +.. automodule:: qsurface.decoders.unionfind :members: -.. automodule:: opensurfacesim.decoders.unionfind.elements +.. automodule:: qsurface.decoders.unionfind.elements :members: Simulation @@ -14,27 +14,27 @@ Simulation The following description also applies to `.unionfind.sim.Planar`. -.. autoclass:: opensurfacesim.decoders.unionfind.sim.Toric +.. autoclass:: qsurface.decoders.unionfind.sim.Toric :member-order: bysource :inherited-members: :members: -.. autoclass:: opensurfacesim.decoders.unionfind.sim.Planar +.. autoclass:: qsurface.decoders.unionfind.sim.Planar Plotting -------- -.. autoclass:: opensurfacesim.decoders.unionfind.plot.Toric +.. autoclass:: qsurface.decoders.unionfind.plot.Toric - .. autoclass:: opensurfacesim.decoders.unionfind.plot::Toric.Figure2D + .. autoclass:: qsurface.decoders.unionfind.plot::Toric.Figure2D - .. autoclass:: opensurfacesim.decoders.unionfind.plot::Toric.Figure3D + .. autoclass:: qsurface.decoders.unionfind.plot::Toric.Figure3D -.. autoclass:: opensurfacesim.decoders.unionfind.plot.Planar +.. autoclass:: qsurface.decoders.unionfind.plot.Planar - .. autoclass:: opensurfacesim.decoders.unionfind.plot::Planar.Figure2D + .. autoclass:: qsurface.decoders.unionfind.plot::Planar.Figure2D - .. autoclass:: opensurfacesim.decoders.unionfind.plot::Planar.Figure3D + .. autoclass:: qsurface.decoders.unionfind.plot::Planar.Figure3D .. [delfosse2017almost] Delfosse, Nicolas and Nickerson, Naomi H., *Almost-linear time decoding algorithm for topological codes*, arXiv preprint arXiv:1709.06218, 2017. diff --git a/docs/source/errors/erasure.rst b/docs/source/errors/erasure.rst index 9a415f36..ddd3a284 100644 --- a/docs/source/errors/erasure.rst +++ b/docs/source/errors/erasure.rst @@ -1,5 +1,5 @@ Erasure error ------------- -.. automodule:: opensurfacesim.errors.erasure +.. automodule:: qsurface.errors.erasure :members: \ No newline at end of file diff --git a/docs/source/errors/pauli.rst b/docs/source/errors/pauli.rst index 66c9b93b..524bdca1 100644 --- a/docs/source/errors/pauli.rst +++ b/docs/source/errors/pauli.rst @@ -1,5 +1,5 @@ Pauli error ----------- -.. automodule:: opensurfacesim.errors.pauli +.. automodule:: qsurface.errors.pauli :members: diff --git a/docs/source/errors/template.rst b/docs/source/errors/template.rst index 6bde0b87..a1a7e85c 100644 --- a/docs/source/errors/template.rst +++ b/docs/source/errors/template.rst @@ -1,6 +1,6 @@ Template error -------------- -.. automodule:: opensurfacesim.errors._template +.. automodule:: qsurface.errors._template :member-order: bysource :members: diff --git a/docs/source/index.rst b/docs/source/index.rst index e044a00d..78723d89 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,4 +1,4 @@ -.. opensurfacesim documentation master file, created by +.. qsurface documentation master file, created by sphinx-quickstart on Mon Oct 12 11:56:41 2020. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. diff --git a/docs/source/main.rst b/docs/source/main.rst index 3fd2ccdb..08a5996f 100644 --- a/docs/source/main.rst +++ b/docs/source/main.rst @@ -1,6 +1,6 @@ Running simulations =================== -.. automodule:: opensurfacesim.main +.. automodule:: qsurface.main :members: :member-order: bysource \ No newline at end of file diff --git a/docs/source/others/plot.rst b/docs/source/others/plot.rst index a4bf79ec..430b7511 100644 --- a/docs/source/others/plot.rst +++ b/docs/source/others/plot.rst @@ -34,6 +34,6 @@ Default values for plot properties such as colors and linewidths are saved in a Development ----------- -.. automodule:: opensurfacesim.plot +.. automodule:: qsurface.plot :members: :member-order: bysource \ No newline at end of file diff --git a/docs/source/threshold.rst b/docs/source/threshold.rst index 0836db51..4946301c 100644 --- a/docs/source/threshold.rst +++ b/docs/source/threshold.rst @@ -1,6 +1,6 @@ Running a threshold simulation ============================== -.. automodule:: opensurfacesim.threshold +.. automodule:: qsurface.threshold :members: :member-order: bysource \ No newline at end of file diff --git a/examples.ipynb b/examples.ipynb index 0c9de6a8..22e32b2f 100644 --- a/examples.ipynb +++ b/examples.ipynb @@ -2,9 +2,9 @@ "cells": [ { "source": [ - "# opensurfacesim\n", + "# Qsurface\n", "\n", - "Opensurfacesim is a simulation package for the surface code, and is designed to modularize 3 aspects of a surface code simulation.\n", + "Qsurface is a simulation package for the surface code, and is designed to modularize 3 aspects of a surface code simulation.\n", "\n", "1. The surface code\n", "2. The error model\n", @@ -12,7 +12,7 @@ "\n", "## Examples from the readme.\n", "\n", - "The included examples in this section uses `opensurfacesim.main.initialize` to setup the surface code and decoder, and `opensurfacesim.main.run` to perform simulations. We'll expand these examples with more in-depth descriptions and how to perform a threshold simulation with `opensurfacesim.main.threshold`. \n", + "The included examples in this section uses `qsurface.main.initialize` to setup the surface code and decoder, and `qsurface.main.run` to perform simulations. We'll expand these examples with more in-depth descriptions and how to perform a threshold simulation with `qsurface.main.threshold`. \n", "\n", "To simulate the toric code and simulate with bit-flip error for 10 iterations and decode with the MWPM decoder:" ], @@ -27,7 +27,7 @@ }, "outputs": [], "source": [ - "from opensurfacesim.main import initialize, run, BenchmarkDecoder\n", + "from qsurface.main import initialize, run, BenchmarkDecoder\n", "code, decoder = initialize((6,6), \"toric\", \"mwpm\", enabled_errors=[\"pauli\"])\n", "run(code, decoder, iterations=10, error_rates = {\"p_bitflip\": 0.1})" ] @@ -53,9 +53,9 @@ { "source": [ "\n", - "The figures in opensurfacesim 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", + "The 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", - "The GUI of the figure is made possible by the Tkinter backend. However, for Jupyter notebooks such as this one, the Tkinter GUI is not available. Opensurfacesim automatically detects this and plots each iteration inline instead. If you're running the notebook locally, or have proper X11 forwarding setup, you can still force the Tk inter with the magic `%matplotlib tk` prior to importing opensurfacesim. " + "The GUI of the figure is made possible by the PyQt5 or Tkinter backend. However, for Jupyter notebooks such as this one, the GUI is not available. Qsurface automatically detects this and plots each iteration inline instead. If you're running the notebook locally, or have proper X11 forwarding setup, you can still force the PyQt5 or Tkinter with the magic `%matplotlib qt` or `%matplotlib tk` prior to importing qsurface. " ], "cell_type": "markdown", "metadata": {} @@ -68,6 +68,11 @@ }, "outputs": [], "source": [ + "# When display is available interactive plotting can be enabled by either \n", + "# %matplotlib qt\n", + "# or \n", + "# %matplotlib tk\n", + "from qsurface.main import initialize, run, BenchmarkDecoder\n", "code, decoder = initialize(\n", " (3,3),\n", " \"toric\",\n", @@ -85,7 +90,7 @@ "metadata": {}, "outputs": [], "source": [ - "from opensurfacesim.main import initialize, run, BenchmarkDecoder\n", + "from qsurface.main import initialize, run, BenchmarkDecoder\n", "code, decoder = initialize((3,3), \"toric\", \"mwpm\", enabled_errors=[\"pauli\"], faulty_measurements=True, plotting=True, initial_states=(0,0))\n", "run(code, decoder, error_rates = {\"p_bitflip\": 0.05, \"pm_bitflip\": 0.05}, decode_initial=False)" ] @@ -100,7 +105,7 @@ ], "metadata": { "kernelspec": { - "name": "Python 3.9.0 64-bit ('matplotlib34')", + "name": "python3", "display_name": "Python 3.9.0 64-bit ('matplotlib34')", "metadata": { "interpreter": { diff --git a/manifest.in b/manifest.in index 14f8f020..9c03056a 100644 --- a/manifest.in +++ b/manifest.in @@ -1,3 +1,3 @@ include README.md -include opensurfacesim/decoders/decoders.ini +include qsurface/decoders/decoders.ini include images/ \ No newline at end of file diff --git a/opensurfacesim/__init__.py b/qsurface/__init__.py similarity index 85% rename from opensurfacesim/__init__.py rename to qsurface/__init__.py index 30432722..b4684da1 100644 --- a/opensurfacesim/__init__.py +++ b/qsurface/__init__.py @@ -5,4 +5,4 @@ from . import main from . import threshold -__version__ = "0.1.3" +__version__ = "0.1.4" diff --git a/opensurfacesim/__main__.py b/qsurface/__main__.py similarity index 98% rename from opensurfacesim/__main__.py rename to qsurface/__main__.py index 62c5026f..9ddfb359 100644 --- a/opensurfacesim/__main__.py +++ b/qsurface/__main__.py @@ -1,5 +1,5 @@ -from opensurfacesim.main import BenchmarkDecoder, run, run_multiprocess, initialize -from opensurfacesim.threshold import run_many, ThresholdFit, read_csv +from qsurface.main import BenchmarkDecoder, run, run_multiprocess, initialize +from qsurface.threshold import run_many, ThresholdFit, read_csv from collections import defaultdict import argparse import sys @@ -28,7 +28,7 @@ def _get_kwargs(parsed_args, arg_group): def cli(args): parser = argparse.ArgumentParser( - prog="opensurfacesim", + prog="qsurface", description="Simulation of surface codes. Need more information here", usage="%(prog)s", ) diff --git a/opensurfacesim/codes/__init__.py b/qsurface/codes/__init__.py similarity index 100% rename from opensurfacesim/codes/__init__.py rename to qsurface/codes/__init__.py diff --git a/opensurfacesim/codes/_icons.py b/qsurface/codes/_icons.py similarity index 100% rename from opensurfacesim/codes/_icons.py rename to qsurface/codes/_icons.py diff --git a/opensurfacesim/codes/_template/__init__.py b/qsurface/codes/_template/__init__.py similarity index 100% rename from opensurfacesim/codes/_template/__init__.py rename to qsurface/codes/_template/__init__.py diff --git a/opensurfacesim/codes/_template/plot.py b/qsurface/codes/_template/plot.py similarity index 100% rename from opensurfacesim/codes/_template/plot.py rename to qsurface/codes/_template/plot.py diff --git a/opensurfacesim/codes/_template/sim.py b/qsurface/codes/_template/sim.py similarity index 98% rename from opensurfacesim/codes/_template/sim.py rename to qsurface/codes/_template/sim.py index d5385a23..6c2b470c 100644 --- a/opensurfacesim/codes/_template/sim.py +++ b/qsurface/codes/_template/sim.py @@ -161,7 +161,7 @@ def init_errors(self, *error_modules: Union[str, Error], error_rates: dict = {}, """ for error_module in error_modules: if type(error_module) == str: - error_module = importlib.import_module(".errors.{}".format(error_module), package="opensurfacesim") + error_module = importlib.import_module(".errors.{}".format(error_module), package="qsurface") self._init_error(error_module, error_rates) def _init_error(self, error_module, error_rates): @@ -236,7 +236,7 @@ def entangle_pair( ancilla_qubit Controlled qubit. key - The entanglement is saved by adding the `~.codes.elements.DataQubit` to `~.codes.elements.AncillaQubit`\ ``.parity_qubits[key]`` + The entanglement is saved by adding the `~.codes.elements.DataQubit` to `~.codes.elements.AncillaQubit` ``.parity_qubits[key]`` edge The edge of the data-qubit to entangle to. """ @@ -285,7 +285,7 @@ def _parse_boundary_coordinates(size, *args: float) -> List[float]: class FaultyMeasurements(PerfectMeasurements): """Simulation code class for faulty measurements. - A 3D graph is initiated with ``layers`` amount of 2D surfaces from `~.codes._template.PerfectMeasurement` stacked on top of each other. The structure of the ``self.data_qubits``, ``self.ancilla_qubits`` and ``self.pseudo_qubits`` dictionary attributes allows for the storage for various time instances of the same qubits in the first nested layer. E.g. ``self.data_qubits[0][(0,0)]`` and ``self.data_qubits[1][(0,0)]`` store the data-qubit at (0,0) at time instances 0 and 1, respectively. Consecutive instances of `~.codes.elements.AncillaQubit`\ s and `~.codes.elements.PseudoQubit`\ s are connected in the 3D graph by `~.codes.elements.PseudoEdge` objects. + A 3D graph is initiated with ``layers`` amount of 2D surfaces from `~.codes._template.PerfectMeasurement` stacked on top of each other. The structure of the ``self.data_qubits``, ``self.ancilla_qubits`` and ``self.pseudo_qubits`` dictionary attributes allows for the storage for various time instances of the same qubits in the first nested layer. E.g. ``self.data_qubits[0][(0,0)]`` and ``self.data_qubits[1][(0,0)]`` store the data-qubit at (0,0) at time instances 0 and 1, respectively. Consecutive instances of `~.codes.elements.AncillaQubit` objects and `~.codes.elements.PseudoQubit` objects are connected in the 3D graph by `~.codes.elements.PseudoEdge` objects. Parameters ---------- diff --git a/opensurfacesim/codes/elements.py b/qsurface/codes/elements.py similarity index 100% rename from opensurfacesim/codes/elements.py rename to qsurface/codes/elements.py diff --git a/opensurfacesim/codes/planar/__init__.py b/qsurface/codes/planar/__init__.py similarity index 100% rename from opensurfacesim/codes/planar/__init__.py rename to qsurface/codes/planar/__init__.py diff --git a/opensurfacesim/codes/planar/plot.py b/qsurface/codes/planar/plot.py similarity index 100% rename from opensurfacesim/codes/planar/plot.py rename to qsurface/codes/planar/plot.py diff --git a/opensurfacesim/codes/planar/sim.py b/qsurface/codes/planar/sim.py similarity index 98% rename from opensurfacesim/codes/planar/sim.py rename to qsurface/codes/planar/sim.py index 4b7340ab..650dcea6 100644 --- a/opensurfacesim/codes/planar/sim.py +++ b/qsurface/codes/planar/sim.py @@ -1,4 +1,4 @@ -from opensurfacesim.codes.elements import AncillaQubit +from qsurface.codes.elements import AncillaQubit from ..toric.sim import PerfectMeasurements as ToricPM, FaultyMeasurements as ToricFM diff --git a/opensurfacesim/codes/rotated/__init__.py b/qsurface/codes/rotated/__init__.py similarity index 100% rename from opensurfacesim/codes/rotated/__init__.py rename to qsurface/codes/rotated/__init__.py diff --git a/opensurfacesim/codes/toric/__init__.py b/qsurface/codes/toric/__init__.py similarity index 100% rename from opensurfacesim/codes/toric/__init__.py rename to qsurface/codes/toric/__init__.py diff --git a/opensurfacesim/codes/toric/plot.py b/qsurface/codes/toric/plot.py similarity index 100% rename from opensurfacesim/codes/toric/plot.py rename to qsurface/codes/toric/plot.py diff --git a/opensurfacesim/codes/toric/sim.py b/qsurface/codes/toric/sim.py similarity index 100% rename from opensurfacesim/codes/toric/sim.py rename to qsurface/codes/toric/sim.py diff --git a/opensurfacesim/decoders/__init__.py b/qsurface/decoders/__init__.py similarity index 100% rename from opensurfacesim/decoders/__init__.py rename to qsurface/decoders/__init__.py diff --git a/opensurfacesim/decoders/_template.py b/qsurface/decoders/_template.py similarity index 98% rename from opensurfacesim/decoders/_template.py rename to qsurface/decoders/_template.py index 72e6d330..f5dac9cf 100644 --- a/opensurfacesim/decoders/_template.py +++ b/qsurface/decoders/_template.py @@ -228,7 +228,7 @@ def get_syndrome(self, find_pseudo: bool = False) -> Union[Tuple[LA, LA], Tuple[ Parameters ---------- find_pseudo : bool, optional - If enabled, the lists of syndromes returned are not only `~.codes.elements.AncillaQubit`\ s, but tuples of ``(ancilla, pseudo)``, where ``pseudo`` is the closest `~.codes.elements.PseudoQubit` in the boundary of the code. + If enabled, the lists of syndromes returned are not only `~.codes.elements.AncillaQubit` objects, but tuples of ``(ancilla, pseudo)``, where ``pseudo`` is the closest `~.codes.elements.PseudoQubit` in the boundary of the code. Returns ------- diff --git a/opensurfacesim/decoders/decoders.ini b/qsurface/decoders/decoders.ini similarity index 100% rename from opensurfacesim/decoders/decoders.ini rename to qsurface/decoders/decoders.ini diff --git a/opensurfacesim/decoders/mwpm/__init__.py b/qsurface/decoders/mwpm/__init__.py similarity index 88% rename from opensurfacesim/decoders/mwpm/__init__.py rename to qsurface/decoders/mwpm/__init__.py index 5eae57cf..1631048c 100644 --- a/opensurfacesim/decoders/mwpm/__init__.py +++ b/qsurface/decoders/mwpm/__init__.py @@ -1,7 +1,7 @@ """ The most popular decoder for surface codes is the Minimum-Weight Perfect Matching (MWPM) decoder. It performs near-optimal for a pauli noise model [dennis2002]_ on a standard toric code with a threshold of :math:`p_{\\text{th}} = 10.3\\%`, and for a phenomenological noise model (including faulty measurements) [wang2003]_, which includes faulty measurements, with :math:`p_{\\text{th}} = 2.9\\%`. The main idea is to approximate the error with the minimum-weight error configuration compatible with the syndrome. The minimum-weight configuration is found by constructing a fully connected graph between the nodes of the syndrome, which leads to a cubic worst-case time complexity [kolmogorov2009]_. -The decoder defaults to using a Python implementation of MWPM by `networkx.algorithms.matching.max_weight_matching`. This implementation is however quite slow. Optionally, `Blossom V `_ [kolmogorov2009]_, a C++ algorithm, can be used to increase the speed of the decoder. Since this software has its own license, it is not bundeled with OpenSurfaceSim. A script is provided to download and compile the latest release of BlossomV in `.get_blossomv`. The interface of the C++ code and Python is taken from `Fault Tolerant Simulations `_. +The decoder defaults to using a Python implementation of MWPM by `networkx.algorithms.matching.max_weight_matching`. This implementation is however quite slow. Optionally, `Blossom V `_ [kolmogorov2009]_, a C++ algorithm, can be used to increase the speed of the decoder. Since this software has its own license, it is not bundeled with qsurface. A script is provided to download and compile the latest release of BlossomV in `.get_blossomv`. The interface of the C++ code and Python is taken from `Fault Tolerant Simulations `_. """ @@ -21,7 +21,7 @@ def get_blossomv(accept: bool = False): License: - .. include:: ../../../opensurfacesim/decoders/mwpm/blossom5/LICENSE + .. include:: ../../../qsurface/decoders/mwpm/blossom5/LICENSE :literal: """ diff --git a/opensurfacesim/decoders/mwpm/blossom5/LICENSE b/qsurface/decoders/mwpm/blossom5/LICENSE similarity index 100% rename from opensurfacesim/decoders/mwpm/blossom5/LICENSE rename to qsurface/decoders/mwpm/blossom5/LICENSE diff --git a/opensurfacesim/decoders/mwpm/blossom5/Makefile b/qsurface/decoders/mwpm/blossom5/Makefile similarity index 100% rename from opensurfacesim/decoders/mwpm/blossom5/Makefile rename to qsurface/decoders/mwpm/blossom5/Makefile diff --git a/opensurfacesim/decoders/mwpm/blossom5/pyInterface.cpp b/qsurface/decoders/mwpm/blossom5/pyInterface.cpp similarity index 100% rename from opensurfacesim/decoders/mwpm/blossom5/pyInterface.cpp rename to qsurface/decoders/mwpm/blossom5/pyInterface.cpp diff --git a/opensurfacesim/decoders/mwpm/plot.py b/qsurface/decoders/mwpm/plot.py similarity index 100% rename from opensurfacesim/decoders/mwpm/plot.py rename to qsurface/decoders/mwpm/plot.py diff --git a/opensurfacesim/decoders/mwpm/sim.py b/qsurface/decoders/mwpm/sim.py similarity index 99% rename from opensurfacesim/decoders/mwpm/sim.py rename to qsurface/decoders/mwpm/sim.py index c82e64f0..5516236e 100644 --- a/opensurfacesim/decoders/mwpm/sim.py +++ b/qsurface/decoders/mwpm/sim.py @@ -1,5 +1,5 @@ from typing import List, Tuple -from opensurfacesim.codes.elements import AncillaQubit +from qsurface.codes.elements import AncillaQubit from .._template import Sim import networkx as nx from numpy.ctypeslib import ndpointer diff --git a/opensurfacesim/decoders/ufns/__init__.py b/qsurface/decoders/ufns/__init__.py similarity index 100% rename from opensurfacesim/decoders/ufns/__init__.py rename to qsurface/decoders/ufns/__init__.py diff --git a/opensurfacesim/decoders/ufns/elements.py b/qsurface/decoders/ufns/elements.py similarity index 85% rename from opensurfacesim/decoders/ufns/elements.py rename to qsurface/decoders/ufns/elements.py index fb193ec0..ee6c60da 100644 --- a/opensurfacesim/decoders/ufns/elements.py +++ b/qsurface/decoders/ufns/elements.py @@ -8,9 +8,9 @@ class Node(ABC): """Element in the node-tree. - A subgraph :math:`\mathcal{V}\subseteq C` is a spanning-tree of a cluster :math:`C` if it is a connected acyclic subgraph that includes all vertices of :math:`C` and a minimum number of edges. We call the spanning-tree of a cluster its ancilla-tree. An acyclic connected spanning-forest is required for the Union-Find Decoder. + A subgraph :math:`\\mathcal{V}\\subseteq C` is a spanning-tree of a cluster :math:`C` if it is a connected acyclic subgraph that includes all vertices of :math:`C` and a minimum number of edges. We call the spanning-tree of a cluster its ancilla-tree. An acyclic connected spanning-forest is required for the Union-Find Decoder. - A node-tree :math:`\mathcal{N}` is a partition of a ancilla-tree :math:`\mathcal{V}`, such that each element of the partition -- which we call a *node* :math:`n` -- represents a set of adjacent vertices that lie at the same distance -- the *node radius :math:`r` -- from the *primer ancilla*, which initializes the node and lies at its center. The node-tree is a directed acyclic graph, and its edges :math:`\mathcal{E}_i` have lengths equal to the distance between the primer vertices of neighboring nodes. + A node-tree :math:`\\mathcal{N}` is a partition of a ancilla-tree :math:`\\mathcal{V}`, such that each element of the partition -- which we call a *node* :math:`n` -- represents a set of adjacent vertices that lie at the same distance -- the *node radius :math:`r` -- from the *primer ancilla*, which initializes the node and lies at its center. The node-tree is a directed acyclic graph, and its edges :math:`\\mathcal{E}_i` have lengths equal to the distance between the primer vertices of neighboring nodes. Parameters ---------- @@ -112,7 +112,7 @@ def ns_parity(self, parent_node: Optional[Node] = None) -> int: Tail recursive function that calculates the parities of the current node and all its descendent nodes. - .. math:: s_p = \\big( \\sum_{n \\in \\text{ children of } s} (1+s_p)\ \\big ) \\bmod 2 + .. math:: s_p = \\big( \\sum_{n \\in \\text{ children of } s} (1+s_p) \\big) \\bmod 2 Parameters ---------- diff --git a/opensurfacesim/decoders/ufns/plot.py b/qsurface/decoders/ufns/plot.py similarity index 93% rename from opensurfacesim/decoders/ufns/plot.py rename to qsurface/decoders/ufns/plot.py index b396883f..8199d8ab 100644 --- a/opensurfacesim/decoders/ufns/plot.py +++ b/qsurface/decoders/ufns/plot.py @@ -8,7 +8,7 @@ class Toric(PlotToric, SimToric): Has all class attributes, methods, and nested figure classes from `.ufns.sim.Toric`, with additional parameters below. Default values for these parameters can be supplied via a *decoders.ini* file under the section of ``[ufns]`` (see `.decoders._template.read_config`). - The plotting class initiates a `opensurfacesim.plot` object. For its usage, see :ref:`plot-usage`. + The plotting class initiates a `qsurface.plot` object. For its usage, see :ref:`plot-usage`. Parameters ---------- @@ -46,7 +46,7 @@ class Planar(Toric, PlotPlanar, SimPlanar): Has all class attributes, methods, and nested figure classes from `.ufns.sim.Planar`, with additional parameters below. Default values for these parameters can be supplied via a *decoders.ini* file under the section of ``[ufns]`` (see `.decoders._template.read_config`). - The plotting class initiates a `opensurfacesim.plot` object. For its usage, see :ref:`plot-usage`. + The plotting class initiates a `qsurface.plot` object. For its usage, see :ref:`plot-usage`. Parameters ---------- diff --git a/opensurfacesim/decoders/ufns/sim.py b/qsurface/decoders/ufns/sim.py similarity index 96% rename from opensurfacesim/decoders/ufns/sim.py rename to qsurface/decoders/ufns/sim.py index 54f9e757..9a6ab211 100644 --- a/opensurfacesim/decoders/ufns/sim.py +++ b/qsurface/decoders/ufns/sim.py @@ -10,7 +10,7 @@ class Toric(UFToric): """Union-Find Node-Suspension decoder for the toric lattice. - Within the combined Union-Find and Node-Suspension data structure, every `~.unionfind.elements.Cluster` is partitioned into one or more `~.ufns.elements.Node`\ s. The ``node`` attribute is monkey-patched to the `~.codes.elements.AncillaQubit` object to assist the identification of its parent `~.ufns.elements.Node`. + Within the combined Union-Find and Node-Suspension data structure, every `~.unionfind.elements.Cluster` is partitioned into one or more `~.ufns.elements.Node` objectss. The ``node`` attribute is monkey-patched to the `~.codes.elements.AncillaQubit` object to assist the identification of its parent `~.ufns.elements.Node`. The boundary of every cluster is not stored at the cluster object, but divided under its partitioned nodes. Cluster growth is initiated from the root of the node-tree. The attributes ``root_node`` and ``min_delay`` are monkey-patched to the `~.unionfind.elements.Cluster` object to assist with cluster growth in the Node-Suspension data structure. See `grow_node` for more. @@ -233,9 +233,9 @@ def grow_node(self, cluster: Cluster, node: Node, union_list: UL, parent_node: O Grows the boundary list that is stored at the current node if there the current node is not suspended. The condition required is the following: - .. math: n_{\text{delay}} - n_{\text{waited}} - \min_{x \in \mathcal{N}}{n_{\text{delay}}} = 0 + .. math: n_{\\text{delay}} - n_{\\text{waited}} - \\min_{x \\in \\mathcal{N}}{n_{\\text{delay}}} = 0 - where :math:`\mathcal{N}` is the node-tree. The minimal delay value in the node-tree here stored as ``cluster.min_delay``. Fully grown edges are added to ``union_list`` to be later considered by `union_bucket`. + where :math:`\\mathcal{N}` is the node-tree. The minimal delay value in the node-tree here stored as ``cluster.min_delay``. Fully grown edges are added to ``union_list`` to be later considered by `union_bucket`. Parameters ---------- diff --git a/opensurfacesim/decoders/unionfind/__init__.py b/qsurface/decoders/unionfind/__init__.py similarity index 64% rename from opensurfacesim/decoders/unionfind/__init__.py rename to qsurface/decoders/unionfind/__init__.py index aecfa7cb..7c1e0156 100644 --- a/opensurfacesim/decoders/unionfind/__init__.py +++ b/qsurface/decoders/unionfind/__init__.py @@ -1,7 +1,7 @@ """ -The Union-Find decoder [delfosse2017almost]_ maps each element of the syndrome :math:`\sigma` to an ancilla :math:`v` in a non-connected graph defined on the code lattice. From this starting point, it grows clusters around these ancillas by repeatedly adding a layer of edges and ancillas to existing clusters, until all clusters have an even number of non-trivial syndrome ancillas. Then, it selects a spanning tree :math:`F` for each cluster. +The Union-Find decoder [delfosse2017almost]_ maps each element of the syndrome :math:`\\sigma` to an ancilla :math:`v` in a non-connected graph defined on the code lattice. From this starting point, it grows clusters around these ancillas by repeatedly adding a layer of edges and ancillas to existing clusters, until all clusters have an even number of non-trivial syndrome ancillas. Then, it selects a spanning tree :math:`F` for each cluster. -The leaves of each spanning tree are conditionally peeled in a tail-recursive breadth-first search until all non-trivial syndrome ancillas are paired and linked by a path within :math:`F`, which is the correcting operator :math:`\mathcal{C}` [delfosse2017linear]_. The strategy for constructing the clusters turns out to have a strong effect on performance. For instance, the threshold for bitflip noise of a decoder that grows the clusters following a random order is 9.2% [delfosse2017almost]_, while if the clusters are grown in order of cluster size, which we call **Weighted Growth**, the threshold increases to 9.9% [delfosse2017almost]_. +The leaves of each spanning tree are conditionally peeled in a tail-recursive breadth-first search until all non-trivial syndrome ancillas are paired and linked by a path within :math:`F`, which is the correcting operator :math:`\\mathcal{C}` [delfosse2017linear]_. The strategy for constructing the clusters turns out to have a strong effect on performance. For instance, the threshold for bitflip noise of a decoder that grows the clusters following a random order is 9.2% [delfosse2017almost]_, while if the clusters are grown in order of cluster size, which we call **Weighted Growth**, the threshold increases to 9.9% [delfosse2017almost]_. The complexity of the Union-Find decoder is driven by the merging of the clusters. For this, the algorithm uses the Union-Find or disjoint-set data structure [tarjan1975efficiency]_. This data structure contains a set of elements, in this case ancillas on the lattice. The set of elements is represented by a two-level tree. At the root of the tree sits one element chosen arbitrarily; the rest of the elements are linked to the root element. The structure admits two functions: :math:`Find` and :math:`Union`. Given :math:`v` an element from the structure, the function :math:`Find(v)` returns the root element of the tree. This is is used to identify the cluster to which :math:`v` belongs. The second function is :math:`Union(u, v)`, this function merges the sets associated with elements :math:`u` and :math:`v`. This requires pointing all the elements of one of the sets to the root of the other. In order to minimize the number of operations the root of the set with the larger number of elements is chosen as root for the merged set, this is called **Weighted Union**. In this context, :math:`Union` is used when the growth of a cluster requires adding a vertex that belongs to another. """ diff --git a/opensurfacesim/decoders/unionfind/elements.py b/qsurface/decoders/unionfind/elements.py similarity index 100% rename from opensurfacesim/decoders/unionfind/elements.py rename to qsurface/decoders/unionfind/elements.py diff --git a/opensurfacesim/decoders/unionfind/plot.py b/qsurface/decoders/unionfind/plot.py similarity index 98% rename from opensurfacesim/decoders/unionfind/plot.py rename to qsurface/decoders/unionfind/plot.py index 8e65b47c..02e4524f 100644 --- a/opensurfacesim/decoders/unionfind/plot.py +++ b/qsurface/decoders/unionfind/plot.py @@ -11,7 +11,7 @@ class Toric(SimToric, Plot): Has all class attributes and methods from `.unionfind.sim.Toric`, with additional parameters below. Default values for these parameters can be supplied via a *decoders.ini* file under the section of ``[unionfind]`` (see `.decoders._template.read_config`). - The plotting class initiates a `opensurfacesim.plot` object. For its usage, see :ref:`plot-usage`. + The plotting class initiates a `qsurface.plot` object. For its usage, see :ref:`plot-usage`. Parameters ---------- @@ -329,7 +329,7 @@ class Planar(Toric, SimPlanar): Has all class attributes and methods from `.unionfind.sim.Planar`, with additional parameters below. Default values for these parameters can be supplied via a *decoders.ini* file under the section of ``[unionfind]`` (see `.decoders._template.read_config`). - The plotting class initiates a `opensurfacesim.plot` object. For its usage, see :ref:`plot-usage`. + The plotting class initiates a `qsurface.plot` object. For its usage, see :ref:`plot-usage`. Parameters ---------- diff --git a/opensurfacesim/decoders/unionfind/sim.py b/qsurface/decoders/unionfind/sim.py similarity index 99% rename from opensurfacesim/decoders/unionfind/sim.py rename to qsurface/decoders/unionfind/sim.py index 0f490c4c..445c5496 100644 --- a/opensurfacesim/decoders/unionfind/sim.py +++ b/qsurface/decoders/unionfind/sim.py @@ -344,7 +344,7 @@ def grow_boundary(self, cluster: Cluster, union_list: List[Tuple[AncillaQubit, E def union_bucket(self, union_list: List[Tuple[AncillaQubit, Edge, AncillaQubit]], **kwargs): """Merges clusters in ``union_list`` if checks are passed. - Items in ``union_list`` consists of ``[ancillaA, edge, ancillaB]`` of two ancillas that, at the time added to the list, were not part of the same cluster. The cluster of an ancilla is stored at ``ancilla.cluster``, but due to cluster mergers the cluster at ``ancilla_cluster`` may not be the root element in the cluster-tree, and thus the cluster must be requested by ``ancilla.cluster.``\ `~.unionfind.elements.Cluster.find`. Since the clusters of ``ancillaA`` and ``ancillaB`` may have already merged, checks are performed in `union_check` after which the clusters are conditionally merged on ``edge`` by `union_edge`. + Items in ``union_list`` consists of ``[ancillaA, edge, ancillaB]`` of two ancillas that, at the time added to the list, were not part of the same cluster. The cluster of an ancilla is stored at ``ancilla.cluster``, but due to cluster mergers the cluster at ``ancilla_cluster`` may not be the root element in the cluster-tree, and thus the cluster must be requested by ``ancilla.cluster.`` `~.unionfind.elements.Cluster.find`. Since the clusters of ``ancillaA`` and ``ancillaB`` may have already merged, checks are performed in `union_check` after which the clusters are conditionally merged on ``edge`` by `union_edge`. If ``weighted_union`` is enabled, the smaller cluster is always made a child of the bigger cluster in the cluster-tree. This ensures the that the depth of the tree is minimized and the future calls to `~.unionfind.elements.Cluster.find` is reduced. diff --git a/opensurfacesim/errors/__init__.py b/qsurface/errors/__init__.py similarity index 100% rename from opensurfacesim/errors/__init__.py rename to qsurface/errors/__init__.py diff --git a/opensurfacesim/errors/_icons.py b/qsurface/errors/_icons.py similarity index 100% rename from opensurfacesim/errors/_icons.py rename to qsurface/errors/_icons.py diff --git a/opensurfacesim/errors/_template.py b/qsurface/errors/_template.py similarity index 100% rename from opensurfacesim/errors/_template.py rename to qsurface/errors/_template.py diff --git a/opensurfacesim/errors/erasure.py b/qsurface/errors/erasure.py similarity index 100% rename from opensurfacesim/errors/erasure.py rename to qsurface/errors/erasure.py diff --git a/opensurfacesim/errors/pauli.py b/qsurface/errors/pauli.py similarity index 100% rename from opensurfacesim/errors/pauli.py rename to qsurface/errors/pauli.py diff --git a/opensurfacesim/main.py b/qsurface/main.py similarity index 98% rename from opensurfacesim/main.py rename to qsurface/main.py index 26fe5d29..349aa8d6 100644 --- a/opensurfacesim/main.py +++ b/qsurface/main.py @@ -119,7 +119,7 @@ def run( iterations Number of iterations to run. error_rates - Dictionary of error rates (see `~opensurfacesim.errors`). Errors must have been loaded during code class initialization by `~.codes._template.sim.PerfectMeasurements.initialize` or `~.codes._template.sim.PerfectMeasurements.init_errors`. + Dictionary of error rates (see `~qsurface.errors`). Errors must have been loaded during code class initialization by `~.codes._template.sim.PerfectMeasurements.initialize` or `~.codes._template.sim.PerfectMeasurements.init_errors`. decode_initial Decode initial code configuration before applying loaded errors. If random states are used for the data-qubits of the ``code`` at class initialization (default behavior), an initial round of decoding is required and is enabled through the ``decode_initial`` flag (default is enabled). seed @@ -220,7 +220,7 @@ def run_multiprocess( decoder A decoder instance (see initialize). error_rates - Dictionary for error rates (see `~opensurfacesim.errors`). + Dictionary for error rates (see `~qsurface.errors`). iterations Total number of iterations to run. decode_initial diff --git a/opensurfacesim/plot.py b/qsurface/plot.py similarity index 100% rename from opensurfacesim/plot.py rename to qsurface/plot.py diff --git a/opensurfacesim/threshold.py b/qsurface/threshold.py similarity index 99% rename from opensurfacesim/threshold.py rename to qsurface/threshold.py index 9aa9793e..2ac5734a 100644 --- a/opensurfacesim/threshold.py +++ b/qsurface/threshold.py @@ -52,7 +52,7 @@ def run_many( enabled_errors List of error modules from `.errors`. error_rates - List of dictionaries for error rates per configuration (see `~opensurfacesim.errors`). + List of dictionaries for error rates per configuration (see `~qsurface.errors`). faulty_measurements Enable faulty measurements (decode in a 3D lattice). methods_to_benchmark diff --git a/setup.py b/setup.py index 43a0e688..cb425b63 100644 --- a/setup.py +++ b/setup.py @@ -8,13 +8,13 @@ setup( - name="opensurfacesim", - version="0.1.3", + name="qsurface", + version="0.1.4", description="Open library from surface code simulations and visualizations", long_description=README, long_description_content_type="text/markdown", - url="https://github.com/watermarkhu/opensurfacesim", - project_urls={"Documentation": "https://opensurfacesim.readthedocs.io/en/latest/"}, + url="https://github.com/watermarkhu/qsurface", + project_urls={"Documentation": "https://qsurface.readthedocs.io/en/latest/"}, author="Mark Shui Hu", author_email="watermarkhu@gmail.com", license="BSD-3", @@ -36,8 +36,8 @@ ], entry_points={ "console_scrips": [ - "py-opensurfacesim=opensurfacesim.__main__:main", - "opensurfacesim-getblossomv=opensurfacesim.decoders.mwpm:get_blossomv", + "qsurface=qsurface.__main__:main", + "qsurface-getblossomv=qsurface.decoders.mwpm:get_blossomv", ], }, ) diff --git a/tests/test_cli.py b/tests/test_cli.py index b60ee677..8f1ab734 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -1,4 +1,4 @@ -from opensurfacesim.__main__ import cli +from qsurface.__main__ import cli import pytest from .variables import * diff --git a/tests/test_code.py b/tests/test_code.py index d2e138be..dc9fc224 100644 --- a/tests/test_code.py +++ b/tests/test_code.py @@ -1,4 +1,4 @@ -from opensurfacesim import codes +from qsurface import codes import pytest from .variables import * diff --git a/tests/test_main.py b/tests/test_main.py index 571be6e8..ea6bf4bc 100644 --- a/tests/test_main.py +++ b/tests/test_main.py @@ -1,4 +1,4 @@ -from opensurfacesim.main import * +from qsurface.main import * import pytest from .variables import * diff --git a/tests/test_mplbackends.py b/tests/test_mplbackends.py index da0596cd..36884f38 100644 --- a/tests/test_mplbackends.py +++ b/tests/test_mplbackends.py @@ -1,4 +1,4 @@ -from opensurfacesim.main import * +from qsurface.main import * import matplotlib as mpl import pytest from .variables import * diff --git a/tests/test_mwpm.py b/tests/test_mwpm.py index 2d38975f..c6cebeef 100644 --- a/tests/test_mwpm.py +++ b/tests/test_mwpm.py @@ -1,5 +1,5 @@ -from opensurfacesim.main import * -import opensurfacesim as oss +from qsurface.main import * +import qsurface as oss import pytest import random from .variables import * diff --git a/tests/test_threshold.py b/tests/test_threshold.py index abe636a1..57dfcf32 100644 --- a/tests/test_threshold.py +++ b/tests/test_threshold.py @@ -1,5 +1,5 @@ -from opensurfacesim.threshold import * -import opensurfacesim as oss +from qsurface.threshold import * +import qsurface as oss import pytest import pandas as pd import matplotlib.pyplot as plt diff --git a/tests/test_ufns.py b/tests/test_ufns.py index 9c87b4f3..c2617563 100644 --- a/tests/test_ufns.py +++ b/tests/test_ufns.py @@ -1,5 +1,5 @@ -from opensurfacesim.main import * -import opensurfacesim as oss +from qsurface.main import * +import qsurface as oss import matplotlib as mpl import pytest import random diff --git a/tests/test_unionfind.py b/tests/test_unionfind.py index 8ae8658a..4f203dc8 100644 --- a/tests/test_unionfind.py +++ b/tests/test_unionfind.py @@ -1,5 +1,5 @@ -from opensurfacesim.main import * -import opensurfacesim as oss +from qsurface.main import * +import qsurface as oss import pytest import random from .variables import * diff --git a/tests/variables.py b/tests/variables.py index 50d5919a..324a81b2 100644 --- a/tests/variables.py +++ b/tests/variables.py @@ -1,5 +1,5 @@ -import opensurfacesim as oss -from opensurfacesim.codes.toric.sim import PerfectMeasurements as toric_code +import qsurface as oss +from qsurface.codes.toric.sim import PerfectMeasurements as toric_code import itertools CODES = oss.codes.CODES