Reimplement flow matching using Gaussian elimination by HaoTy · Pull Request #45 · tqec/tqecd

HaoTy · 2026-02-26T05:03:34Z

Flow matching is a major bottleneck of tqecd's performance and scalability. The matchings are solved by (SAT-solver-accelerated) brute force in main. This PR reimplements the functions in match_utils/cover.py to solve them efficiently using Gaussian elimination over GF(2), which partly addresses #2.

The solution's minimal-count requirement needed to be relaxed, but I don't think it fundamentally affects anything. All tqecd tests pass, and all tqec tests (including tests marked as slow) pass with do_not_use_database=True.

Benchmarking using a script adapted from tqec/tqec#356 (comment) shows that both the constant factor and scalability are drastically improved:

from time import perf_counter

from tqec import Basis, compile_block_graph
from tqec.gallery import memory

from tqecd import annotate_detectors_automatically


def format_timings(ks: list[int], timings: list[float]) -> str:
    return (
        "k        |"
        + " , ".join(f"{k:>6}" for k in ks)
        + "\ntime (s) |"
        + " , ".join(f"{t:6.3f}" for t in timings)
    )

block_graph = memory(Basis.Z)
compiled_graph = compile_block_graph(block_graph)

ks: list[int] = list(range(1, 10))
times: list[float] = []

for k in ks:
    circuit = compiled_graph.generate_stim_circuit(k=k, manhattan_radius=-1)
    start = perf_counter()
    annotate_detectors_automatically(circuit)
    end = perf_counter()
    times.append(end - start)

print("Time to annotate detectors:")
print(format_timings(ks, times))

This PR:

Time to annotate detectors:
k        |     1 ,      2 ,      3 ,      4 ,      5 ,      6 ,      7 ,      8 ,      9
time (s) | 0.009 ,  0.034 ,  0.089 ,  0.209 ,  0.421 ,  0.799 ,  1.371 ,  2.294 ,  3.481

main:

Time to annotate detectors:
k        |     1 ,      2 ,      3 ,      4 ,      5 ,      6 ,      7 ,      8 ,      9
time (s) | 0.014 ,  0.047 ,  0.339 ,  1.685 ,  3.606 ,  5.975 ,  9.122 , 13.128 , 18.237

Note that these improvements will not lead to a significant speedup in the detector annotation of tqec's ZX cubes, as they use the detector database and subtemplates to confine detector findings to small subcircuits. However, it is expected to benefit circuits that lack a nice subtemplate partitioning, such as cultivation and Y initialization/measurement. They should also benefit #37.

A bonus is that the SAT solver dependencies can be removed (included in this PR), making tqecd easily installable on platforms without a precompiled binary.

The int-based efficient Gaussian elimination infrastructure is borrowed from my implementation in https://github.com/tqec/tqec/blob/main/src/tqec/computation/_correlation.py.

…into enhance/flow-matching

smburdick

Mostly documentation related.

smburdick · 2026-04-13T20:15:27Z

