provide interfaces to numerous ECC decoders as well as ECC evaluation pipelines

.buildkite/pipeline.yml

@@ -1,6 +1,8 @@
 env:
   CODECOV_TOKEN: adb3f22a-231a-4f7b-8ed4-7c6c56453cbe
   JULIA_NUM_THREADS: auto
+  PYTHON: ""
+  PYCALL_DEBUG_BUILD: yes
 
 steps:
   - label: "CI Buildkite"
@@ -11,12 +13,12 @@ steps:
       - JuliaCI/julia-test#v1: ~
       - JuliaCI/julia-coverage#v1:
           codecov: true
-    command: |
-      julia -e '
-        using Pkg
-        Pkg.add("QuantumSavory")
-        Pkg.build("QuantumSavory")
-        Pkg.test("QuantumSavory")
-        Pkg.add("BPGates")
-        Pkg.build("BPGates")
-        Pkg.test("BPGates")'
+#    command: |
+#      julia -e '
+#        using Pkg
+#        Pkg.add("QuantumSavory")
+#        Pkg.build("QuantumSavory")
+#        Pkg.test("QuantumSavory")
+#        Pkg.add("BPGates")
+#        Pkg.build("BPGates")
+#        Pkg.test("BPGates")'

.github/workflows/benchmark.yml

@@ -2,6 +2,9 @@ name: Performance tracking
 on:
   pull_request:
 
+env:
+  PYTHON: ~
+
 jobs:
   performance-tracking:
     runs-on: ubuntu-latest

.github/workflows/ci-julia-nightly.yml

@@ -4,6 +4,8 @@ on:
     branches: [master, main]
     tags: ["*"]
   pull_request:
+env:
+  PYTHON: ~
 jobs:
   test:
     name: Julia ${{ matrix.version }} - t=${{ matrix.threads }} - jet=${{ matrix.jet }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}

.github/workflows/ci.yml

@@ -4,6 +4,8 @@ on:
     branches: [master, main]
     tags: ["*"]
   pull_request:
+env:
+  PYTHON: ~
 jobs:
   test:
     name: Julia ${{ matrix.version }} - t=${{ matrix.threads }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}

.github/workflows/downgrade.yml

@@ -8,6 +8,8 @@ on:
     branches: [master, main]
     paths-ignore:
       - 'docs/**'
+env:
+  PYTHON: ~
 jobs:
   test:
     runs-on: ubuntu-latest

.gitignore

@@ -3,4 +3,5 @@ Manifest.toml
 LocalPreferences.toml
 */.*swp
 scratch/
-*.cov
+*.cov
+.vscode

CHANGELOG.md

@@ -6,6 +6,10 @@
 
 # News
 
+## v0.8.20 - 2024-01-22
+
+- Significant additions to the `ECC` submodule, with constructors for a few new codes (`Toric` and  generic `CSS`); incorporating many syndrome decoding algorithms (thanks to the `PyQDecoders.jl` and `LDPCDecoders.jl` packages); and providing a convenient API for evaluating code performance in different settings through the new `evaluate_decoder` function.
+
 ## v0.8.19 - 2023-12-16
 
 - Bumping up the lower bounds of many dependencies and adding lower-bound compatibility checks to CI.

Project.toml

@@ -1,7 +1,7 @@
 name = "QuantumClifford"
 uuid = "0525e862-1e90-11e9-3e4d-1b39d7109de1"
 authors = ["Stefan Krastanov <[email protected]>"]
-version = "0.8.19"
+version = "0.8.20"
 
 [deps]
 Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
@@ -18,12 +18,16 @@ PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
 QuantumInterface = "5717a53b-5d69-4fa3-b976-0bf2f97ca1e5"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SIMD = "fdea26ae-647d-5447-a871-4b548cad5224"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 SumTypes = "8e1ec7a9-0e02-4297-b0fe-6433085c89f2"
 
 [weakdeps]
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
+LDPCDecoders = "3c486d74-64b9-4c60-8b1a-13a564e77efb"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+PyQDecoders = "17f5de1a-9b79-4409-a58d-4d45812840f7"
 Quantikz = "b0d11df0-eea3-4d79-b4a5-421488cbf74b"
 QuantumOpticsBase = "4f57444f-1401-5e15-980d-4471b28d5678"
 
@@ -33,6 +37,8 @@ QuantumCliffordMakieExt = "Makie"
 QuantumCliffordPlotsExt = "Plots"
 QuantumCliffordQOpticsExt = "QuantumOpticsBase"
 QuantumCliffordQuantikzExt = "Quantikz"
