Namespace homogenisation

[matulni]

This PR introduces a homogeneous and pythonic naming convention for transformation methods and accessors.

Transformation methods

We fix the following convention:

• .to_<object> when the transformation can only return an object or raise an exception. If object corresponds to an existing class, we use the name of the class without underscores and small case. Ex.: to_opengraph, to_causalflow, to_xzcorrections, etc.

Non-exhaustive list of method names (unless specified, the method name remained the same in the commit):

• Pattern.to_opengraph (formerly Pattern.extract_opengraph)

• Pattern.to_xzcorrections (formerly Pattern.extract_xzcorrections)

• Pattern.to_qasm3

• Pattern.to_causalflow (formerly Pattern.extract_causal_flow)

• Pattern.to_gflow (formerly Pattern.extract_gflow)

• Pattern.to_pauliflow (formerly Pattern.extract_pauli_flow)

• StandardizedPattern.to_pattern

• StandardizedPattern.to_space_optimal_pattern

• StandardizedPattern.to_opengraph (formerly StandardizedPattern.extract_opengraph)

• StandardizedPattern.to_xzcorrections (formerly StandardizedPattern.extract_xzcorrections)

• XZCorrections.to_pattern

• XZCorrections.to_causalflow (formerly XZCorrections.to_causal_flow)

• XZCorrections.to_gflow

• XZCorrections.to_pauliflow (formerly XZCorrections.to_pauli_flow)

• XZCorrections.to_dag (formerly XZCorrections.extract_dag)

• PauliFlow.to_xzcorrections (formerly PauliFlow.to_corrections)

• GFlow.to_xzcorrections (formerly GFlow.to_corrections)

• CausalFlow.to_xzcorrections (formerly CausalFlow.to_corrections)

• ExtractionResult.to_circuit

• PauliString.to_tableau

• CliffordMap.to_tableau

• <...>.to_bloch

• AbstractMeasurement.to_plane_or_axis

• AbstractPlanarMeasurement.to_plane

• Measurement.to_pauli_or_bloch

• <...>.to_ascii

• <...>.to_unicode

• <...>.to_latex

• State.to_statevector_numpy (formerly State.to_statevector)

• State.to_densitymatrix_numpy (formerly State.to_densitymatrix)

• Opengraph.to_pattern

• Opengraph.to_causal_flow (formerly Opengraph.extract_causal_flow)

• Opengraph.to_gflow (formerly Opengraph.extract_gflow)

• Opengraph.to_pauli_flow (formerly Opengraph.extract_pauli_flow)

• Opengraph.to_circuit (formerly OpenGraph.extract_circuit)

• Noise.to_krauschannel (formerly Noise.to_kraus_channel)

• <...>.to_standardizedpattern (formerly <...>.to_standardized_pattern)

• .to_<object>_or_none when the transformation can fail returning None, even if the initial object is well-formed:

  • Opengraph.to_causalflow_or_none (formerly Opengraph.find_causal_flow)
  • Opengraph.to_gflow_or_none (formerly Opengraph.find_gflow)
  • Opengraph.to_pauliflow_or_none (formerly Opengraph.find_pauli_flow)
  • Measurement.to_pauli_or_none (formerly Measurement.try_to_pauli)

• .from_<object> for constructors that can only return an object or raise an exception.

  • <...>.from_standardizedpattern (formerly <...>.from_standardized_pattern)

• .from_<object>_or_none for constructors that can fail returning None

  • PauliFlow.from_correctionmatrix_or_none (formerly PauliFlow.try_from_correction_matrix)
  • ComplexUnit.from_or_none (formerly ComplexUnit.try_from)

Exception to this naming convention:

• Circuit.transpile Reason: returns a TranspileResult and established word in the community.
• Pattern.simulate. Reason: established word in the community.
• PauliFlow.extract_circuit. Reason: returns an ExtractionResult and established word in the community.

Accessor methods

For accessor methods which don't return an "MBQC class" but rather a "Python object" we use plain nouns, even if the method is not a property. This follows the convention used by many python libraries, like numpy or networkx.

List method names (unless specified, the method name remained the same in the commit):

