Refactor of flow tools - Verification of flow objects

[matulni]

This PR introduces the methods :func: PauliFlow.check_well_formed, :func: GFlow.check_well_formed and :func: CausalFlow.check_well_formed which verify the correctness of flow objects and raise exceptions when the flow is incorrect.

Exception classes are grouped in the new module graphix.flow.exceptions.

The error messages explain which proposition in the flow is violated. Flow-finding algorithms always (in principle) output well-formed flows, but it is possible to instantiate flow objects by passing arbitrary parameters to the constructors. In such cases, there is not any guarantee that the flow objects are well formed. The methods introduced here can be useful for debugging or researching. The exception handling adapts the pattern introduced in #364.

The new methods subsume :func: gflow.verify_flow, :func: gflow.verify_gflow, :func: gflow.verify_pauli_flow.

Additionally, this PR introduces the methods :func: PauliFlow.get_measurement_label, :func: GFlow.get_measurement_label which return the measurement label of a given node. They follow same criteria employed in the flow-finding algorithms, that is, querying this method on a node with a measurement Measurement(0, Plane.XY) will return Plane.XY in a GFlow or CausalFlow and Axis.X in a PauliFlow.

Additional information on the exception management

---
config:
layout: elk
elk:
mergeEdges: false
nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart TD
a0(**Exception**)
n0(**FlowError**)
n1(FlowGenericError)
n2(FlowPropositionError)
n3(FlowPropositionOrderError)
n4(PartialOrderError)
n5(PartialOrderLayerError)
a0 --> n0
n0 --FGEReason--> n1
n0 --FPEReason--> n2
n0 --FPOEReason--> n3
n0 --POEReason--> n4
n0 --POLEReason--> n5

Loading

• Arrows indicate inheritance (from parent to child).

• "Reasons" (FlowPropositionErrorReason, PartialOrderLayerErrorReason, etc.) are Enum classes.

• Error subclasses:

  • FlowPropositionError
    • Violations of the flow-definition propositions which concern the correction function only (C0, C1, G1, G3, G4, G5, P4, P5, P6, P7, P8, P9).
    • Additional parameters:
      • node
      • correction_set
  • FlowPropositionOrderError
    • Violations of the flow-definition propositions which concern the correction function and the partial order (C2, C3, G1, G2, P1, P2, P3).
    • Additional parameters:
      • node
      • correction_set
      • past_and_present_nodes
  • FlowGenericError
    • General errors in the flow correction function, XY planes in causal flow.
    • Does not require additional parameters.
  • PartialOrderError
    • General flow and XZ-corrections errors in the partial order.
    • Does not require additional parameters.
  • PartialOrderLayerError
    • Flow and XZ-corrections errors concerning a specific layer of the partial order.
    • Additional parameters:
      • layer_index
      • layer

[codecov]

Codecov Report

❌ Patch coverage is 78.64769% with 60 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.00%. Comparing base (2daae9a) to head (6fe0d2b).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
graphix/flow/exceptions.py	64.74%	49 Missing ⚠️
graphix/flow/core.py	92.25%	11 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## master #378 +/- ##
==========================================
- Coverage 86.31% 86.00% -0.31% 
==========================================
Files 44 45 +1 Lines 6183 6476 +293 ==========================================
+ Hits 5337 5570 +233 - Misses 846 906 +60 

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

[matulni]

Note: the functionality introduced here assumes that the open graph is well formed (currently ensured at instantiation). This should be updated when/if we move away from this design. See #374 (comment)

[emlynsg]

LGTM. Very thorough test suite!

[mgarnier59]

LGTM!
No additional comments.

[thierry-martinez]

LGTM! Nice work!