Optionally reuse flows for anti-commuting covers

[inmzhang]

This issue is found by one of my colleagues (Weiping Lin).

For the following circuit:

QUBIT_COORDS(0, 0) 0
QUBIT_COORDS(1, 0) 1
QUBIT_COORDS(2, 0) 2
R 0 1 2
TICK
CX 1 0
TICK
CX 1 2
TICK
MX 1
TICK
M 0 2

There should be two detectors DETECTOR rec[-1] and DETECTOR rec[-2]. However, annotate_detectors_automatically returns a single detector DETECTOR rec[-1] rec[-2]. This is because in

tqecd/src/tqecd/flow.py

Lines 90 to 93 in 7e47c39

	# Update the flows by removing the entries related to stabilizers that
	# will be merged and re-compute the anti-commuting stabilizers and map.
	for i in sorted(flows_indices_of_stabilizers_to_merge, reverse=True):
	flows.pop(i)

Every used flow is immediately removed and cannot be used anymore.

This PR adds an option to reuse the flows for further anticommuting cover opportunities. It's achieved by removing a single flow instead of all the flows each time. Note that it will significantly increase the runtime when this option is on but it enables more opportunities to find complete detectors.

[github-actions]

Package	Line Rate	Complexity	Health
src.tqecd	93%	0	✔
src.tqecd.match_utils	91%	0	✔
Summary	93% (787 / 847)	0	✔

[github-actions]

A preview of e50278f is uploaded and can be seen here:

✨ https://tqec.github.io/tqecd/pull/37/ ✨

Changes may take a few minutes to propagate.

[HaoTy]

Will try to review this PR over the weekend. Once we make the performance improvements to cover finding and the Pauli string, the overhead should be largely mitigated.

[Copilot]

Pull request overview

This PR adds an opt-in mode to the detector-finding pipeline that allows reusing stabilizer flows when forming commuting stabilizers from anti-commuting ones, enabling additional detector extraction in cases where the previous “consume all used flows” behavior prevented finding complete detector sets.

Changes:

• Add reuse_flows_for_anticommuting_cover option to the public annotate_detectors_automatically API and propagate it through fragment compilation and detector matching.
• Extend flow merging (try_merge_anticommuting_flows) to optionally remove only one contributing flow per merge instead of all contributing flows.
• Add a regression test covering the reported circuit and verifying the detector count difference with/without reuse enabled.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/tqecd/match.py	Threads the new reuse option into boundary stabilizer matching and anti-commuting merge step.
src/tqecd/flow.py	Adds reuse_flows parameter to anti-commuting merge logic and modifies removal behavior.
src/tqecd/construction.py	Exposes the option on annotate_detectors_automatically and propagates it through compilation (including loop recursion).
src/tqecd/construction_test.py	Adds a regression test for the reported circuit behavior under the new option.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[HaoTy]

My apologies for the delay! With the Gaussian-elimination-based flow matching currently in main, the added test fails due to the flow order being different from the SAT-based matching. flows.pop(flows_indices_of_stabilizers_to_merge[-1]) takes an arbitrary choice and does not guarantee it's a suitable one.