• Pattern.node_mapping
• Pattern.signals (formerly Pattern.extract_signals)
• Pattern.partial_order_layers (formerly Pattern.extract_partial_order_layers)
• Pattern.measurement_commands (formerly Pattern.extract_measurement_commands).
• Pattern.max_degree (formerly Pattern.compute_max_degree).
• Pattern.graph (formerly Pattern.extract_graph).
• Pattern.nodes (formerly Pattern.extract_nodes).
• Pattern.isolated_nodes (formerly Pattern.extract_isolated_nodes).
• Pattern.clifford_commands (formerly Pattern.extract_clifford).
• Pattern.connected_nodes
• Pattern.correction_commands
• Pattern.max_space
• Pattern.space_list
• Opengraph.neighbors
• Opengraph.odd_neighbors
• PauliFlow.node_measurement_label
• PauliFlow.extraction_pauli_strings (this is already a cached property)
• MatGF2.rank (formerly MatGF2.compute_rank)

Consistent class naming

Class Statevec was renamed as Statevector to match StatevectorBackend and transformation method conventions.

Reverse dependencies

Changes were made in the following repositories:

• graphix-pyzxNamespace homogenisation graphix-pyzx#2
• graphix-stim-compiler Namespace homogenisation graphix-stim-compiler#1
• graphix-stim-backend Namespace homogenisation graphix-stim-backend#2
• graphix-mqtbench
• graphix-ibmq Namespace homogenisation graphix-ibmq#25
• veriphix Namespace homogenisation qat-inria/veriphix#25

Reverse dependencies in the nox.py was changed accordingly. See accompanying PRs in these repositories.

[codecov]

Codecov Report

❌ Patch coverage is 87.20000% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.62%. Comparing base (7e94d5b) to head (2af34a1).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
graphix/sim/tensornet.py	42.10%	11 Missing ⚠️
graphix/pattern.py	81.25%	3 Missing ⚠️
graphix/graphsim.py	66.66%	1 Missing ⚠️
graphix/sim/statevec.py	92.85%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #557   +/-   ##
=======================================
  Coverage   90.62%   90.62%           
=======================================
  Files          49       49           
  Lines        7481     7481           
=======================================
  Hits         6780     6780           
  Misses        701      701           

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

This is a great improvement, thanks!

| If object corresponds to an existing class, we use the name of the class without underscores and small case.

There are still some exceptions:

• from_standardized_pattern / to_standardized_pattern ;
• from_correction_matrix ;
• to_kraus_channel.

If we introduce a dedicated class FocusedFlow (#474), we woud perhaps rename from_focused_flow into from_focusedflow.

[matulni]

This is a great improvement, thanks!

| If object corresponds to an existing class, we use the name of the class without underscores and small case.

There are still some exceptions:

• from_standardized_pattern / to_standardized_pattern ;
• from_correction_matrix ;
• to_kraus_channel.

If we introduce a dedicated class FocusedFlow (#474), we woud perhaps rename from_focused_flow into from_focusedflow.

Thanks. I'm doubtful. Indeed, it would be more consistent to change them, but not sure if it hinders code readability.

• from_standardizedpattern / to_standardizedpattern ;
• from_correctionmatrix ;
• to_krauschannel.

Another exception/inconsistency is that we use State.to_statevector, but it returns an np.array.

The backend naming is also somewhat inconsistent:
We have Statevec and StatevectorBackend for some reason (whereas we have DensityMatrix and DensityMatrixBackend).

[thierry-martinez]

LGTM! Thanks for all these changes.

[pranav97nair]

Apart from a couple minor typos I don't see any issues! Thanks a lot for this update.

Purely subjectively, I find to_statevector_numpy and to_densitymatrix_numpy a bit wordy, though I agree the change was required by the new convention. I don't have any alternative ideas other than perhaps to_numpy_vector and to_numpy_matrix. I'll let you decide whether that is worth updating or not!

[pranav97nair]

This should be to_dag unless I am missing something.

[matulni]

Thanks, fixed in 2af34a1

[pranav97nair]

Typo: "nouns"

[matulni]

Fixed in 2af34a1

[matulni]

Thanks for the review @pranav97nair, I agree it's a bit wordy, but I don't see much difference w.r.t. to_numpy_vector or to_numpy_matrix. Let's leave it as is