plaquette-unionfind 0.0.1a2

Description:

plaquetteunionfind 0.0.1a2

Table of Contents

About
Installation
Usage

Python Frontend
C++ Backend
Interface to Plaquette


Benchmarks
Documentation



About
The Plaquette-UnionFind plugin
extends the Plaquette error correction
software, providing a fast unionfind decoder written in C++. See the Benchmarks
section for a comparison to other known decoding packages.


Installation
The basic dependencies for installation are cmake and ninja.
The C++ tests/examples and python bindings can be built independently by
cmake -Bbuild -G Ninja -DPLAQUETTE_UNIONFIND_BUILD_TESTS=On -DPLAQUETTE_UNIONFIND_BUILD_BINDINGS=On
cmake --build ./build
You can run the C++ backend tests with
make test-cpp
You can install just the python interface with (this quietly builds the C++ backend):
pip install -r requirements.txt
pip install .
or get the latest stable release from PyPI
pip install plaquette_unionfind
You can run the python frontend tests with
make test-python


Usage

Python Frontend
import plaquette_unionfind as puf
import plaquette_graph as pg

vertex_boundary = [False] * 12 + [True] * 8
edges = [(0, 12), (0, 1), (1, 2), (2, 13), (0, 3), (1, 4), (2, 5), (3, 14), (3, 4),
(4, 5), (5, 15), (3, 6), (4, 7), (5, 8), (6, 16), (6, 7), (7, 8), (8, 17),
(6, 9), (7, 10), (8, 11), (9, 18), (9, 10), (10, 11), (11, 19)]
syndrome = [False, False, True, True, False, True, True, False, True, False, True,
False, False, False, False, False, False, False, False, False]
dg = pg.DecodingGraph(num_vertices, edges, vertex_boundary)
uf = puf.UnionFindDecoder(dg)
correction = uf.decode(syndrome)


C++ Backend
#include "DecodingGraph.hpp"
#include "UnionFindDecoder.hpp"

int main(int argc, char *argv[]) {

using namespace Plaquette;
//a vector storing a flag that is 1 if the vertex is on the boundary
std::vector<bool> vertex_boundary = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 1, 1, 1, 1, 1, 1, 1, 1};
std::vector<std::pair<size_t, size_t>> edges = {
{0, 12}, {0, 1}, {1, 2}, {2, 13}, {0, 3}, {1, 4}, {2, 5},
{3, 14}, {3, 4}, {4, 5}, {5, 15}, {3, 6}, {4, 7}, {5, 8},
{6, 16}, {6, 7}, {7, 8}, {8, 17}, {6, 9}, {7, 10}, {8, 11},
{9, 18}, {9, 10}, {10, 11}, {11, 19}};

std::vector<bool> syndrome = {false, false, true, true, false, true, true,
false, true, false, true, false, false, false,
false, false, false, false, false, false};

auto decoding_graph = DecodingGraph(vertex_boundary.size(),
edges, vertex_boundary);
UnionFindDecoder decoder(decoding_graph);
auto correction = decoder.Decode(syndrome);
}


Interface to Plaquette
Plaquette is undergoing heavy development, so this interface is likely to change. If you are benchmarking
our decoder, please do not use the plaquette interface unless you know what you are doing. You will be timing other computations unrelated to the decoding.
from plaquette.codes import LatticeCode
import plaquette_unionfind

code = LatticeCode.make_planar(n_rounds=1, size=size)
qed = {
"pauli": {q.equbit_idx: {"x": error_rate} for q in code.lattice.dataqubits}
}
decoder = plaquette_unionfind.UnionFindDecoderInterface.from_code(code, qed, weighted=False)



Benchmarks
We benchmark plaquette-unionfind along with two of the leading open source decorders PyMatching-v2
and FusionBlosson.
For our benchmarks, we have been careful to only time the intrinsic PyMatching and FusionBlossom decoding
functions. Only the intrinsic speed of the decoder was timed, so e.g., we do not yet benchmark along with
the decode_batch function for Pymatching-v2. We also set FusionBlossom to single-threaded mode for a fair
comparison with PyMatching and plaquette-unionfind. All benchmarks are performed on a m6id.4xlarge AWS node.
All benchmarks are reproducible (see below) using our scripts on a m6id.4xlarge.
For our first benchmark, we use the 2-D (perfect measurement) Planar Code with p = 0.05 depolarization
error. We observe up to 8-10x speedup over PyMatching and FusionBlossom.

For our second benchmark we use the 3-D Rotated Planar Code to account for measurement errors, with p = 0.01 depolarization
error and p = 0.01 measurement error. We observe that Pymatching is more sensitive to the lattice size than the other decoders.

Finally we benchmark a 30x30 Rotated Planar Code (29 rounds of measurement) with varying probability. We observe that
FusionBlossom is sensitive to the error probability.

To run all three benchmarks, use the following bash commands:
source benchmarks/run_perfect_planar_benchmark.sh 0.05
source benchmarks/run_imperfect_rotated_planar_benchmark.sh 0.01
source benchmarks/run_imperfect_rotated_planar_fixed_size_benchmark.sh

python plot_benchmark_1.py perfect_planar_0.05.dat perfect_planar_0.05.png "Surface Code Benchmark #1" 5
python plot_benchmark_2.py imperfect_rotated_planar_0.01.dat imperfect_rotated_planar_0.01.png "Surface Code Benchmark #2" 5
python plot_benchmark_3.py imperfect_rotated_planar_fixed_size.dat imperfect_rotated_planar_fixed_size.png "Surface Code Benchmark #3" 1


Documentation
To generate the documentation you will need to install graphviz and doxygen. Then run
pip install -r doc/requirements.txt
make docs
firefox ./doc/_build/html/index.html
Here is a live link to the documentation: https://docs.plaquette.design/projects/unionfind