fix doc build, misc bugs and add doctests

Author: Fe-r-oz

docs/Project.toml

@@ -1,5 +1,15 @@
 [deps]
 BinaryProvider = "b99e7846-7c00-51b0-8f62-c81ae34c0232"
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
 CodingTheory = "7ca085cf-10e4-43da-ad7d-8f62f68877b3"
+DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+Hecke = "3e1990a7-5d81-5526-99ce-9ba3ff248f21"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+Oscar = "f1435218-dba5-11e9-1e4d-f1a5fab5fc13"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"

src/Quantum/product_codes.jl

@@ -12,6 +12,27 @@
     HypergraphProductCode(A::CTMatrixTypes, B::CTMatrixTypes; char_vec::Union{Vector{zzModRingElem}, Missing}= missing, logs_alg::Symbol = :stnd_frm)
 
 Return the hypergraph product code of matrices `A` and `B`.
+
+# Example
+
+```jldoctest
+[1922, 50, 16]] Hypergraph Product Code from Appendix B, Example C1 of [panteleev2021degenerate](@cite).
+
+julia> F, x = polynomial_ring(Oscar.Nemo.Native.GF(2), :x);
+
+julia> l = 31;
+
+julia> R, = residue_ring(F, x^l -1);
+
+julia> h = R(1 + x^2 + x^5);
+
+julia> A = residue_polynomial_to_circulant_matrix(h);
+
+julia> code = HypergraphProductCode(A, A);
+
+julia> length(code), dimension(code)
+(1922, 50)
+```
 """
 function HypergraphProductCode(A::CTMatrixTypes, B::CTMatrixTypes; char_vec::Union{Vector{zzModRingElem},
     Missing} = missing, logs_alg::Symbol = :stnd_frm)
@@ -258,6 +279,29 @@ end
     GeneralizedBicycleCode(A::CTMatrixTypes, B::CTMatrixTypes; char_vec::Union{Vector{zzModRingElem}, Missing} = missing, logs_alg::Symbol = :stnd_frm)
 
 Return the generealized bicycle code given by `A` and `B`.
+
+# Example
+
+[[254, 28, 14 ≤ d ≤ 20]] Generalized Bicycle Code from Appendix B, Example A1 of [panteleev2021degenerate](@cite).
+
+```jldoctest
+julia> F = Oscar.Nemo.Native.GF(2);
+
+julia> S, x = polynomial_ring(F, :x);
+
+julia> l = 127;
+
+julia> R, _ = residue_ring(S, x^l - 1);
+
+julia> a = 1 + x^15 + x^20 + x^28 + x^66;
+
+julia> b = 1 + x^58 + x^59 + x^100 + x^121;
+
+julia> code = GeneralizedBicycleCode(R(a), R(b));
+
+julia> length(code), dimension(code)
+(254, 28)
+```
 """
 function GeneralizedBicycleCode(A::T, B::T; char_vec::Union{Vector{zzModRingElem}, Missing} = missing,
     logs_alg::Symbol = :stnd_frm) where T <: CTMatrixTypes
@@ -508,6 +552,39 @@ end
     LiftedProductCode(A::MatElem{T}, B::MatElem{T}; char_vec::Union{Vector{zzModRingElem}, Missing} = missing, logs_alg::Symbol = :stnd_frm) where T <: Union{ResElem, CTGroupAlgebra}
 
 Return the lifted product code given by the matrices `A` and `B`.
