Introduction

[Error] we're working on the documentation of this project, please wait for a formal release (1.0.0) before you want to use this project.

TODO: add citations to all concepts

QEC-Playground is a command line tool and library to explore quantum error correction, primarily surface code. It integrates the whole workflow from simulating surface code to decoding the syndrome and validating the decoding results. Every component in this workflow can be customized independently, so that user can explore different codes or decoders with minimum effort.

On top of this library, we provide a Python binding so that you don't have to learn Rust programming language while enjoying the speed gain of Rust. You can implement your own surface code, noise model or decoder in Python, while letting other components to run at full speed in Rust.

• Simulator
  • generates random qubit errors and simulates the measurement outcome (syndrome), given the Clifford gate implementation of a surface code
  • Code Builder
    • builds the Clifford gate implementation of a supported surface code, given a few parameters like code distances and how many rounds of measurements
    • TODO: Python: full customization supported
• Noise Model
  • describes the error distribution, supporting single-qubit and two-qubit correlated Pauli errors and erasure errors
  • Noise Model Builder
    • builds a supported noise model, given customized parameters like initialization error rate, measurement error rate, noise bias, etc.
    • TODO: Python: full customization supported
• Decoder
  • computes the correction pattern that tries to minimize the logical error rate of the logical qubit encoded in this surface code, given a measurement result
  • TODO: Python: full customization supported
  • Model Graph
    • automatically builds the model graph from the Clifford gate implementation of any surface code for graph-based decoders, e.g. MWPM decoder and UF decoder
    • TODO: Python: manually change the model graph
    • Complete Mode Graph
      • computes the complete model graph out of the model graph either offline (precompute the complete graph, memory-demanding) or online (compute edges on the fly, CPU-demanding)
      • TODO: Python: manually change the complete model graph in the offline mode
  • Erasure Graph
    • automatically builds the erasure graph from the Clifford gate implementation of any surface code for graph-based decoders, e.g. MWPM decoder and UF decoder

Contributing

QEC-Playground is free and open source. You can find the source code on Github, where you can post issues and feature requests using Github issue tracker. Currently the project is maintained by Yue Wu at Yale Efficient Computing Lab. If you'd like to contribute to the project, consider emailing the maintainer or opening a pull request.

License

The QEC-Playground source and documentation are released under the MIT License.

Installation

There are multiple ways to install this library. Choose any one of the methods below that best suit your needs.

Pre-compiled Binaries

TODO: upload the binary and alert the limitation of Blossom V library license issue

Build from Source using Rust

This is the recommended way to install the library for two reasons. First, the pre-compiled binary doesn't include the Blossom V library due to incompatible license, and thus is not capable of running any decoder that based on Minimum-Weight Perfect Matching (MWPM) algorithm. Second, you can access all the examples as well as the simulation scripts and data in our published papers only from the source code repository.

Download the Blossom V Library [Optional]

In order to use the MWPM algorithm (e.g. in the MWPM decoder or the tailored-SC decoder), you need to download the Blossom V [kolmogorov2009blossom] library from https://pub.ist.ac.at/~vnk/software.html into the folder backend/blossomV. You're responsible for requesting a proper license for the use of this library, as well as obeying any requirement.

An example of downloading the Blossom V library is below. Note that the latest version number and website address may change over time.

wget -c https://pub.ist.ac.at/~vnk/software/blossom5-v2.05.src.tar.gz -O - | tar -xz
cp -r blossom5-v2.05.src/* backend/blossomV/
rm -r blossom5-v2.05.src

You don't need to compile the Blossom V library manually.

Note that you can still compile the project without the Blossom V library. The build script automatically detects whether the Blossom V library exists and enables the feature accordingly.

Install the Python Dependencies [Optional]

To enable the binding between Rust and Python, install the following packages

sudo apt install python3 python3-pip
pip3 install networkx

Install the Rust Toolchain

We need the Rust toolchain to compile the project written in the Rust programming language. Please see https://rustup.rs/ for the latest instructions. An example on Unix-like operating systems is below.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.bashrc  # this will add `~/.cargo/bin` to path

After installing the Rust toolchain successfully, you can compile the backend by

cd backend/rust/
cargo build --release

Install Frontend tools [Optional]

TODO: We plan to remove the dependency of Node.js for building the frontend, by rewriting the tutorials and visualization pages as single-page Vue applications.

The code is already running at https://wuyue98.cn/QECPlayground/, but if you're interested in building them on yourself, follow this guide.

We use Vue.js to implement code and use npm package manager to build code. Download and install npm from https://nodejs.org/en/download/ first, then install vue CLI

npm install -g @vue/cli
vue --version  # check whether installation is successful
vue ui  # this will start a web page
# select the folder of /frontend which contains the Vue project
# then you can use GUI in browser to build the code

Or you can use command line to build the frontend project

cd frontend
npm install
npm run build  # build code into dist/ folder
npm run serve  # fast debugging, hot re-compile

Install mdbook to build the documentation

In order to build this documentation, you need to install mdbook and several plugins.

cargo install mdbook
cargo install mdbook-bib
cd documentation
mdbook serve  # dev mode, automatically refresh the local web page on code change
mdbook build  # build deployment in /docs folder, to be recognized by GitHub Pages

Bibliography