tests: test consistency of Bivariate Bicycle code using LPCode constructor

[Fe-r-oz]

@Krastanov, @royess, please find the Lifted Product Construction of Bivariate Bicycle codes, here the abelian group is : ℤₗ x ℤₘ where ℤⱼ cyclic group of order j. Utilized cyclic_group from Oscar.

ECC Zoo refers to these codes as one of the several (two block group algebra codes) 2BGA codes. Since, we have the constructor for 2BGA, and based on Bravyi description (#352 (comment)), it seems this should be simple when considering the LP construction. There are other construction methods that does not rely on LP construction: 1) the circulant matrix construction in GF(2) or 2) where Group algebra (GA) can be defined as quotient of a bivariate polynomial ring.

The literature says that BB belong to class of Generalized Bicycle Codes (GB), and GB codes were further generalized into two block group algebra codes (2BGA). That's why ECC Zoo says they are one of several 2BGA codes.

Initial output:

julia> import Hecke

julia> import Oscar

julia> using QuantumClifford.ECC: bivariate_bicycle_codes

julia> bivariate_bicycle_codes([3, 1, 2], [3, 1, 2], 9, 6)
QuantumCliffordHeckeExt.LPCode(Hecke.GroupAlgebraElem{Nemo.FqFieldElem, Hecke.GroupAlgebra{Nemo.FqFieldElem, Oscar.DirectProductGroup, Oscar.BasicGAPGroupElem{Oscar.DirectProductGroup}}}[Element of Group algebra of group of order 54 over GF(2) with coefficients Nemo.FqFieldElem[0, 1, 1, 1, 0, 0, 0, 0, 0, 0  …  0, 0, 0, 0, 0, 0, 0, 0, 0, 0];;], Hecke.GroupAlgebraElem{Nemo.FqFieldElem, Hecke.GroupAlgebra{Nemo.FqFieldElem, Oscar.DirectProductGroup, Oscar.BasicGAPGroupElem{Oscar.DirectProductGroup}}}[Element of Group algebra of group of order 54 over GF(2) with coefficients Nemo.FqFieldElem[0, 1, 1, 1, 0, 0, 0, 0, 0, 0  …  0, 0, 0, 0, 0, 0, 0, 0, 0, 0];;], Group algebra of group of order 54 over GF(2), Nemo.representation_matrix)

julia> stab_looks_good(parity_checks(bivariate_bicycle_codes([3, 2, 7], [3, 1, 2], 12, 12)), remove_redundant_rows=true)
true

julia> B = bivariate_bicycle_codes([3,1,2],[3,1,2],6,6)
QuantumCliffordHeckeExt.LPCode(Hecke.GroupAlgebraElem{Nemo.FqFieldElem, Hecke.GroupAlgebra{Nemo.FqFieldElem, Oscar.DirectProductGroup, Oscar.BasicGAPGroupElem{Oscar.DirectProductGroup}}}[Element of Group algebra of group of order 36 over GF(2) with coefficients Nemo.FqFieldElem[0, 1, 1, 1, 0, 0, 0, 0, 0, 0  …  0, 0, 0, 0, 0, 0, 0, 0, 0, 0];;], Hecke.GroupAlgebraElem{Nemo.FqFieldElem, Hecke.GroupAlgebra{Nemo.FqFieldElem, Oscar.DirectProductGroup, Oscar.BasicGAPGroupElem{Oscar.DirectProductGroup}}}[Element of Group algebra of group of order 36 over GF(2) with coefficients Nemo.FqFieldElem[0, 1, 1, 1, 0, 0, 0, 0, 0, 0  …  0, 0, 0, 0, 0, 0, 0, 0, 0, 0];;], Group algebra of group of order 36 over GF(2), Nemo.representation_matrix)

#All the code_n values match from two papers!
julia> code_n(bivariate_bicycle_codes([3,1,2],[3,1,2],6,6))
72
julia> code_n(bivariate_bicycle_codes([3,1,2],[3,1,2],9,6))
108
julia> code_n(bivariate_bicycle_codes([3, 2, 7], [3, 1, 2], 12, 12))
288
julia> code_n(bivariate_bicycle_codes([9,1,2],[0,2,7],15,3))
90
julia> code_n(bivariate_bicycle_codes([3,1,2],[3,1,2],12,6))
144
julia> code_n(bivariate_bicycle_codes([9,1,2],[3,25,26],30,6))
360
julia> code_n(bivariate_bicycle_codes([3,10,17],[5,3,19],21,18))
756
julia> code_n(bivariate_bicycle_codes([6,5,6],[1,4,13],14,7))
196
julia> code_n(bivariate_bicycle_codes([5,2,3],[2,7,6],15,5))
150
julia> code_n(bivariate_bicycle_codes([9,1,2],[0,1,11],12, 3))
72
julia> code_n(bivariate_bicycle_codes([8,4,1],[5,8,7],9,5))
90

#needs to be investigated why code_k gives 0 while code_n works fine and why some decoder tests are broken in test summary if the output is originating from there. 

#adding Oscar to test suite will causes some CIs to fail, we need to suppress those unrelated errors.

#ERROR: LoadError: InitError: GAP.jl currently does not support multithreaded garbage collection. Please run julia with `--#gcthreads=1` for now. 
#Stacktrace: 

The tests passed locally for encoding, decoding, syndrome etc.

  Stored in directory: /tmp/pip-ephem-wheel-cache-3qca0wlo/wheels/aa/01/42/62baa284292ba38f07f9aef82b69982bfca8b615ad87b970f3
Successfully built ldpc
Installing collected packages: tqdm, six, pyparsing, pillow, packaging, numpy, networkx, kiwisolver, fonttools, cycler, scipy, python-dateutil, contourpy, matplotlib, ldpc, pymatching
Successfully installed contourpy-1.3.0 cycler-0.12.1 fonttools-4.54.1 kiwisolver-1.4.7 ldpc-0.1.51 matplotlib-3.9.2 networkx-3.3 numpy-1.26.4 packaging-24.1 pillow-10.4.0 pymatching-2.2.1 pyparsing-3.1.4 python-dateutil-2.9.0.post0 scipy-1.14.1 six-1.16.0 tqdm-4.66.5
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: Skipped ExpandTemplates step (doctest only).
[ Info: Skipped CrossReferences step (doctest only).
[ Info: Skipped CheckDocument step (doctest only).
[ Info: Skipped Populate step (doctest only).
[ Info: Skipped RenderDocument step (doctest only).
WARNING: using QuantumClifford.I in module ECC conflicts with an existing identifier.
WARNING: using LinearAlgebra.I in module QuantumClifford conflicts with an existing identifier.
Skipping Base.active_repl
Skipping Base.active_repl_backend
Test Summary: |   Pass  Broken   Total      Time
Package       | 286158       9  286167  13m48.0s
     Testing QuantumClifford tests passed 

This is an initial commit but there is further work that needs to be done. Please feel free to add your insights. That is much appreciated.

If I am not mistaken, I think we will need one function for LiftedProduct based on the current logic that also takes l and where Group Algebra is product of cyclic groups. Currently, we are only assuming that l is the only parameter that we need for LP codes with GA being an abelian group based on l. But we need to cater to m parameter as well now since we are taking direct product of two cyclic groups, each with it's own parameter, l and m, respectively. . Something like the following if we want to construct these codes using LPcode constructor. I do skimmed some of these papers and not ready about the LP constructions methods. In this Panteleev Paper, where he describes the different codes Bicycle, two block group algebra, generalized bicycle for which constructors have been already defined, we need only l parameter. For bivariate bicycle codes, an additional parameter m and a GA that is direct product of cyclic groups, is required based on the current logic. Maybe we will need the following:

function LiftedCode(shift_array::Matrix{Int}, l::Int, m::Int; GA::GroupAlgebra=group_algebra(GF(2), direct_product(cyclic_group(l), cyclic_group(m))))

Do we really need the above method because LiftedCode constructor for 2GBA codes is already defined, and these codes end up calling that constructor because of being a subset of 2GBA? It seems if we want to specifically use LPCode constructor, then we have to consider defining it.

Hopefully, this sounds reasonable approach for further exploration. While this provides easy integration of cyclic groups, Two suspects are why code_k is 0 for instances of these codes and why decoder test broken warnings. In the earlier PR (352), code_k gives correct results for non-LP construction. @test canonicalize!(parity_checks(LP implementation)) == canonicalize!(non-LP implementation (352))) to ensure this LP-implementation is correct.

Feedback is more than welcome.

P.S. I have not thoroughly read the 4 papers that were referred in LPCode PR, so I am unfamiliar with those works. @Krastanov , @royess will have have better insights.

• The code is properly formatted and commented.
• Substantial new functionality is documented within the docs.
• All new functionality is tested.
• All of the automated tests on github pass.

[royess]

I was feeling unwell and was not able to respond to this earlier.

Bivariate bicycle codes are 2GBA codes, as you mentioned. So it should be constructed by two_block_group_algebra_codes by giving the group algebra elements, as you did in your commit. Your approach looks reasonable to me in general.

I am unfamiliar with OScar. So, I cannot help with checking your implementation.

I would not suggest adding bivariate bicycle codes as constructors for LPCode. A helper function looks better and less confusing.

If it is only for testing purposes, there will be no need to modify codes in ext, in particular if we do not want two co-existing implementations of bivariate bicycle codes that cause confusion. Instead, we may want to save these things (including OScar as a dependency) for tests.

[Fe-r-oz]

@royess, No worries. I think there is no need to define these code as constructors for LPCode. In fact, there is a much simpler way. Please check out the rebase: 656d5e8. Feedback is more than welcome.

Now, both constructions provide exact code_k, and code_n correct values even though they use vastly different formulas. The circulant construction make use of intersection of kernel calculation given by: k = 2 * dim(kernel(A) ∩ kernel (B)) to calculate code_k while LP construction uses the built-in formulas.

As you said, the two co-existing implementations cause some confusion. The canonical forms of their parity check matrices don't match though, maybe that is because of the different construction methods (Group Algebra or GF(2) circulant Matrices) and conventions as we are using group algebras.

I have cross-checked the circulant-matrix based implementation with the original python implementation provided in the Bravyi paper as well. I used MAT.jl to import the python matrices, and compare for all code instances of datasets as follows: Also, I tested for most instances of code present in the literature code_k and code_n here

# Before pushing this PR
julia> using MAT
julia> using QuantumClifford
julia> using QuantumClifford.ECC: BBQLDPC, parity_checks
julia> mat_file_path = "/home/Feroz/Desktop/matrices96.mat";
julia> mat_data = matopen(mat_file_path);
julia> AT = read(mat_data, "AT");
julia> BT = read(mat_data, "BT");
# since  Hx = hcat(A, B), and Hz = hcat(B', A'),
# so cross-checked A and B matrices for all instances before hcating Hx, and Hz
julia> BTT, ATT = parity_checks(BBQLDPC(9, 6, [3, 1, 2], [3, 1, 2]))
([0 0 … 0 0; 0 0 … 0 0; … ; 0 0 … 0 0; 0 0 … 0 0], [0 0 … 0 0; 1 0 … 0 0; … ; 0 0 … 0 0; 0 0 … 1 0])
julia> ATT == AT
true
julia> BTT == BT
true

Is it possible for one family (like one in consideration) of error-correcting codes to nonequivalent canonical forms of parity-check matrices, especially if they have different construction/representation methods over different group objects? As you know, In literature, there are three construction methods: LP Code (Group Algebra) construction 2) quotient bivariate polynomial ring construction 3) circulant construction.

There is one example of this observation, Golay code: https://errorcorrectionzoo.org/c/golay. The ECC Zoo construction for these code uses a fancy math object 'great dodecahedron', that has a nonequivalent canonical form than the simple matrix-based construction methods which is widely used. In most books such as Huffman Fundamentals of Error Correction and most papers, if the construction method is on simple math object (GF(2) matrix), and those codes have canonically equivalent parity check matrices even if a slight different approach. Here, I test equivalence of two different constructions methods for reverse-bordered circulant matrix for Golay code in Golay code test file. Apart from this, I don't have know reasons about why this could be the case.

Edit:

After some more pondering, I found out that the bivaraite polynomial ring construction of these codes (which is similar to the permutation matrix construction) applies a permutation matrix to the column space and row space both, that's why their canonical forms are nonequivalent. Sₘ is a circulant permutation matrix, and x = Sₗ ⊗ Iₘ permutes the row space and y = Iₗ ​⊗ Sₘ permutes the column space. Permuting the row-space leads to equivalent canonical form, while this is not the case if we permute the column space as well. Hopefully, this make sense.

[Fe-r-oz]

Some brief details about Oscar methods:

abelian_group(PcGroup, [l,m]) provides the direct product of cyclic groups l, and m that correspond to abelian ℤₗ x ℤₘ. Please find more detail here: https://docs.oscar-system.org/stable/Groups/pcgroup/#Polycyclic-groups.

Hecke does not have constructors for product of abelian/cyclic groups (https://docs.oscar-system.org/stable/Groups/products/) so we just import Oscar to the doctests to meet the requirements for computing the direct product. In addition, ECC Zoo, in a slightly different way, states that 'Bivariate bicycle codes are Abelian LP codes over groups of the form ℤₗ x ℤₘ' in the children section of Abelian LP Code. Therefore, we can simply use LPCode instead of manually defining a constructor, as was previously required for 2BGA or GB codes, without modifying anything in the existing code.

Hopefully, the current approach is a reasonable one.

@Krastanov, I think the PR is ready for review, Thank you!

[Fe-r-oz]

P.S. Cross checks (All code constructions verified for the following as well):

• Coprime Bivariate Bicycle code via Hecke's Group Algebra #378
• Multivariate Bicycle code via Hecke's Group Algebra #381

[Fe-r-oz]

Ah... Found something much simpler. It just occurred to me today after some more thought. Now, only used Hecke.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.01%. Comparing base (be50f9c) to head (3fa0843).
Report is 22 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #372      +/-   ##
==========================================
- Coverage   83.06%   83.01%   -0.05%     
==========================================
  Files          70       70              
  Lines        4410     4410              
==========================================
- Hits         3663     3661       -2     
- Misses        747      749       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Fe-r-oz]

Since #394 is resolved, I have added the test file that reproduced complete Tables from three different papers for these codes.

I didn't add test file earlier because it would have caused CI-failures unrelated to this PR and instead opened the mentioned issue about it.

Now, The PR has been setup for review, @Krastanov, Thanks!

P.S:

This PR is implemented as a cross-check to #399. So, please review that first, so I can add the bivariate_bicycle_codes constructor defined in #399 for cross-testing purposes here.

[Krastanov]

is this still needed or is all of this functionality and/or tests already merged in your other PRs?

[Fe-r-oz]

Not necessarily.

The original plan was to use the LPCode constructor for a consistency check by generating BB code and comparing it with the results from two_block_algebra_codes. However, as shown in #421, we've already decided to revert to two_block_group_algebra_codes instead of LPCode to avoid the roundabout way. Testing both approaches can still be useful if further verification is needed.