some polish

- remove unrelated files and update .gitignore
-  add an auto-generated API documentation for the ECC submodule
-  remove unused `boolean_tableau`
- remove docstrings for already documented functions
- remove a redundant function definition (code_k is already defined in terms of code_n and code_s)
-  minor stilystic cleanup in simple_sparse_codes
- add some rudimentary CSS tests

.gitignore

@@ -4,4 +4,4 @@ LocalPreferences.toml
 */.*swp
 scratch/
 *.cov
-.vscode/settings.json
+.vscode

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,9 @@ pages = [
     "Circuit Operations" => "noisycircuits_ops.md",
     "API" => "noisycircuits_API.md"
 ],
+"ECC compendium" => [
+    "API" => "ECC_API.md"
+],
 "All Gates" => "allops.md",
 "Visualizations" => "plotting.md",
 "API" => "API.md",

docs/src/ECC_API copy.md

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

src/ecc/ECC.jl

@@ -1,22 +1,22 @@
 module ECC
 
 using LinearAlgebra
-using QuantumClifford, SparseArrays
+using QuantumClifford
 using QuantumClifford: AbstractOperation, AbstractStabilizer, Stabilizer
 import QuantumClifford: Stabilizer, MixedDestabilizer
 using DocStringExtensions
 using Combinatorics: combinations
+using SparseArrays
 using Statistics: std
 using Nemo: ZZ, residue_ring, matrix
 
 abstract type AbstractECC end
 
-export Shor9, Steane7, Cleve8, Perfect5, Bitflip3,
-    parity_checks, naive_syndrome_circuit, shor_syndrome_circuit, naive_encoding_circuit,
-    code_n, code_s, code_k, rate, distance,
+export parity_checks, code_n, code_s, code_k, rate, distance,
     isdegenerate, faults_matrix,
-    Unicycle, Bicycle,
-    CSS
+    naive_syndrome_circuit, shor_syndrome_circuit, naive_encoding_circuit,
+    CSS, Unicycle, Bicycle,
+    Shor9, Steane7, Cleve8, Perfect5, Bitflip3
 
 """Parity check tableau of a code."""
 function parity_checks end
@@ -295,13 +295,12 @@ end
 include("circuits.jl")
 include("decoder_pipeline.jl")
 
+include("codes/css.jl")
 include("codes/bitflipcode.jl")
 include("codes/fivequbit.jl")
 include("codes/steanecode.jl")
 include("codes/shorcode.jl")
 include("codes/clevecode.jl")
-
-include("codes/css.jl")
 include("codes/simple_sparse_codes.jl")
 
 end #module

src/ecc/codes/css.jl