+QuantumCliffordLDPCDecodersExt = "LDPCDecoders"
+QuantumCliffordPyQDecodersExt = "PyQDecoders"
 
 [compat]
 CUDA = "4.4.0"
@@ -42,17 +48,21 @@ DocStringExtensions = "0.9"
 Graphs = "1.9"
 HostCPUFeatures = "0.1.6"
 ILog2 = "0.2.3"
-InteractiveUtils = "1"
-LinearAlgebra = "1"
+InteractiveUtils = "1.9"
+LDPCDecoders = "0.1.1"
+LinearAlgebra = "1.9"
 MacroTools = "0.5.9"
 Makie = "0.20"
 Nemo = "0.38"
 Plots = "1.38.0"
 PrecompileTools = "1.2"
+PyQDecoders = "0.1.1"
 Quantikz = "1.3.1"
 QuantumInterface = "0.3.3"
 QuantumOpticsBase = "0.4.18"
-Random = "1"
+Random = "1.9"
 SIMD = "3.4.0"
+SparseArrays = "1.9"
+Statistics = "1.9"
 SumTypes = "0.5"
 julia = "1.9"

benchmark/Project.toml

@@ -1,5 +1,7 @@
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+LDPCDecoders = "3c486d74-64b9-4c60-8b1a-13a564e77efb"
 Nemo = "2edaba10-b0f1-5616-af89-8c11ac63239a"
+PyQDecoders = "17f5de1a-9b79-4409-a58d-4d45812840f7"
 QuantumClifford = "0525e862-1e90-11e9-3e4d-1b39d7109de1"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"

benchmark/benchmarks.jl

@@ -139,3 +139,22 @@ SUITE["circuitsim"]["mctrajectories_sumtype"]["q101_r1"]    = @benchmarkable mct
 SUITE["circuitsim"]["mctrajectories_sumtype"]["q1001_r1"]   = @benchmarkable mctrajectory!(state, circuit) setup=(state=Register(one(Stabilizer, 1001), [false]); circuit=compactify_circuit(x_diag_circuit(1000))) evals=1
 
 end
+
+
+if V >= v"0.8.20"
+
+using QuantumClifford.ECC
+
+SUITE["ecc"] = BenchmarkGroup(["ecc"])
+SUITE["ecc"]["evaluate_decoder"] = BenchmarkGroup(["evaluate_decoder"])
+for (cs, c) in [("shor",Shor9()), ("toric8",Toric(8,8))]
+    for (ds, d) in [
+        [("table",TableDecoder(c)), ("bp",BeliefPropDecoder(c)), ("pybp",PyBeliefPropDecoder(c))]...,
+        (isa(c,Toric) ? [("pymatch",PyMatchingDecoder(c))] : [])...]
+        for (ss, s) in [("comm",CommutationCheckECCSetup(0.01)), ("naivesyn",NaiveSyndromeECCSetup(0.01,0)), ("shorsyn",ShorSyndromeECCSetup(0.01,0))]
+            SUITE["ecc"]["evaluate_decoder"]["$(cs)_$(ds)_$(ss)"] = @benchmark evaluate_decoder($d, $s, 1000)
+        end
+    end
+end
+
+end

docs/Project.toml

@@ -5,8 +5,10 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
+LDPCDecoders = "3c486d74-64b9-4c60-8b1a-13a564e77efb"
 Nemo = "2edaba10-b0f1-5616-af89-8c11ac63239a"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+PyQDecoders = "17f5de1a-9b79-4409-a58d-4d45812840f7"
 Quantikz = "b0d11df0-eea3-4d79-b4a5-421488cbf74b"
 QuantumClifford = "0525e862-1e90-11e9-3e4d-1b39d7109de1"
 QuantumInterface = "5717a53b-5d69-4fa3-b976-0bf2f97ca1e5"

docs/make.jl

@@ -20,7 +20,7 @@ doctest = false,
 clean = true,
 sitename = "QuantumClifford.jl",
 format = Documenter.HTML(size_threshold_ignore = ["API.md"]),
