add QuantumCliffordOscarExt to provide convenient API for finitely presented groups via specific group presentation

.github/workflows/ci.yml

@@ -44,6 +44,11 @@ jobs:
           arch: ${{ matrix.arch }}
       - uses: julia-actions/cache@v2
       - uses: julia-actions/julia-buildpkg@v1
+      - name: "Inject Oscar as test dependency (if not Windows and not threaded)"
+        if: ${{ matrix.os != 'windows-latest' && matrix.threads == 1 }}
+        continue-on-error: true
+        run: |
+          sed -i -e "s/\[deps\]/[deps]\nOscar = \"f1435218-dba5-11e9-1e4d-f1a5fab5fc13\"/" test/Project.toml
       - uses: julia-actions/julia-runtest@v1
         env:
           JULIA_NUM_THREADS: ${{ matrix.threads }}

Project.toml

@@ -27,6 +27,7 @@ CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
 Hecke = "3e1990a7-5d81-5526-99ce-9ba3ff248f21"
 LDPCDecoders = "3c486d74-64b9-4c60-8b1a-13a564e77efb"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+Oscar = "f1435218-dba5-11e9-1e4d-f1a5fab5fc13"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 PyQDecoders = "17f5de1a-9b79-4409-a58d-4d45812840f7"
 Quantikz = "b0d11df0-eea3-4d79-b4a5-421488cbf74b"
@@ -37,6 +38,7 @@ QuantumCliffordGPUExt = "CUDA"
 QuantumCliffordHeckeExt = "Hecke"
 QuantumCliffordLDPCDecodersExt = "LDPCDecoders"
 QuantumCliffordMakieExt = "Makie"
+QuantumCliffordOscarExt = ["Hecke", "Oscar"]
 QuantumCliffordPlotsExt = "Plots"
 QuantumCliffordPyQDecodersExt = "PyQDecoders"
 QuantumCliffordQOpticsExt = "QuantumOpticsBase"
@@ -57,6 +59,7 @@ LinearAlgebra = "1.9"
 MacroTools = "0.5.9"
 Makie = "0.20, 0.21"
 Nemo = "0.42.1, 0.43, 0.44, 0.45, 0.46, 0.47"
+Oscar = "1.1.1"
 Plots = "1.38.0"
 PrecompileTools = "1.2"
 PyQDecoders = "0.2.1"

docs/Project.toml

@@ -8,6 +8,7 @@ Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 Hecke = "3e1990a7-5d81-5526-99ce-9ba3ff248f21"
 LDPCDecoders = "3c486d74-64b9-4c60-8b1a-13a564e77efb"
 Nemo = "2edaba10-b0f1-5616-af89-8c11ac63239a"
+Oscar = "f1435218-dba5-11e9-1e4d-f1a5fab5fc13"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 PyQDecoders = "17f5de1a-9b79-4409-a58d-4d45812840f7"
 Quantikz = "b0d11df0-eea3-4d79-b4a5-421488cbf74b"

docs/make.jl

@@ -12,6 +12,11 @@ import Hecke
 
 const QuantumCliffordHeckeExt = Base.get_extension(QuantumClifford, :QuantumCliffordHeckeExt)
 
+ENV["OSCAR_PRINT_BANNER"] = "false"
+import Oscar
+
+const QuantumCliffordOscarExt = Base.get_extension(QuantumClifford, :QuantumCliffordOscarExt)
+
 #DocMeta.setdocmeta!(QuantumClifford, :DocTestSetup, :(using QuantumClifford); recursive=true)
 
 ENV["LINES"] = 80    # for forcing `displaysize(io)` to be big enough
@@ -25,7 +30,7 @@ doctest = false,
 clean = true,
 sitename = "QuantumClifford.jl",
 format = Documenter.HTML(size_threshold_ignore = ["API.md"]),
-modules = [QuantumClifford, QuantumClifford.Experimental.NoisyCircuits, QuantumClifford.ECC, QuantumInterface, QuantumCliffordHeckeExt],
+modules = [QuantumClifford, QuantumClifford.Experimental.NoisyCircuits, QuantumClifford.ECC, QuantumInterface, QuantumCliffordHeckeExt, QuantumCliffordOscarExt],
 warnonly = [:missing_docs],
 linkcheck = true,
 authors = "Stefan Krastanov",

