Refactor of flow tools - Verification of XZCorrections objects

[matulni]

This PR adds a new method :func: XZCorrections.check_well_formed to verify the correctness of XZ-corrections objects.

A correct XZCorrections instance verifies the following properties:
- Keys of the correction dictionaries are measured nodes, i.e., a subset of $O^c$.
- Corrections respect the partial order.
- The first layer of the partial order contains all the output nodes if there are any.
- The partial order contains all the nodes (without duplicates) and it does not have empty layers.

Flow and XZ-corrections exceptions.

This PR builds on the exception classes introduced in #378. It requires changes introduced in #378.

We detail next the full exception landscape.

---
config:
  layout: elk
  elk:
    mergeEdges: false
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart TD

a0(**Exception**)
b0("**Generic[_Reason]**")

m0(**XZCorrectionsError**)

n0(**FlowError**)

n1(CorrectionFunctionError)
n2(FlowPropositionError)
n3(FlowPropositionOrderError)
n4(PartialOrderError)
n5(PartialOrderLayerError)

m1(XZCorrectionsOrderError)

a0 --> m0
a0 --> n0

b0 --> m0
b0 --> n0


m0 --POEReason--> n4
m0 --POLEReason--> n5
m0 --XZCOEReason--> m1

n0 --CFEReason--> n1
n0 --FPEReason--> n2
n0 --FPOEReason--> n3
n0 --POEReason--> n4
n0 --POLEReason--> n5

Loading

• Arrows indicate inheritance (from parent to child).

• _Reason is a parametric type bound to the union of FlowErrorReason | XZCorrectionsErrorReason | str. Binding to str allows passing generic error messages to XZCorrectionsError and FlowError. All errors require this parameter.

• "Reasons" (XZCorrectionsOrderErrorReason, PartialOrderLayerErrorReason, etc.) are Enum classes which inherit from FlowErrorReason or XZCorrectionsErrorReason or both.

• Error subclasses:

  • CorrectionFunctionError
    • General errors in the flow correction function.
    • Does not require additional parameters.
  • 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
  • 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
  • XZCorrectionsOrderError
    • Errors in XZ-corrections objects concerning the correction dictionaries and the partial order.
    • Additional parameters:
      • node
      • correction_set
      • past_and_present_nodes

[codecov]

Codecov Report

❌ Patch coverage is 78.49162% with 77 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.05%. Comparing base (2daae9a) to head (50b901d).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
graphix/flow/exceptions.py	65.00%	63 Missing ⚠️
graphix/flow/core.py	92.13%	14 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #381      +/-   ##
==========================================
- Coverage   86.31%   86.05%   -0.27%     
==========================================
  Files          44       45       +1     
  Lines        6183     6756     +573     
==========================================
+ Hits         5337     5814     +477     
- Misses        846      942      +96     

☔ 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.