@@ -1,12 +1,14 @@
 """An arbitrary CSS error correcting code defined by its X and Z checks.
 
-Hx: A boolean matrix describing the X checks
-Hz: A boolean matrix describing the Z checks
-"""
+```jldoctest
+julia> CSS([0 1 1 0; 1 1 0 0], [1 1 1 1]) |> parity_checks
++ _XX_
++ XX__
++ ZZZZ
+```"""
 struct CSS <: AbstractECC
     Hx::Matrix{Bool}
     Hz::Matrix{Bool}
-    """Creates a CSS code using the two provided matrices where Hx contains the X checks and Hz contains the Z checks."""
     function CSS(Hx, Hz)
         n = size(Hx, 2)
         if n != size(Hz, 2) error("When constructing a CSS quantum code, the two classical codes are required to have the same block size") end
@@ -15,27 +17,12 @@ struct CSS <: AbstractECC
     end
 end
 
-function boolean_tableau(c::CSS)
-    Hx_height, Hx_width = size(c.Hx)
-    Hz_height, Hz_width = size(x.Hz)
-    checks_matrix = falses(Hx_height + Hz_height, Hx_width + Hz_width)
-    checks_matrix[1:Hx_height, 1:Hx_width] = c.Hx
-    checks_matrix[Hx_height+1:end, Hx_width+1:end] = c.Hz
-    return checks_matrix
-end
-
-"""Returns the stabilizer making up the parity check tableau."""
 function parity_checks(c::CSS)
     extended_Hx = Matrix{Bool}(vcat(c.Hx, zeros(size(c.Hz))))
     extended_Hz = Matrix{Bool}(vcat(zeros(size(c.Hx)), c.Hz))
     Stabilizer(fill(0x0, size(c.Hx, 1) + size(c.Hz, 1)), extended_Hx, extended_Hz)
 end
 
-"""Returns the block length of the code."""
 code_n(c::CSS) = size(c.Hx,2)
 
-"""Returns the depth of the parity check matrix"""
 code_s(c::CSS) = size(c.Hx, 1) + size(c.Hz, 1)
-
-"""Returns the number of encoded qubits"""
-code_k(c::CSS) = (2 * size(c.Hx,2)) - code_m(c)

src/ecc/codes/simple_sparse_codes.jl

@@ -1,14 +1,12 @@
-# Currently just has Bicycle and Unicycle codes, but open to all types of rudimentary sparse codes
+"""Generate a bicycle code of the specified height and width (returns an instance of [`CSS`](@ref), not a `Bicycle` type).
 
-"""Takes a height and width of matrix and generates a bicycle code to the specified height and width.
+This is not a deterministic function (random sampling is involved in the creation of a bicycle code).
 
 Parameters:
-- n: width of array, should be >= 2
-- m: height of array, should be >= 2 and a multiple of 2
-
+- `n`: width of array, should be ≥ 2
+- `m`: height of array, should be ≥ 2 and a multiple of 2
 
-``` jldoctest Bicycle
-julia> using QuantumClifford.ECC
+```jldoctest
 julia> parity_checks(Bicycle(6, 4))
 + XX_X_X
 + X_X_XX
@@ -22,12 +20,6 @@ julia> Bicycle(6,4).Hx
 
 julia> typeof(Bicycle(6, 4))
 CSS
-
-julia> QuantumClifford.stab_looks_good(parity_checks(Bicycle(6, 4)))
-true
-
-julia> QuantumClifford.stab_looks_good(parity_checks(Bicycle(10, 6)))
-true
 ```
 """
 function Bicycle(n::Int, m::Int)
@@ -54,7 +46,7 @@ Parameters:
 - n: width of array, should be >= 1
 - set: array of indices that are 'active' checks in the circulant code
 
-``` jldoctest Unicycle
+```jldoctest
 julia> Unicycle(7, [1, 2, 4])
 4×8 Matrix{Bool}:
  0  1  1  0  1  0  0  1
@@ -84,7 +76,7 @@ Required before the bicycle code can be used.
 
 Typical usage:
 
-``` jldoctest reduce_bicycle
+```jldoctest
 julia> reduce_bicycle(Bool[1 1 0 1 0 1; 0 1 1 1 1 0; 1 0 1 0 1 1])
 Bool[1 1 0 1 0 1; 1 0 1 0 1 1]
 
