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

[thofma]

@Fe-r-oz hope I did everything correct

Edit: Here some explanation for the CI changes: Since Oscar does not work on Windows and julia has no mechanism to handle platform dependent, we cannot have Oscar in the Project.toml. Hence in the CI script we inject this dependency by hand if Oscar is available. The tests themselves are behind a Sys.iswindows() and try using Oscar check.

[Fe-r-oz]

Thank you, this is wonderful!

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 20 lines in your changes missing coverage. Please review.

Project coverage is 82.63%. Comparing base (75e5fe9) to head (c310abc).

Files with missing lines	Patch %	Lines
ext/QuantumCliffordOscarExt/direct_product.jl	0.00%	5 Missing ⚠️
ext/QuantumCliffordOscarExt/group_presentation.jl	0.00%	5 Missing ⚠️
src/ecc/codes/twobga_ext/direct_product.jl	0.00%	5 Missing ⚠️
src/ecc/codes/twobga_ext/group_presentation.jl	0.00%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #400      +/-   ##
==========================================
- Coverage   83.46%   82.63%   -0.84%     
==========================================
  Files          72       72              
  Lines        4813     4819       +6     
==========================================
- Hits         4017     3982      -35     
- Misses        796      837      +41     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Fe-r-oz]

Should we include the test files that require Oscar methods, like those in #398, #397, #390, within the @static if !Sys.iswindows() macro, or would it be more appropriate to use this macro inside the test files that require Oscar?

Thank you for your time!

[thofma]

Since we use these @testitems, it would be easier to add a tag to them and filter them in the runtest.jl file. I can help with that, but without #400 this won't work, since there are more things required in the CI setup.

[Krastanov]

This looks really great! I have a bit of a backlog of reviews, so I will probably not be able to merge this until late next week, but I am very grateful you guys spent time on providing something so neatly polished here.

@royess , if you have a chance, could you also check this out, as it is building upon a lot of the infrastructure you contributed.

[Fe-r-oz]

@Krastanov, We have identified an inconsistency in the implementation of the two_block_group_algebra_codes. This issue has been independently verified through three distinct approaches, all of which confirm its existence. Tommy's feedback has been incredibly helpful in cross-checking the three distinct approaches used to reproduce this inconsistency. For further context, please refer to the details documented in issue #405.

As a result, we have temporarily removed the additional functionality for the semidirect product of groups from the PR we introduced today. We plan to reintroduce this feature once the inconsistency is resolved, as it is unrelated to this PR.

[royess]

@royess , if you have a chance, could you also check this out, as it is building upon a lot of the infrastructure you contributed.

I would like to help but perhaps not very soon. I will aim to do that next week.

[Fe-r-oz]

Changelog:

• New QuantumCliffordOscarExt Features:
  • Enhanced CI by injecting Oscar.jl into the test runner when available, due to its lack of support on Windows, with tests conditioned using Sys.iswindows() to check for Oscar.jl’s availability.
  • Implemented twobga_from_fp_group to support finitely presented groups via specific group presentations for 2BGA codes.
  • Implemented twobga_from_direct_product to support direct product of general groups for 2BGA codes.

The mermaid diagram included in documentation for specific group presentations via Finitely Presented Groups:

graph TD
    A[Group Presentation <br> ⟨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⟩"]

Loading

[Krastanov]

Thanks folks! As I am reading through this, I have a couple of background questions about the Oscar/Hecke ecosystem (of which I know very little):

• What does Oscar provide that is not in Hecke? Why is it necessary? I am not knowledgeable of that ecosystem.

• Why list notation instead of just a sum? E.g. why [one(GA), x^7] instead of one(GA) + x^7 -- the later seems simpler to read to me and the only operation that seems to be done on the list is to sum it.

• QuantumCliffordOscarExt.twobga_from_direct_product introduced here seems almost identical to the already existing QuantumCliffordHeckeExt.two_block_group_algebra_codes. Semantically, why should they be two different functions?

• I see that Oscar 1.2 was recently released. Does that mean that the tests can now also run on Windows?

[Krastanov]

I see that the mermaid diagram by Feroz above seems to be in the direction of answering my first question, but I do not really understand the context of it. Some examples of something inconvenient/impossible in Hecke but easy/possible in Oscar would be very helpful.

[thofma]

Hecke contains only abelian groups and a list of all finite groups of order up to 100. Oscar brings in comprehensive functionality for computational group theory, including support for arbitrary finitely presented groups (groups of the form $\langle X | S \rangle$).

Regarding Oscar 1.2, Windows support is still lacking (and will so for the foreseeable future), but at least starting with julia -t n with n > 1 does not make Oscar crash during loading.

[Fe-r-oz]

QuantumCliffordOscarExt.twobga_from_direct_product introduced here seems almost identical to the already existing QuantumCliffordHeckeExt.two_block_group_algebra_codes. Semantically, why should they be two different functions?

As Tommy pointed out, Hecke currently supports only abelian groups and a list of finite groups. The direct products I introduced in QuantumCliffordHeckeExt were only of the form abelian_group([l, m]) or abelian_group([l, l, l]).

Oscar provides functionality of designing specific group presentations when we have a finite group formed by direct product of two or more subgroups or semidirect product of two or more subgroups as depicted by the mermaid diagram. There are even cases of finite groups when we have group C x (C : C) where : means semidirect products whose group presentation we can conveniently design using Oscar. PR #406 highlights this limitation in Hecke, where it becomes inconvenient/impossible to create specific group presentations $\langle X \mid S \rangle$ even for two cyclic groups.

Oscar provides convenient access to non-abelian groups such as alternating_group, dihedral_group and operations like direct_product and semidirect_product between them. The paper employs direct_product between the alternating_group and a cyclic group (A4), which is also referenced in the ECC Zoo under 2BGA codes: ECC Zoo 2BGA codes. Lin and Pryadko also use the semidirect_product between two cyclic groups, which is why the cyclic_group from Oscar is required.

The key difference is that QuantumCliffordOscarExt.twobga_from_direct_product computes the direct product of two or more general groups, such as A4 x C2or D12 x C2, where A is the Oscar.alternating_group, D is the Oscar.dihedral_group, etc. With twobga_from_direct_product , we offer comprehensive documentation and implementation for accurately computing the direct product of two general groups, ensuring that the presentation $\langle X \mid S \rangle$ is satisfied and that the two subgroups indeed form a valid group. Many thanks to Tommy for providing numerous helpful tips in the documentation.

In addition, Oscar also supports homomorphisms hom between free modules, which are necessary for the intersection of two kernels, ker(Hx) ∩ ker(Hz). This calculation is helpful in computing code_k for quantum LDPC codes.

Since 2BGA codes require a finite general group (specifically, Oscar.FPGroup with a specific group presentation), they presently lack the necessary completeness by definition.

Edit:

Future prospects: There has been a growing interest in non-Abelian codes, particularly Dihedral Quantum Codes, which offer promising opportunities for new software bounty projects. Recent papers, such as Dihedral Quantum Codes, highlight these developments. Oscar provides a comprehensive toolkit to support this exploration. Additionally, there has been a notable focus on Dihedral group algebra in recent research. One such paper discusses the use of the direct product between dihedral and cyclic groups, as detailed in [Direct Product Group Codes and Derived Quantum Codes]. Oscardirect_productoffers this functionality for users who intend this implement the approach outlined in the aforementioned paper. The abstract mentions direct product of general groups such as D x D or D x C.

Why list notation instead of just a sum? E.g. why [one(GA), x^7] instead of one(GA) + x^7 -- the later seems simpler to read to me and the only operation that seems to be done on the list is to sum it.

To my knowledge, 'non-list' notation is not supported for FPGroups, but Tommy would know best. We form a list of group algebra elements and then take the sum as shown below:

Sharing Tommy's insights from earlier discussions in #391:

julia> using Oscar

julia> F = free_group(["r", "s"]);

julia> r, s = gens(F);

julia> G, = quo(F, [s^4, r^9, s^(-1)*r*s*r]); # specific group presentations are supported for finitely presented groups

julia> describe(G) # semidirect product  between cyclic groups is supported by Oscar
"C9 : C4"

julia> small_group_identification(G)
(36, 1)

julia> F2G = group_algebra(GF(2), G);

julia> r, s = gens(G); # for less typing

julia> b_elts = [one(G), s, r^6, s^3 * r, s * r^7, s^3 * r^5];  # list notation

julia> b = sum(F2G(x) for x in b_elts); # the sum of the list of group algebra elements (FPGroupElem)

julia>  # ------------------------------------------------------------------------------------
julia> b_elts = 1 +  s + r^6 +  s^3 * r + s * r^7 +  s^3 * r^5; # non-list notation is not supported for FPGroups
ERROR: MethodError: no method matching +(::Int64, ::FPGroupElem)
The function `+` exists, but no method is defined for this combination of argument types.

Closest candidates are:
  +(::Any, ::Any, ::Any, ::Any...)
   @ Base operators.jl:596
  +(::Oscar.StraightLinePrograms.Lazy, ::Any)
   @ Oscar ~/.julia/packages/Oscar/2lR8w/src/StraightLinePrograms/lazy.jl:98
  +(::Any, ::Oscar.StraightLinePrograms.Lazy)
   @ Oscar ~/.julia/packages/Oscar/2lR8w/src/StraightLinePrograms/lazy.jl:99
  ...

Stacktrace:
 [1] +(::Int64, ::FPGroupElem, ::FPGroupElem, ::FPGroupElem, ::FPGroupElem, ::FPGroupElem)
   @ Base ./operators.jl:596
 [2] top-level scope
   @ REPL[9]:1

Moreover, the list notation is used in bicycle_codes, generalized_bicycle_codes and haah_cubic_codes as well where we pass a_shifts, and b_shifts such as c = haah_cubic_codes([0, 15, 20, 28, 66], [0, 58, 59, 100, 121], 6).

QuantumClifford.jl/ext/QuantumCliffordHeckeExt/lifted_product.jl

Line 308 in ce1dc02

a = sum(GA[n÷l+1] for n in a_shifts)

QuantumClifford.jl/ext/QuantumCliffordHeckeExt/lifted_product.jl

Lines 294 to 295 in ce1dc02

	a = sum(GA[n%l+1] for n in a_shifts)
	b = sum(GA[n%l+1] for n in b_shifts)

QuantumClifford.jl/ext/QuantumCliffordHeckeExt/lifted_product.jl

Lines 330 to 331 in ce1dc02

	a = sum(GA[n%dim(GA)+1] for n in a_shifts)
	b = sum(GA[n%dim(GA)+1] for n in b_shifts)

[Fe-r-oz]

With reference to your third question, we have prepared the following mermaid diagram to illustrate the differences.

graph TB
    root[Direct Product of Groups]
   
    root --> A[Hecke.direct_product]
    root --> B[Oscar.direct_product]
   
    %% Hecke Branch
    A --> A1[Supports mostly abelian groups and list of finite groups]
    A1--> A2[abelian_group symmetric_group small_group]
    A2 --> A3[C × C, C × S]

    %% Oscar Branch
    B --> B1[Supports finite general groups, including non-abelian groups]
    B1--> B2[alternating_group <br> dihedral_group <br> free_group <br> cyclic_group <br> permutation_group <br>  quaternion_group <br> symmetric_group <br> abelian_group<br> small_group]
    B2--> B3[A × C,  A × D <br> D × C, D × D <br> F × F, F × A, F × D <br> F × S, F × C <br> C × C, C × S]

Loading

Additionally, to reiterate Tommy's point, the order of the groups supported by Oscar is substantially larger. In this example, the order of the direct product of two finite groups is ten times 100.

julia> using Oscar

julia> F = free_group(["r", "s"]);

julia> r, s = gens(F);

julia> G, = quo(F, [s^4, r^9, s^(-1)*r*s*r]);

julia> grp = direct_product(G, G); # direct product of two finitely presented groups

julia> order(grp)
1296

[Fe-r-oz]

Future prospects: There has been a growing interest in non-Abelian codes, particularly Dihedral Quantum Codes. Recent papers, such as Dihedral Quantum Codes, highlight these developments. Oscar provides a comprehensive toolkit to support this exploration. Additionally, there has been a notable focus on Dihedral group algebra in recent research. One such paper discusses the use of the direct product between dihedral and cyclic groups, as detailed in [Direct Product Group Codes and Derived Quantum Codes].

@Krastanov, I am thrilled to share the latest paper (posted Dec 12, 2024) Codes in algebras of direct products of groups and associated quantum codes that constructs the Group codes arising from $\mathbb{F}_q[D_n \times C_t]$ and $\mathbb{F}_q[D_n \times D_m]$ where D is the dihedral_group and C is the cyclic_group. Oscar.direct_product supports these capabilities as mentioned in the aforementioned mermaid schematic!

Edit: Section 4.1 of this paper provides a nice application of specific group presentations with additional relations. For instance, the paper uses the following group presentations for the dihedral and cyclic groups:

• $D_n = \langle x, y \mid x^n = y^2 = 1, y^{-1}xy = x^{-1} \rangle$
• $D_m = \langle c, d \mid c^m = d^2 = 1, dcd = c^{-1} \rangle$ along with the group algebra $\mathbb{F}_3[D_n \times D_m]$.

Additionally, it considers:

• $D_n = \langle x, y \mid x^n = y^2 = 1, y^{-1}xy = x^{-1} \rangle$
• $C_t = \langle z \mid z^t = 1 \rangle$ with the group algebra $\mathbb{F}_3[D_n \times C_t]$.

[Fe-r-oz]

@royess , if you have a chance, could you also check this out, as it is building upon a lot of the infrastructure you contributed.

Dear @royess, I hope this message finds you well! If you have time, kindly please review this PR as well. That would be fantastic! It builds upon a lot much of the excellent infrastructure you contributed in #356, so your insights and perspective would be incredibly valuable here. Thank you so much for your time—I truly appreciate it!

Dear @Krastanov, I hope this message finds you well! My apologies—I realize I should have sent this note before formally submitting the review request. Clicking "Request Review" days ago first made this message feel like an afterthought and unprofessional, and I sincerely regret the awkward sequencing. I hope the oversight hasn’t caused any inconvenience. Thank you!! Edit: I forgot to mention that I greatly appreciated the amazing questions in #400 (review)!

[Krastanov]

Apologies for all the noise over the last day -- we had recently started partitioning part of the library and that messed up the CI. Given that this PR also was introducing non-trivial CI logic, it seemed like a good place to fix it.

Also apologies for taking so long to review this. @thofma thank you for the domain expertise -- this might or might not be a very simple use of Oscar, but this type of use is extremely hot among quantum information science researchers right now, and barely anyone has previous domain expertise, so we are all stumbling in the dark a bit. You and your team should definitely consider advertising Oscar in a few QIS conferences -- there would be great deal of interest.

Thanks, Feroz for spearheading this!

[Krastanov]

@nzy1997 , the CI issue I tagged you about is (mostly?) fixed in this PR. Pardon the noisy tags.