Method namespace refactorization

[matulni]

Current naming for transformation methods is not consistent throught the codebase, mostly because there isn't a clear documented convention.

We suggest fixing the following convention (unless specified, the method name remains the same):

• .to_<object_name> when the transformation is always well defined (i.e., it cannot fail assuming runnable and well-formed objects):

  • Pattern.to_opengraph (formerly Pattern.extract_opengraph)
  • Pattern.to_xzcorrections (formerly Pattern.extract_xzcorrections)
  • Pattern.to_qasm3
  • StandardizedPattern.to_pattern
  • StandardizedPattern.to_space_optimal_pattern
  • Standardized.to_opengraph (formerly Standardized.extract_opengraph)
  • StandardizedPattern.to_xzcorrections (formerly StandardizedPattern.extract_xzcorrections)
  • XZCorrections.to_pattern
  • PauliFlow.to_xzcorrections (formerly PauliFlow.to_corrections)
  • PauliFlow.to_circuit (formely PauliFlow.extract_circuit)
    • Note: this may be misleading because the method returns an ExtractionResult instead of a Circuit, and in the literature this procedure is known as "circuit extraction".
  • 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
  • State.to_densitymatrix

• .extract_<object_name> when the transformation can fail raising an exception, even if the initial object is well-formed:

  • Pattern.extract_causal_flow
  • Pattern.extract_gflow
  • Opengraph.extract_pattern (formerly Opengraph.to_pattern)
  • Opengraph.extract_causal_flow
  • Opengraph.extract_gflow
  • Opengraph.extract_pauli_flow
  • Opengraph.extract_circuit
  • XZCorrections.extract_causal_flow (formerly XZCorrections.to_causal_flow)
  • XZCorrections.extract_gflow (formerly XZCorrections.to_gflow)

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

  • Opengraph.find_causal_flow
  • Opengraph.find_gflow
  • Opengraph.find_pauli_flow

---

The only exception to this naming convention is: Circuit.transpile, and Pattern.simulate since these are established words in the community.

---

Further, for "getter methods" which don't return an "MBQC class" but rather a "Python object" we suggest using plain nouns, even if the method is not a property (unless specified, the method name remains the same):

• 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.connect_nodes
• Pattern.correction_commands
• Pattern.max_space
• Pattern.space_list
• Opengraph.neighbors
• Opengraph.odd_neighbors
• XZCorrections.dag (formerly XZCorrections.extract_dag)
• PauliFlow.node_measurement_label
• PauliFlow.extraction_pauli_strings (this is already a cached property)
• MatGF2.rank (formerly MatGF2.compute_rank)

Questions to discuss

Q1: Is this the naming convention we want ?

I personally prefer .try_to_<object> instead of .extract_<object>, and .to_<object>_or_none instead of .find_<object>. Not sure if it's not too pythonic, but it's more self-explanatory than the convention above. Also, this would be more consistent with current PauliFlow.try_from_correction_matrix, and with Measurement.to_pauli_or_bloch. Then Measurement.try_to_pauli should become Measurement.to_pauli_or_none.

Q2: Are we missing any methods in the public API?

I went through the main modules but I may have missed something.

Q3: How to best split this PR?

A priori, we just need to do a search and replace, but the refactoring will have an important impact on most (if not all) the reverse dependencies. This can become very tedious to review and merge. Should we wait until having most PRs merged across dependencies before starting the refactoring? How can we split the PR?

[matulni]

@thierry-martinez : use to_<object> or to_<object>_or_none only.
Measurement.try_to_pauli should become Measurement.to_pauli_or_none. --> ok

PauliFlow.try_from_correction_matrix -- > PauliFlow.from_correction_matrix