-modules = [QuantumClifford, QuantumClifford.Experimental.NoisyCircuits, QuantumInterface],
+modules = [QuantumClifford, QuantumClifford.Experimental.NoisyCircuits, QuantumClifford.ECC, QuantumInterface],
 warnonly = [:missing_docs],
 authors = "Stefan Krastanov",
 pages = [
@@ -41,6 +41,10 @@ pages = [
     "Circuit Operations" => "noisycircuits_ops.md",
     "API" => "noisycircuits_API.md"
 ],
+"ECC compendium" => [
+    "Evaluating codes and decoders" => "ECC_evaluating.md"
+    "API" => "ECC_API.md"
+],
 "All Gates" => "allops.md",
 "Visualizations" => "plotting.md",
 "API" => "API.md",

docs/src/ECC_API.md

@@ -0,0 +1,6 @@
+# Full ECC API (autogenerated)
+
+```@autodocs
+Modules = [QuantumClifford.ECC]
+Private = false
+```

docs/src/ECC_evaluating.md

@@ -0,0 +1,86 @@
+# [Evaluating an ECC code and decoders](@id ecc_evaluating)
+
+```@meta
+DocTestSetup = quote
+    using QuantumClifford
+    using QuantumClifford.ECC
+end
+CurrentModule = QuantumClifford.ECC
+```
+
+!!! warning "The documentation is incomplete"
+    While waiting for a better documentation than the small example below, consider looking into [`evaluate_decoder`](@ref), [`TableDecoder`](@ref), [`BeliefPropDecoder`](@ref), [`PyBeliefPropDecoder`](@ref), [`PyMatchingDecoder`](@ref), [`CommutationCheckECCSetup`](@ref), [`NaiveSyndromeECCSetup`](@ref), [`ShorSyndromeECCSetup`](@ref)
+
+This is a quick and durty example on how to use some of the decoders.
+
+A function to plot the results of 
+
+```@example decoderexample
+using CairoMakie
+
+function make_decoder_figure(phys_errors, results, title="")
+    minlim = min(minimum(phys_errors),minimum(results[results.!=0]))
+    maxlim = min(1, max(maximum(phys_errors),maximum(results[results.!=0])))
+
+    fresults = copy(results)
+    fresults[results.==0] .= NaN
+
+    f = Figure()
+    a = Axis(f[1,1],
+        xscale=log10, yscale=log10,
+        limits=(minlim,maxlim,minlim,maxlim),
+        aspect=DataAspect(),
+        xlabel="physical error rate",
+        ylabel="logical error rate",
+        title=title)
+    lines!(a, [minlim,maxlim],[minlim,maxlim], color=:black)
+    for (i,sresults) in enumerate(eachslice(fresults, dims=1))
+        scatter!(a, phys_errors, sresults[:,1], marker=:+, color=Cycled(i))
+        scatter!(a, phys_errors, sresults[:,2], marker=:x, color=Cycled(i))
+    end
+    f
+end
+```
+
+Testing out a lookup table decoder on a small code.
+
+```@example decoderexample
+using QuantumClifford
+using QuantumClifford.ECC
+
+mem_errors = 0.001:0.0005:0.01
+codes = [Shor9()]
+results = zeros(length(codes), length(mem_errors), 2)
+
+for (ic, c) in pairs(codes)
+    for (i,m) in pairs(mem_errors)
+        setup = CommutationCheckECCSetup(m)
+        decoder = TableDecoder(c)
+        r = evaluate_decoder(decoder, setup, 10000)
+        results[ic,i,:] .= r
+    end
+end
+
+make_decoder_figure(mem_errors, results, "Shor's code with a lookup table decoder")
+```
+
+Testing out the toric code with a decoder provided by the python package `pymatching` (provided in julia by the meta package `PyQDecoders.jl`).
+
+```@example decoderexample
+import PyQDecoders
+
+mem_errors = 0.001:0.005:0.1
+codes = [Toric(4,4), Toric(6,6)]
+results = zeros(length(codes), length(mem_errors), 2)
+
+for (ic, c) in pairs(codes)
+    for (i,m) in pairs(mem_errors)
+        setup = ShorSyndromeECCSetup(m, 0)
+        decoder = PyMatchingDecoder(c)
+        r = evaluate_decoder(decoder, setup, 1000)
+        results[ic,i,:] .= r
+    end
+end
+
+make_decoder_figure(mem_errors, results, "Toric code with a MWPM decoder")
+```

docs/src/ecc_example_sim.md

@@ -8,6 +8,11 @@ end
 CurrentModule = QuantumClifford.Experimental.NoisyCircuits
 ```
 
+!!! warning "The documentation is incomplete"
+    Waiting for a better documentation than the small example below.
+    Check out also the page on [ECC performance evaluators](@ref ecc_evaluating)
+
+
 Consider Steane 7-qubit code:
 
 ```@example 1

docs/src/references.md

@@ -22,6 +22,12 @@ These publications describe the uniform sampling of random stabilizer states:
 - [berg2020simple](@cite)
 - [li2019measurement](@cite)
 
+For circuit construction routines (for stabilizer measurements for a given code):
+- [cleve1997efficient](@cite)
+- [gottesman1997stabilizer](@cite) (and its erratum)
+- [grassl2002algorithmic](@cite)
+- [grassl2011variations](@cite)
+
 # References
 
 ```@bibliography