Implement balanced product codes #318

ryan-kersten · 2025-08-04T19:18:31Z

Closes #305

The main computational complexity in implementing this code was finding permutation R and C where
RM=MC^t for a matrix M, where R and C have an orbit of length L. I've never used GAP before, is there any better way to find these permutations than using 'filtered' to find all the symmetry group elements of a certain order?

Uses GAP to find all permutations of a matrix that have an orbit of a certain length

Add an option to add padding/fixed points to a permutation matrix returned by to_matrix

These lines can never run

ryan-kersten · 2025-08-05T02:16:45Z

Sorry about the somewhat messy git history- I had a bunch of type check issues and mocking issues that were a little ugly. I typically develop things in c++, contributing in python is new to me and I still have a lot to learn :)

Should be in a good state now

perlinm · 2025-08-05T02:19:27Z

No worries, the effort to pass all checks is greatly appreciated!

perlinm · 2025-08-06T06:37:33Z

Hmm, maybe if it takes a long time to find suitable R and C, and moreover the choice of these matrices is not unique, we should make them inputs to the code (and test validity/compatibility at initialization time). We can then provide tools for finding suitable choices of R and C, and provide example code in the docstring for BalancedProductCode.

Also, maybe it would be nice to add an alternative construction based on Eq 4 on page 7 of arXiv:2505.13679? Something like a BalancedProductCode.from_codes(code_q: codes.CSSCode, code_c: codes.ClassicalCode).

ryan-kersten · 2025-08-06T23:29:53Z

Earlier, I was thinking of caching r and c across successive calls, but passing them as inputs makes much more sense.

While adding the alternate construction method, I realized it most of the work needed for the distance balancing feature from Section III. So I went ahead and implemented that too, although I set it to default to false since it involves calculating the distance of the input codes.

Uses better way to get number of encoded logical ops in a code

ryan-kersten · 2025-08-08T23:05:28Z

I implemented the new features and made tests for them. Is there anything else I can improve?

perlinm · 2025-08-09T02:39:56Z

Sorry for the delay! I'll take another look next week 🙂

perlinm

This is all awesome and looking good! I have just a few requests. I may do one more pass over this PR afterwards, but also at some point I'm happy to just merge and perform some additional cleanup myself 🙂

perlinm · 2025-08-13T19:43:24Z

qldpc/codes/quantum.py

+        R: qldpc.abstract.GroupMember,
+        C: qldpc.abstract.GroupMember,


Can we name these something like perm_r and perm_c and accept comb.Permutation | npt.NDArray[np.int_] inputs (with import sympy.combinatorics as comb)? I imagine many users will prefer to pass explicit permutation matrices. Initialization can convert these objects to matrices for validity checks as needed, e.g.

size = binaryMatrix.shape[0] mat_r = perm_r.to_matrix(size) if isinstance(perm_r, comb.Permutation) else perm_r

perlinm · 2025-08-13T19:44:39Z

qldpc/codes/quantum.py

+        self._r = R
+        self._c = C


Why not save the binaryMatrix to self while we're at it? (Also very minor: please rename to something like seed_matrix)

perlinm · 2025-08-13T19:50:33Z

qldpc/codes/quantum.py

+        check_z = np.hstack(
+            (np.eye(binaryMatrix.shape[1], dtype=int) + self._r.to_matrix(), binaryMatrix)
+        )
+        CSSCode.__init__(self, check_x, check_z)


Super nit: CSSCode.__init__(self, checks_x, checks_z, field=2, is_subsystem_code=False).

Also, I think we can make checks_z ~ [1 + R, -I] and add a field: int | None = None argument that we pass to CSSCode.__init__ as well. The construction seems to work equally well for arbitrary finite fields.

I agree with you on having an arbitrary field as an argument. Where do you get the alternative definition of checks_z with the negative?

That's just from me working out on scratch paper where I can put a minus sign to make this a valid CSS code, Hx @ Hz.T = 0 (in words, this condition simply enforces that X-type and Z-type stabilizers commute). We should do the same with the other BPCode construction. Note that the minus sign has no effect for qubits (binary matrices), for which -M = M.

perlinm · 2025-08-13T19:51:38Z

qldpc/codes/quantum.py

+    """
+    Allows for the creation of balanced codes from a classical code and a CSS code.
+
+    https://arxiv.org/pdf/2505.13679v1
+
+    If 'distance_balancing', function will determine if x and z errors have the same distance
+    and if not, will construct the code to maximize the final distance. This involve exact distance calculations
+    which will only work on relatively small codes
+
+    """
+
+    @classmethod
+    def from_codes(
+        cls, code_q: CSSCode, code_c: ClassicalCode, distance_balancing: bool = False
+    ) -> qldpc.codes.BalancedProductCode:


Please move the docstring inside the method:

Suggested change

"""

Allows for the creation of balanced codes from a classical code and a CSS code.

https://arxiv.org/pdf/2505.13679v1

If 'distance_balancing', function will determine if x and z errors have the same distance

and if not, will construct the code to maximize the final distance. This involve exact distance calculations

which will only work on relatively small codes

"""

@classmethod

def from_codes(

cls, code_q: CSSCode, code_c: ClassicalCode, distance_balancing: bool = False

) -> qldpc.codes.BalancedProductCode:

@classmethod

def from_codes(

cls, code_q: CSSCode, code_c: ClassicalCode, distance_balancing: bool = False

) -> qldpc.codes.BalancedProductCode:

"""Construct a balanced product code from a quantum CSS code and a classical code.

If 'distance_balancing', this function will determine if x and z errors have the same distance

and if not, it will construct the code to maximize the final distance. This involve exact distance calculations

which will only work on relatively small codes.

See Eq. (4) of https://arxiv.org/pdf/2505.13679v1

"""

perlinm · 2025-08-13T19:53:38Z

qldpc/external/groups.py

+
+
+def get_permutation_symmetry_of_matrix(
+    symmetry_length: int, n: int, m: int


Can we give n and m descriptive names? Also, again the docstring should go inside the function.

perlinm · 2025-08-13T19:55:49Z

qldpc/external/groups.py

+    def parse_permutation_output(output: str) -> list[qldpc.abstract.GroupMember]:
+        perm_list = []
+        for perm in output.strip("[] ").split(", "):
+            result = []
+            cycles = re.findall(r"\([^()]+\)", perm)
+            for cycle in cycles:
+                cycle = cycle.strip("()")
+                elements = tuple(int(x) - 1 for x in cycle.split(","))
+                result.append(elements)
+            # Remove trivial permutation
+            if result:
+                perm_list.append(qldpc.abstract.GroupMember.from_sympy(Permutation(result)))
+        return perm_list


Is this performing the same parsing as in this code? If so, can we factor it out into a common function?

perlinm · 2025-08-13T19:59:05Z

qldpc/abstract.py

-        matrix = np.zeros([self.size] * 2, dtype=int)
+        size = dimension if dimension is not None else self.size
+        matrix = np.eye(size, dtype=int)
        for ii in range(self.size):
-            matrix[ii, self.apply(ii)] = 1
+            j = self.apply(ii)
+            # Since using identity matrix not zero, have to clear the row
+            matrix[ii, :] = 0
+            matrix[ii, j] = 1
+


Let's keep the old construction and do something like

if dimension > len(matrix): matrix = scipy.linalg.block_diag(matrix, np.eye(dimension - len(matrix), dtype=int) return matrix

And maybe dimension should be size?

perlinm · 2025-08-13T20:02:08Z

It looks like there are also conflicts that prevent automatic merging into main. I haven't taken a look at these conflicts, but I'm happy to help if they turn out to be thorny.

perlinm · 2025-08-14T13:24:21Z

Oh also: in keeping with naming conventions for quantum codes in qldpc, can you please rename the BalancedProductCode class to BPCode?

ryan-kersten · 2025-08-16T09:58:52Z

Thanks for the comments! I have time this weekend, so I should have everything good by Monday.

perlinm · 2025-08-29T13:05:12Z

@ryan-kersten could you please make a checklist of your main todo's for this PR? That way somebody else can take over to finish the PR in the future if it turns out that you don't have the time 🙂

perlinm · 2025-09-20T19:56:28Z

@ryan-kersten alternative request: to open the same PR but from a branch of this repository. That way I can finish it up.

ryan-kersten requested a review from perlinm as a code owner August 4, 2025 19:18

ryan-kersten force-pushed the balenced-product branch 2 times, most recently from a3e2d5b to e092a47 Compare August 4, 2025 21:19

ryan-kersten added 10 commits August 4, 2025 21:09

Find permutations of matrix

7c676e8

Uses GAP to find all permutations of a matrix that have an orbit of a certain length

Add tests for permutation finding

87b6c40

Add dim option to Groupmember.to_matrix

4a5ae49

Add an option to add padding/fixed points to a permutation matrix returned by to_matrix

Core functionality of balanced product code

a6edd42

Tests for balanced product code

6c47e0e

Add balanced product code to init

756d992

Fix mocking in gap test

b830766

Fix coverage

a95a95d

Fixed formatting+mocking

ee3bc47

Fix coverage

fff6fc3

These lines can never run

ryan-kersten force-pushed the balenced-product branch from cded71a to fff6fc3 Compare August 5, 2025 02:11

ryan-kersten added 7 commits August 6, 2025 10:30

Split up finding perms and balanced code

51e39c0

Moved balance code tests around

04d8f9c

Alternative balanced code creation

744eb74

Add balanced code tests

709c2dd

Add distance balancing

d6c95da

Distance balancing tests

5ba3f44

Formatting fixes + docs

69c3af3

ryan-kersten added 4 commits August 6, 2025 18:57

Coverage fix

4885a77

Fix coverage

9c3fc5d

Fix tests

36b6ed9

Uses better way to get number of encoded logical ops in a code

add more doc for permutation fnx

43d1716

perlinm requested changes Aug 13, 2025

View reviewed changes

ryan-kersten added 5 commits August 16, 2025 07:46

Rename to BPCode

df50480

Rename binaryMatrix

bcdf09d

Fix doc strings

8e60117

Restore original to_matrix

ece3773

Parsing GAP generator out fnx

bca4dfa

Basic Color codes

7d528ef

		R: qldpc.abstract.GroupMember,
		C: qldpc.abstract.GroupMember,



		def get_permutation_symmetry_of_matrix(
		symmetry_length: int, n: int, m: int

Implement balanced product codes #318

Are you sure you want to change the base?

Implement balanced product codes #318

Uh oh!

Conversation

ryan-kersten commented Aug 4, 2025

Uh oh!

ryan-kersten commented Aug 5, 2025

Uh oh!

perlinm commented Aug 5, 2025

Uh oh!

perlinm commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ryan-kersten commented Aug 6, 2025

Uh oh!

ryan-kersten commented Aug 8, 2025

Uh oh!

perlinm commented Aug 9, 2025

Uh oh!

perlinm left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

perlinm Aug 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

perlinm commented Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

perlinm commented Aug 14, 2025

Uh oh!

ryan-kersten commented Aug 16, 2025

Uh oh!

perlinm commented Aug 29, 2025

Uh oh!

perlinm commented Sep 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

perlinm commented Aug 6, 2025 •

edited

Loading

perlinm left a comment •

edited

Loading

perlinm Aug 17, 2025 •

edited

Loading

perlinm commented Aug 13, 2025 •

edited

Loading