docs/src/ECC_API.md

@@ -10,4 +10,11 @@ Private = false
 ```@autodocs
 Modules = [QuantumCliffordHeckeExt]
 Private = true
-```
+```
+
+## Implemented in an extension requiring `Oscar.jl`
+
+```@autodocs
+Modules = [QuantumCliffordOscarExt]
+Private = true
+```

docs/src/references.bib

@@ -487,3 +487,34 @@ @article{anderson2014fault
   year={2014},
   publisher={APS}
 }
+
+@article{lin2024quantum,
+  title={Quantum two-block group algebra codes},
+  author={Lin, Hsiang-Ku and Pryadko, Leonid P},
+  journal={Physical Review A},
+  volume={109},
+  number={2},
+  pages={022407},
+  year={2024},
+  publisher={APS}
+}
+
+@inproceedings{wang2023abelian,
+  title={Abelian and non-Abelian quantum two-block codes},
+  author={Wang, Renyu and Lin, Hsiang-Ku and Pryadko, Leonid P},
+  booktitle={2023 12th International Symposium on Topics in Coding (ISTC)},
+  pages={1--5},
+  year={2023},
+  organization={IEEE}
+}
+
+@article{naghipour2015quantum,
+  title={Quantum stabilizer codes from Abelian and non-Abelian groups association schemes},
+  author={Naghipour, Avaz and Jafarizadeh, Mohammad Ali and Shahmorad, Sedaghat},
+  journal={International Journal of Quantum Information},
+  volume={13},
+  number={03},
+  pages={1550021},
+  year={2015},
+  publisher={World Scientific}
+}

docs/src/references.md

@@ -40,6 +40,9 @@ For quantum code construction routines:
 - [steane1999quantum](@cite)
 - [campbell2012magic](@cite)
 - [anderson2014fault](@cite)
+- [lin2024quantum](@cite)
+- [wang2023abelian](@cite)
+- [naghipour2015quantum](@cite)
 
 For classical code construction routines:
 - [muller1954application](@cite)

ext/QuantumCliffordOscarExt/QuantumCliffordOscarExt.jl

@@ -0,0 +1,19 @@
+module QuantumCliffordOscarExt
+
+using DocStringExtensions
+
+import Nemo
+import Nemo: FqFieldElem
+import Hecke: group_algebra, GF, abelian_group, gens, quo, one, GroupAlgebra,
+   GroupAlgebraElem
+import Oscar
+import Oscar: free_group, small_group_identification, describe, order, FPGroupElem, FPGroup,
+    BasicGAPGroupElem, DirectProductGroup, direct_product, cyclic_group, sub
+
+import QuantumClifford.ECC: two_block_group_algebra_codes
+
+include("types.jl")
+include("direct_product.jl")
+include("group_presentation.jl")
+
+end # module

ext/QuantumCliffordOscarExt/direct_product.jl

@@ -0,0 +1,78 @@
+"""
+# Direct Product of Groups
+
+The direct product of groups is instrumental in constructing group algebra of two-block
+group algebra code. Lin and Pryadko illustrate this method in Appendix C, Table 2 of
+[lin2024quantum](@cite), where they utilize the direct product of two cyclic groups,
+expressed as `C₂ₘ = Cₘ × C₂`, with an order of `2m`.
+
+# Example
+
+The [[56, 28, 2]] abelian 2BGA code from Appendix C, Table II in [lin2024quantum](@cite)
+can be constructed using the direct product of two cyclic groups. Specifically, the group
+`C₂₈` of order `l = 28` can be represented as `C₁₄ × C₂`, where the first group has order
+`m = 14` and the second group has order `n = 2`.
+
+```jldoctest directprod
+julia> import Oscar: direct_product, cyclic_group, small_group_identification, describe, order, sub; # hide
+
+julia> import Hecke: gens, quo, group_algebra, GF, one; # hide
+
+julia> m = 14; n = 2;
+
+julia> C₁₄ = cyclic_group(m);
+
+julia> C₂ = cyclic_group(n);
+
+julia> G = direct_product(C₁₄, C₂);
+
+julia> GA = group_algebra(GF(2), G);
+
+julia> x, s = gens(GA)[1], gens(GA)[3];
+
+julia> a = [one(GA), x^7];
+
+julia> b = [one(GA), x^7, s, x^8, s * x^7, x];
+
+julia> c = twobga_from_direct_product(a, b, GA);
+
+julia> order(G)
+28
+
+julia> code_n(c), code_k(c)
+(56, 28)
+
+julia> describe(G), small_group_identification(G)
+("C14 x C2", (28, 4))
+```
+
+!!! note When using the direct product of two cyclic groups, it is essential to verify
+the group presentation `Cₘ = ⟨x, s | xᵐ = s² = xsx⁻¹s⁻¹ = 1⟩` is satisfied, where the
+order is `2m`. Ensure that the selected generators have the correct orders of `m = 14`
+and `n = 2`, respectively. If the group presentation is not satisfied, the resulting
+group algebra over `GF(2)` will not represent the intended group, `C₂₈ = C₁₄ × C₂`. In
+addition, `Oscar.sub` can be used to determine if `H` is a subgroup of `G` and to
+confirm that both `C₁₄` and `C₂` are subgroups of `C₂₈`.
+
+```jldoctest directprod
+julia> order(gens(G)[1])
+14
+
+julia> order(gens(G)[3])
+2
+
+julia> x^14 == s^2 == x * s * x^-1 * s^-1
+true
+
+julia> H, _  = sub(G, [gens(G)[1], gens(G)[3]]);
+
+julia> H == G
+true
+```
+"""
+function twobga_from_direct_product(a_elts::VectorDirectProductGroupElem, b_elts::VectorDirectProductGroupElem, F2G::DirectProductGroupAlgebra)
+    a = sum(F2G(x) for x in a_elts)
+    b = sum(F2G(x) for x in b_elts)
+    c = two_block_group_algebra_codes(a,b)
+    return c
+end

ext/QuantumCliffordOscarExt/group_presentation.jl

@@ -0,0 +1,151 @@
+"""
+# Specific Group Presentations
+
+For quantum error-correcting codes like the two-block group algebra (2BGA) code, designing specific
+group presentations for both abelian and non-abelian groups is crucial. These presentations are essential
+for constructing the group algebra of the 2BGA code for a given finite general group, `G`.
+
+Lin and Pryadko, in their seminal paper titled "Quantum Two-Block Group Algebra Codes" [lin2024quantum](@cite),
+employ specific presentations that necessitate the use of `Oscar.free_group`. The diagram below distinguishes
+between small groups (`Hecke/Oscar.small_group`) and finitely presented groups (`Oscar.free_group`) by highlighting
+the existence of extra relations in their presentations.
+
+```@raw html
+<div class="mermaid">
+graph TD
+    A[Group Presentation ⟨S ∣ R⟩] --> B{Are there <br> extra relations?}
+    B -- No --> C[Small groups <br> Hecke/Oscar.small_group]
+    C --> D[Independent generators]
+    C --> E["Example: <br> ⟨r, s ∣ s⁴, r⁹⟩"]
+    B -- Yes --> F[Finitely presented groups <br> Oscar.free_group]
+    F --> G[Defined by interactions]
+    F --> H["Example: <br> ⟨r, s ∣ s⁴, r⁹, s⁻¹rsr⟩"]
+</div>
+```
+
+# Example
+
+The [[96, 12, 10]] 2BGA code from Table I in [lin2024quantum](@cite) has the group presentation
+`⟨r, s | s⁶ = r⁸ = r⁻¹srs = 1⟩` and a group structure of `C₂ × (C₃ ⋉ C₈)`.
+
+```jldoctest finitegrp
+julia> import Oscar: free_group, small_group_identification, describe, order; # hide
+
+julia> import Hecke: gens, quo, group_algebra, GF, one; # hide
+
+julia> F = free_group(["r", "s"]);
+
+julia> r, s = gens(F); # generators
+
+julia> G, = quo(F, [s^6, r^8, r^(-1) * s * r * s]);  # relations
+
+julia> GA = group_algebra(GF(2), G);
+
+julia> r, s = gens(G);
+
+julia> a = [one(G), r, s^3 * r^2, s^2 * r^3];
+
+julia> b = [one(G), r, s^4 * r^6, s^5 * r^3];
+
+julia> c = twobga_from_fp_group(a, b, GA);
+
+julia> order(G)
+48
+
+julia> code_n(c), code_k(c)
+(96, 12)
+
+julia> describe(G), small_group_identification(G)
+("C2 x (C3 : C8)", (48, 9))
+```
+
+# Cyclic Groups
+
+Cyclic groups with specific group presentations, given by `Cₘ = ⟨x, s | xᵐ = s² = xsx⁻¹s⁻¹ = 1⟩`,
+where the order is `2m`, are supported.
+
+To construct the group algebra for a cyclic group, specify the group presentation `⟨S | R⟩`, using
+its generators `S` and defining relations `R`.
+
+# Example
+
+The [[56, 28, 2]] abelian 2BGA code from Appendix C, Table II in [lin2024quantum](@cite) is constructed using
+the cyclic group `C₂₈ = C₁₄ × C₂`.
+
+```jldoctest finitegrp
+julia> m = 14;
+
+julia> F = free_group(["x", "s"]);
+
+julia> x, s = gens(F); # generators
+
+julia> G, = quo(F, [x^m, s^2, x * s * x^-1 * s^-1]); # relations
+
+julia> GA = group_algebra(GF(2), G);
+
+julia> x, s = gens(G);
+
+julia> a = [one(G), x^7];
+
+julia> b = [one(G), x^7, s, x^8, s * x^7, x];
+
+julia> c = twobga_from_fp_group(a, b, GA);
+
+julia> order(G)
+28
+
+julia> code_n(c), code_k(c)
+(56, 28)
+
+julia> describe(G), small_group_identification(G)
+("C14 x C2", (28, 4))
+```
+
+# Dihedral Groups
+
+Dihedral groups with specific group presentations, given by `Dₘ = ⟨r, s | rᵐ = s² = (rs)² = 1⟩`,
+where the order is `2m`, are supported.
+
+To construct the group algebra for a dihedral group, specify the group presentation `⟨S | R⟩`
+using its generators `S` and defining relations `R`.
+
+# Example
+
+The [[24, 8, 3]] 2BGA code from Appendix C, Table III in [lin2024quantum](@cite) is constructed
+using the dihedral group `D₆ = C₆ ⋉ C₂`.
+
+```jldoctest finitegrp
+julia> m = 6;
+
+julia> F = free_group(["r", "s"]);
+
+julia> r, s = gens(F); # generators
+
+julia> G, = quo(F, [r^m, s^2, (r*s)^2]); # relations
+
+julia> GA = group_algebra(GF(2), G);
+
+julia> r, s = gens(G);
+
+julia> a = [one(G), r^4];
+
+julia> b = [one(G), s*r^4, r^3, r^4, s*r^2, r];
+
+julia> c = twobga_from_fp_group(a, b, GA);
+
+julia> order(G)
+12
+
+julia> code_n(c), code_k(c)
+(24, 8)
+
+julia> describe(G), small_group_identification(G)
+("D12", (12, 4))
+```
+"""
+function twobga_from_fp_group(a_elts::VectorFPGroupElem, b_elts::VectorFPGroupElem, F2G::FqFieldFPGroupAlgebra)
+    a = sum(F2G(x) for x in a_elts)
+    b = sum(F2G(x) for x in b_elts)
+    c = two_block_group_algebra_codes(a,b)
+    return c
+end

ext/QuantumCliffordOscarExt/types.jl

@@ -0,0 +1,7 @@
+const VectorFPGroupElem = Vector{FPGroupElem}
+
+const VectorDirectProductGroupElem = Vector{GroupAlgebraElem{FqFieldElem, GroupAlgebra{FqFieldElem, DirectProductGroup, BasicGAPGroupElem{DirectProductGroup}}}}
+
+const FqFieldFPGroupAlgebra = GroupAlgebra{FqFieldElem, FPGroup, FPGroupElem}
+
+const DirectProductGroupAlgebra = GroupAlgebra{FqFieldElem, DirectProductGroup, BasicGAPGroupElem{DirectProductGroup}}