+
+# Example
+
+[[882, 24, 18 ≤ d ≤ 24]] Lifted Product Code from Appendix B, Example B1 of [panteleev2021degenerate](@cite).
+
+```jldoctest
+julia> F = Oscar.Nemo.Native.GF(2);
+
+julia> S, x = polynomial_ring(F, :x)
+(Univariate polynomial ring in x over F, x)
+
+julia> l = 63;
+
+julia> R, _ = residue_ring(S, x^l - 1);
+
+julia> A = matrix(R, 7, 7,
+           [x^27, 0   , 0   , 0   , 0   , 1   , x^54,
+            x^54, x^27, 0   , 0   , 0   , 0   , 1   ,
+            1   , x^54, x^27, 0   , 0   , 0   , 0   ,
+            0   , 1   , x^54, x^27, 0   , 0   , 0   ,
+            0   , 0   , 1   , x^54, x^27, 0   , 0   ,
+            0   , 0   , 0   , 1   , x^54, x^27, 0   ,
+            0   , 0   , 0   , 0   , 1   , x^54, x^27]);
+
+julia> b = R(1 + x + x^6);
+
+julia> code = LiftedProductCode(A, b);
+┌ Warning: Commutativity of A and b required but not yet enforced.
+└ @ CodingTheory ~/Desktop/ct/doctests/CodingTheory/src/Quantum/product_codes.jl:340
+
+julia> length(code), dimension(code)
+(882, 24)
+```
 """
 function LiftedProductCode(A::MatElem{T}, B::MatElem{T}; char_vec::Union{Vector{zzModRingElem}, Missing} =
     missing, logs_alg::Symbol = :stnd_frm) where T <: Union{ResElem, CTGroupAlgebra}
@@ -894,6 +971,29 @@ Return the bivariate bicycle code defined by the residue ring elements `a` and `
 
 # Note
 - This is defined in https://arxiv.org/pdf/2308.07915
+
+# Example
+
+[[360, 12, ≤24]] Bivariate Bicycle Code from Table 3 of [bravyi2024high](@cite).
+
+```jldoctest
+julia> using CodingTheory, Oscar;
+
+julia> S, (x, y) = polynomial_ring(Oscar.Nemo.Native.GF(2), [:x, :y]);
+
+julia> l = 30; m = 6;
+
+julia> R, _ = quo(S, ideal(S, [x^l - 1, y^m - 1]));
+
+julia> a = R(x^9 + y + y^2);
+
+julia> b = R(y^3 + x^25 + x^26);
+
+julia> code = BivariateBicycleCode(a, b);
+
+julia> length(code), dimension(code)
+(360, 12)
+```
 """
 function BivariateBicycleCode(a::T, b::T) where T <: Union{MPolyQuoRingElem{FqMPolyRingElem}, MPolyQuoRingElem{fpMPolyRingElem}}
     R = parent(a)
@@ -954,6 +1054,29 @@ Return the coprime bivariate bicycle code defined by the residue ring elements `
 
 # Note
 - This is defined in https://arxiv.org/pdf/2408.10001v1.
+
+# Example
+
+[126, 12, 10]] Coprime Bivariate Bicycle Code from Table 2 of [wang2024coprime](@cite).
+
+```jldoctest
+julia> using CodingTheory, Oscar;
+
+julia> S, (P) = polynomial_ring(Oscar.Nemo.Native.GF(2), [:P]);
+
+julia> l = 7; m = 9;
+
+julia> R, _ = quo(S, ideal(S, [P[1]^(l*m)]));
+
+julia> a = R(1 + P[1] + P[1]^58);
+
+julia> b = R(P[1]^3 + P[1]^16 + P[1]^44);
+
+julia> code = CoprimeBivariateBicycleCode(a, b);
+
+julia> length(code), dimension(code)
+(126, 12)
+```
 """
 function CoprimeBivariateBicycleCode(a::T, b::T) where T <: Union{MPolyQuoRingElem{FqMPolyRingElem}, MPolyQuoRingElem{fpMPolyRingElem}}
     R = parent(a)

test/Quantum/product_codes_test.jl

@@ -198,10 +198,9 @@
         # takes awhile to run
 
         # Example C2
-        F = Oscar.Nemo.Native.GF(2)
-        S, x = polynomial_ring(F, :x)
+        F, x = polynomial_ring(Oscar.Nemo.Native.GF(2), :x)
         l = 31
-        R = ResidueRing(S, x^l - 1)
+        R, = residue_ring(F, x^l -1)
         h = R(1 + x^2 + x^5)
         A = residue_polynomial_to_circulant_matrix(h)
         Q = HypergraphProductCode(A, A)
@@ -606,7 +605,9 @@
         @test length(Q) == 196
         @test dimension(Q) == 12
         @test_broken minimum_distance(S) == 8
+    end
 
+    @testset "CoprimeBivariateBicycleCode" begin
         # Coprime Bivariate Bicycle codes
         # Table 2 of https://arxiv.org/pdf/2408.10001v1
         # [[30, 4, 6]]
@@ -664,4 +665,5 @@
         @test length(Q) == 126
         @test dimension(Q) == 12
         @test_broken minimum_distance(Q) == 10
+    end
 end