@@ -110,14 +102,16 @@ end
 """Takes a list of indices and creates the base of the bicycle matrix.
 
 For example:
-``` jldoctest circ_to_bicycle_h0
+
+```jldoctest
 julia> circ_to_bicycle_h0([0, 1], 3)
 Bool[1 1 0 1 0 1; 0 1 1 1 1 0; 1 0 1 0 1 1]
 
 julia> circ_to_bicycle_h0([0, 1], 4)
 Bool[1 1 0 0 1 0 0 1; 0 1 1 0 1 1 0 0; 0 0 1 1 0 1 1 0; 1 0 0 1 0 0 1 1]
 ```
-See https://arxiv.org/abs/quant-ph/0304161 for more details"""
+
+See `https://arxiv.org/abs/quant-ph/0304161` for more details"""
 function circ_to_bicycle_h0(circ_indices::Array{Int}, n::Int)
     circ_arr = Array{Bool}(undef, n)
     circ_matrix = Matrix{Bool}(undef, n, n)
@@ -145,9 +139,9 @@ end
 Required before the unicycle code can be used.
 
 Typical usage:
-`reduce_unicycle(circ_to_unicycle_h0(array_indices, block length) )`
+`reduce_unicycle(circ_to_unicycle_h0(array_indices, block length))`
 
-``` jldoctest reduce_unicycle
+```jldoctest
 julia> reduce_unicycle(Bool[1 1 0 1 0 0 0 1; 0 1 1 0 1 0 0 1; 0 0 1 1 0 1 0 1; 0 0 0 1 1 0 1 1; 1 0 0 0 1 1 0 1; 0 1 0 0 0 1 1 1; 1 0 1 0 0 0 1 1])
 Bool[0 1 1 0 1 0 0 1; 0 0 0 1 1 0 1 1; 0 1 0 0 0 1 1 1; 1 0 1 0 0 0 1 1]
 ```"""
@@ -174,11 +168,11 @@ end
 For example:
 `circ_to_unicycle_h0([1, 2, 4], 7)`
 
-``` jldoctest circ_to_unicycle
+```jldoctest
 julia> circ_to_unicycle([1, 2, 4], 7)
 Bool[1 1 0 1 0 0 0 1; 0 1 1 0 1 0 0 1; 0 0 1 1 0 1 0 1; 0 0 0 1 1 0 1 1; 1 0 0 0 1 1 0 1; 0 1 0 0 0 1 1 1; 1 0 1 0 0 0 1 1]
 ```
-See https://arxiv.org/abs/quant-ph/0304161 for more details"""
+See `https://arxiv.org/abs/quant-ph/0304161` for more details"""
 function circ_to_unicycle_h0(circ_indices::Array{Int}, n::Int)
     circ_arr = fill(false, n)
     one_col = transpose(fill(true, n))
@@ -204,7 +198,7 @@ end
 
 """Attempts to generate a list of indices to be used in a bicycle code using a search method
 
-``` jldoctest bicycle_set_gen
+```jldoctest
 julia> bicycle_set_gen(3)
 [0, 1]
 

test/test_doctests.jl

@@ -4,6 +4,6 @@ using QuantumClifford
 ENV["LINES"] = 80    # for forcing `displaysize(io)` to be big enough
 ENV["COLUMNS"] = 80
 @testset "Doctests" begin
-    DocMeta.setdocmeta!(QuantumClifford, :DocTestSetup, :(using QuantumClifford); recursive=true)
+    DocMeta.setdocmeta!(QuantumClifford, :DocTestSetup, :(using QuantumClifford; using QuantumClifford.ECC); recursive=true)
     doctest(QuantumClifford)
 end

test/test_ecc.jl

@@ -8,6 +8,7 @@ codes = [
     Shor9(),
     Perfect5(),
     Cleve8(),
+    CSS([0 1 1 0; 1 1 0 0], [1 1 1 1]),
 ]
 
 ##

test/test_ecc_encoding.jl

@@ -19,6 +19,7 @@ using QuantumClifford.ECC: AbstractECC, Cleve8, Steane7, Shor9, Bitflip3, Perfec
         :(S"Y_"),
         :(S"Z_"),
         :(S"X_"),
+        :(CSS([0 1 1 0; 1 1 0 0], [1 1 1 1])),
         fill(:(random_stabilizer(5,7)), 100)...
         ]
 

test/test_ecc_syndromes.jl

@@ -8,7 +8,8 @@ codes = [
     Steane7(),
     Shor9(),
     Perfect5(),
-    Cleve8()
+    Cleve8(),
+    CSS([0 1 1 0; 1 1 0 0], [1 1 1 1])
 ]
 
 ##