+
+
+def _solve_linear_system(
+    basis: dict[int, tuple[int, int]], x: int, update_basis: bool = True


Might want to define a Basis type or class somewhere, just to make it clear what the valid keys/values are, kind of like what's in tqec.

smburdick · 2026-04-13T20:21:26Z

+    """Try to find a set of boundary stabilizers from ``sources`` that generate a
+    superset of ``target``.
+
+    This function try to find a set of Pauli strings from ``sources`` that


typo: "This function tries to find ..."

smburdick · 2026-04-13T20:21:46Z

+    superset of ``target``.
+
+    This function try to find a set of Pauli strings from ``sources`` that
+    includes ``target`` (i.e., on every qubit where ``target`` is non-trivial,


What is a trivial target?

Non-identity

smburdick · 2026-04-13T20:22:27Z

+    the product of each of the returned Pauli strings should commute with
+    ``target``).
+
+    The differences with :func:`find_cover` are:


Would find_noncommuting_cover be a valid name for find_cover?

The method names are somewhat legacy from the previous implementation. Now after simplification, it's clear that they only differ by how they treat the involved qubits and edge cases. I will think about whether the naming could be improved.

smburdick · 2026-04-13T20:23:41Z

+
+    If multiple valid covers exist, the covers involving the lowest number of
+    :class:`~tqecd.pauli.PauliString` instances from ``sources`` are listed, and
+    a random cover is picked from that list.


Why not just return all of the covers?

Because there are exponentially many of them, and they don't really make a difference. But this doc describes the previous behavior and is inaccurate now. Will fix.

smburdick · 2026-04-13T20:32:30Z

+def find_exact_cover(
+    target: PauliString, sources: list[PauliString]
+) -> list[int] | None:
+    """Try to find a set of pauli strings from ``sources`` that generate exactly


*Pauli strings

smburdick · 2026-04-13T20:33:29Z

+    """Try to find a set of pauli strings from ``sources`` that generate exactly
+    ``target``.
+
+    The Pauli strings returned (via indices over the provided ``sources``), once


By the by, I noticed #47 , are you feeling the slowdown in this computation too?

This computation doesn't rely on the PauliString class too much, because Pauli strings are converted to ints. There could be a speedup for the conversion.

smburdick · 2026-04-13T20:37:07Z

@@ -1,15 +1,11 @@
 from __future__ import annotations


Do you think it's time to start moving the test files into their own directory

Not very critical, but yeah, something we can do.

smburdick · 2026-04-13T20:40:14Z

 [project]
 name = "tqecd"
-version = "0.1.3"
+version = "0.1.4"


Do we want to do a release?

Yes. Notice the reduced dependencies and the further implications.

smburdick · 2026-04-13T20:40:30Z

+    "numpy>=1.26; python_version >= '3.12'",
+    "numpy>=2.1; python_version >= '3.13'",
+    "stim>=1.15.0",
+]


Is dependabot needed for this repo?

I think there are some bots already? But admittedly, the CICD aspect is not as polished as tqec. Let's start by switching to uv, ty, and ruff and make the pyproject and GitHub action configurations more rigorous.

HaoTy · 2026-04-17T07:59:08Z

This PR is superseded by #51. I will fix the typos, etc. there.

This is a local version of #45 to avoid GitHub action permission issues when merging from a fork. --------- Co-authored-by: Copilot <copilot@github.com>

Pending tqec/tqecd#45. Bump tqecd dependency version; remove SAT solver dependencies; fix a typo in pyproject.toml.

HaoTy added 5 commits February 25, 2026 22:38

feat: reimplement flow matching using Gaussian elimination

3041b76

chore: remove sat-solver dependencies

7b2fffc

chore: update installation instructions

91268c7

chore: bump tqecd version and required Python version

99bf2ac

chore: move cover.py to the top-level module and remove match_utils

6ddaa3b

HaoTy mentioned this pull request Feb 26, 2026

Update tqecd-related dependencies tqec/tqec#849

Merged

chore: update CI

cc13aa1

HaoTy mentioned this pull request Feb 26, 2026

Improve the performance of automatic detector computation #2

Open

KabirDubey mentioned this pull request Feb 26, 2026

Implement Y basis initialization/measurement block tqec/tqec#719

Open

chore: fix some Python versions in CI

b2502aa

KabirDubey mentioned this pull request Feb 27, 2026

Support Y basis initialization/measurement circuits #48

Open

HaoTy mentioned this pull request Apr 8, 2026

Add conftest.py to increase timeouts for slow tests tqec/tqec#894

Open

HaoTy added 5 commits April 9, 2026 00:19

chore: keep the numpy version bound consistent with tqec

5e34260

feat: simplify to_int

49922d4

Merge branch 'main' into enhance/flow-matching

856a2e6

chore: remove requirements.txt from workflows

cd93591

Merge branch 'enhance/flow-matching' of https://github.com/HaoTy/tqecd …

97bc2fb

…into enhance/flow-matching

HaoTy mentioned this pull request Apr 11, 2026

Reimplement flow matching using Gaussian elimination (local merge) #51

Merged

smburdick reviewed Apr 13, 2026

View reviewed changes

HaoTy closed this Apr 17, 2026

HaoTy added a commit to tqec/tqec that referenced this pull request May 4, 2026

Update tqecd-related dependencies (#849)

b1a6953

Pending tqec/tqecd#45. Bump tqecd dependency version; remove SAT solver dependencies; fix a typo in pyproject.toml.



		def _solve_linear_system(
		basis: dict[int, tuple[int, int]], x: int, update_basis: bool = True

Conversation

HaoTy commented Feb 26, 2026

Uh oh!

smburdick left a comment

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!

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!

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!

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!

HaoTy commented Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants