Add mod2 utility module

[orisus42]

Description

This PR resolves #735
I added a mod2.py file at src/mqt/qecc/ which replaces the dependency on ldpc.mod2.mod2_numpy with an internal module mqt.qecc.mod2 implementing four functions that are currently used in the project:

• row_echelon
• rank
• nullspace
• row_basis

I replaced all the imports as well from the python files. Ran existing tests after replacing the imports which worked so I didn't add any new tests, but let me know if any new tests might be needed to verify functionality properly (EDIT: Added a test for full coverage of the changes). Removed some dead functionality from the functions as well like the scipy sparse matrix input because QECC only passes a plain np.ndarray everywhere.

Haven't yet added any QECC specific improvements like the mentioned StabilizerCode.compute_logical_ops() improvement in the issue but let me know if I should look into that for this PR.

AI Use Disclosure: I used Claude Code (Sonnet 4.6) to assist me with improving code quality, writing the docstrings and in general reviewing the logic of translating the mod2 functions from ldpc.mod2 to the internal QECC mod2 utilities module. The code logic and general structure is my own where Claude helped with removing unneeded functionality from the functions specific to QECC. Everything has been tested according to the contribution guidelines. No AI generated content has been used to write any portion of the PR description.

Checklist

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.
• I have disclosed the use of AI tools in the PR description as per our AI Usage Guidelines.
• AI-assisted commits include an Assisted-by: [Model Name] via [Tool Name] footer.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[orisus42]

I added a test that checks for a matrix with zero rows as it wasn't being covered by existing tests.

[denialhaag]

Hi, @orisus42! Thanks a lot for your interest in contributing to MQT QECC! 🙂

While scanning your PR, I noticed one detail, which you can find in the comment below.

I'll also go ahead and trigger a review by CodeRabbit now. We have a section in our documentation that explains a bit how to work with it: https://mqt.readthedocs.io/projects/qecc/en/latest/contributing.html#working-with-coderabbit

[denialhaag]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added built-in binary linear-algebra support for computing row reduction, rank, nullspaces, and row-space bases.
  • Updated quantum code and circuit synthesis workflows to use the new in-project implementation consistently.

• Tests

  • Added coverage for row-reduction behavior on empty matrices.

Walkthrough

Adds an in-repository mqt.qecc.mod2 module implementing GF(2) matrix operations, redirects existing callers from ldpc.mod2, and adds an empty-matrix row-echelon test.

Changes

GF(2) utility migration

Layer / File(s)	Summary
GF(2) linear-algebra implementation src/mqt/qecc/mod2.py	Adds row_echelon, rank, nullspace, and row_basis for binary matrices.
Consumer import migration src/mqt/qecc/analog_information_decoding/..., src/mqt/qecc/circuit_synthesis/..., src/mqt/qecc/codes/...	Redirects existing rank, row-echelon, nullspace, and related calls to mqt.qecc.mod2; sparse imports are reorganized where needed.
Empty-matrix validation tests/test_mod2.py	Tests zero-row row-echelon output, rank, pivots, and transformation shape.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• munich-quantum-toolkit/qecc#534: Updates related GF(2) mod2 import points for ldpc compatibility.

Suggested labels: dependencies, python

Suggested reviewers: burgholzer

Poem

I’m a rabbit with matrices, hopping in two,
GF(2) rows now live where the code grew.
Rank and nullspaces, neatly aligned,
Old imports depart, new helpers unwind.
Hop, hop—empty rows pass the test!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding an internal mod2 utility module.
Description check	✅ Passed	The description covers the change summary, motivation, linked issue, AI disclosure, and checklist items well enough.
Linked Issues check	✅ Passed	The PR implements the requested internal mod2 utilities module and removes the external ldpc.mod2 dependency as requested by #735.
Out of Scope Changes check	✅ Passed	The added tests and sparse-input cleanup align with the mod2 refactor and do not appear unrelated to the issue.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mqt/qecc/circuit_synthesis/transvection.py`:
- Line 18: The phase-1 kernel row selection in the transvection logic is brittle
because nullspace() does not guarantee row order. Update the code that uses the
kernel from mod2.nullspace() to explicitly find the row with a 1 in the last
column using np.where on the kernel matrix, and fail fast if no such row exists
instead of relying on ker[-1] or ker[-1, -1]. Use the relevant transvection
function and its kernel-handling logic to locate the change.

In `@src/mqt/qecc/mod2.py`:
- Line 17: Make the `full` parameter in `row_echelon` keyword-only to eliminate
the FBT001/FBT002 warning. Update the function signature in `row_echelon` so
`full` cannot be passed positionally, and keep the existing named callsites
working since they already use `full=`. Check any nearby helpers or overloads in
`mod2.py` to ensure the API remains consistent with `row_echelon`.

In `@tests/test_mod2.py`:
- Around line 17-25: Add direct coverage for mqt.qecc.mod2 beyond row_echelon by
creating tests that call rank, nullspace, and row_basis from the internal module
instead of only exercising ldpc.mod2.mod2_numpy. Use the existing
row_echelon-style test file as the place to add a few small, deterministic
cases, and verify each function’s expected output shape/content for simple
matrices so the internal implementation is directly tested.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 159743b9-223b-44ca-a751-8d38bf59ce1b

📥 Commits

Reviewing files that changed from the base of the PR and between 7d5a4b2 and 3a0b65a.

📒 Files selected for processing (15)

• src/mqt/qecc/analog_information_decoding/code_construction/code_constructor.py
• src/mqt/qecc/analog_information_decoding/code_construction/sparse_code_constructor.py
• src/mqt/qecc/analog_information_decoding/utils/simulation_utils.py
• src/mqt/qecc/circuit_synthesis/cnot.py
• src/mqt/qecc/circuit_synthesis/encoding.py
• src/mqt/qecc/circuit_synthesis/faults.py
• src/mqt/qecc/circuit_synthesis/state_prep.py
• src/mqt/qecc/circuit_synthesis/state_prep_det.py
• src/mqt/qecc/circuit_synthesis/strategy.py
• src/mqt/qecc/circuit_synthesis/transvection.py
• src/mqt/qecc/codes/css_code.py
• src/mqt/qecc/codes/pauli.py
• src/mqt/qecc/codes/stabilizer_code.py
• src/mqt/qecc/mod2.py
• tests/test_mod2.py

[denialhaag]

I breifly cleaned up the types in 76b73ec. LGTM now! @lsschmid, feel free to merge! 🙂

[orisus42]

I see that a bunch of fixes have been made! I apologize for not looking at review comments earlier, got caught up in something. If there's anything else needed for this PR, let me know!

[lsschmid]

Hey @orisus42! yes, I did some final fixes and cleanups on your changes, so it's ready to be merged.
Thanks again a lot for contributing! This is really appreciated!

If you are interested, you can also take a look into other issues of we can also have a chat about other ideas/ways to contribute (also maybe something more interesting/practical than this refactor) 👍

[lsschmid]

If you are interested, just drop me an email: ludwig.s.schmid@tum.de