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.