Extract Pauli flow from XZ-corrections (closes #432)

[Vinny010]

Closes #432.

Implements XZCorrections.to_pauli_flow and the convenience method Pattern.extract_pauli_flow (analogous to extract_causal_flow / extract_gflow), reconstructing a Pauli flow directly from the pattern's XZ-corrections (Theorem 4 of Browne et al. 2007) rather than from the underlying open graph — whose Pauli flow is not unique and is not guaranteed to generate the pattern.

How the anachronical corrections were tackled (the crux of the issue)

The hard part, as the issue notes, is that a Pauli flow's correction sets may contain anachronical corrections: corrections targeting X/Y Pauli-measured nodes that lie in the present or past of the corrected node. PauliFlow.to_corrections discards these (the correcting_set & future filter), so they never appear in the pattern and cannot be read off the corrections — they must be reconstructed.

For each measured node i, reconstruction is cast as a linear system over GF(2):

• Pinned future part. For nodes in the future of i, membership in the correction set p(i) is fixed by the observed X-corrections of i (and must reproduce the Z-corrections via the odd neighbourhood). These become constants of the system.
• Free anachronical variables. The unknowns are exactly the anachronical candidates — non-future nodes measured along the X or Y axes (permitted in p(i) by P1) — and, where the local proposition allows it, i itself.
• Equations. The odd-neighbourhood constraints: the Z-corrections on the future nodes, the vanishing of the odd neighbourhood on past non-(Y/Z) nodes (P2), the membership/odd-neighbourhood coupling on past Y nodes (P3), and the local proposition on i (P4–P9, handling the XY/XZ/YZ planes and the X/Y/Z axes).

The system is solved with a small GF(2) Gaussian-elimination helper (_solve_gf2); failure to solve at any node means no Pauli flow is compatible with the corrections. The resulting flow is then validated by PauliFlow.check_well_formed.

Correctness

The decisive check is the round trip: for the reconstructed pf, pf.to_corrections() must reproduce the pattern's X- and Z-corrections exactly (this is what guarantees it generates this pattern). Tests verify well-formedness and the round trip on:

• the three worked examples of the issue (causal, gflow and Pauli; the reconstructed correction functions match the expected p(0) = {1, 3}, p(1) = {2}, p(2) = {3} etc., including the anachronical node 1),
• a Pauli-measured open graph, and
• a randomized family of open graphs that admit a Pauli flow.

There are also unit tests for the GF(2) solver. Passes ruff, mypy --strict, pyright, and pytest locally (new tests plus the existing flow / open-graph / pattern suites).

Developed with LLM assistance, reviewed and tested by me.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.08%. Comparing base (fcdb8f4) to head (926197a).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #526      +/-   ##
==========================================
+ Coverage   88.85%   89.08%   +0.23%     
==========================================
  Files          49       49              
  Lines        7135     7240     +105     
==========================================
+ Hits         6340     6450     +110     
+ Misses        795      790       -5     

☔ View full report in Codecov by Harness.
📢 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.

[thierry-martinez]

Thank you very much for this clean solution. Here are my initial comments on your PR.

[thierry-martinez]

There is already a GF(2)-linear-system solver implemented in _linalg.solve_f2_linear_system.

[thierry-martinez]

Why do you choose to apply round there rather than leave the random float unchanged?

[thierry-martinez]

What are the relevant exceptions here? We should at least catch OpenGraphError. Are there any others?

[thierry-martinez]

Is it possible to fail at this point? Can you give an example where the correction_function isn’t well‑formed by construction?

[Vinny010]

Thanks for the thoughtful review, @thierry-martinez! Pushed 9a73dc7 addressing each point:

• _linalg.solve_f2_linear_system reuse — good catch. Switched to it. The per-node augmented matrix [A | b] is reduced to row echelon form with MatGF2.gauss_elimination(ncols=n_vars) (which propagates the row operations to the RHS column), inconsistency is detected by scanning for a [0…0 | 1] row, and the reduced system is then handed to the existing solver. _solve_gf2 is removed.
• round on the random angle — purely cosmetic (kept the test failure messages readable when I was iterating). Dropped.
• Exception narrowing in the randomized test — narrowed to OpenGraphError, which is the only documented raise condition of OpenGraph.to_pattern when no flow exists.
• pf.check_well_formed() on line 311 — by construction the GF(2) equations of _reconstruct_pauli_correction_function encode P2–P9 exactly, and restricting the anachronical candidates to X/Y-measured nodes guarantees P1; the general flow properties are satisfied by construction too. So I cannot construct an example where the check fails — it’s effectively a regression guard for the algorithm. Added a comment explaining that. Happy to drop the call entirely if you’d prefer.

Let me know if you’d like any other changes.