ppm_compilation : Apply all sub-PPM compilation passes in one step. (#1750)

**Context:**
Introduced the `ppm_compilation` pass as a top-level composition of
existing transformation and optimization passes. This allows users to
apply the transformation Clifford+T to Pauli product measurements (PPMs)
in a single step without managing sub-pass sequencing manually.
 
The sub-paseses comprise:
* `to_ppr`: Converts gates into Pauli Product Rotations (PPRs)
(Transformation)
       #1486  
       #1499 
  * `commute_ppr`: Commutes PPRs past non-Clifford PPRs (Optimization)
      #1563
  * `merge_ppr_ppm`: Merges PPRs into PPMs (Optimization) 
      #1580 
  * `ppr_to_ppm`: Decomposes PPRs into PPMs (Transformation) 
      #1664 

**Example:**
```python
  import pennylane as qml
  from catalyst import measure, passes, qjit
  
  pipe = [("pipe", ["enforce-runtime-invariants-pipeline"])]
  
  @qjit(pipelines=pipe, target="mlir")
  @passes.ppm_compilation(decompose_method="auto-corrected", avoid_y_measure=True, max_pauli_size=2)
  @qml.qnode(qml.device("null.qubit", wires=2))
  def circuit():
      qml.CNOT([0, 1])
      qml.CNOT([1, 0])
      qml.adjoint(qml.T)(0)
      qml.T(1)
      return measure(0), measure(1)
  
  print(circuit.mlir_opt)
```

**Benefits:**
- Simplifies the user workflow for compilation.

[[sc-90149]]

---------

Co-authored-by: Josh Izaac <[email protected]>
Co-authored-by: David Ittah <[email protected]>
Co-authored-by: Joey Carter <[email protected]>

Author: 4 people

doc/releases/changelog-dev.md

@@ -23,6 +23,20 @@
   * `decompose_non_clifford_ppr`: Decompose non-Cliford PPR (:math:`\theta = \tfrac{\pi}{8}`)
   into PPMs using a magic state.
 
+* A new compilation pass called :func:`~.passes.ppm_compilation` has been added to Catalyst to 
+  transform Clifford+T gates into Pauli Product Measurements (PPMs). This high-level pass simplifies
+  circuit transformation and optimization by combining multiple sub-passes into a single step.
+  [(#1750)](https://github.com/PennyLaneAI/catalyst/pull/1750)
+  
+  The sub-passes that make up the :func:`~.passes.ppm_compilation` pass are:
+  * :func:`~.passes.to_ppr`: Converts gates into Pauli Product Rotations (PPRs).
+  * :func:`~.passes.commute_ppr`: Commutes PPRs past non-Clifford PPRs.
+  * :func:`~.passes.merge_ppr_ppm`: Merges Clifford PPRs into PPMs.
+  * :func:`~.passes.ppr_to_ppm`: Decomposes non-Clifford and Clifford PPRs into PPMs.
+
+  Use this pass via the :func:`~.passes.ppm_compilation` decorator to compile circuits 
+  in a single pipeline.
+
 * Support for :class:`qml.Snapshot <pennylane.Snapshot>` to capture quantum states at any 
   point in a circuit has been added to Catalyst [(#1741)](https://github.com/PennyLaneAI/catalyst/pull/1741).
   For example, the code below is capturing 
@@ -60,7 +74,6 @@
   Array([0.25, 0.25, 0.25, 0.25], dtype=float64))
   ```
 
-
 <h3>Improvements 🛠</h3>
 
 * The behaviour of measurement processes executed on `null.qubit` with QJIT is now more in line with
@@ -106,12 +119,12 @@
   deallocation primitive has been split into deallocation and a separate device release primitive.
   [(#1720)](https://github.com/PennyLaneAI/catalyst/pull/1720)
 
-  * `qunitary_p` is now `unitary_p` (unchanged)
-  * `qmeasure_p` is now `measure_p` (unchanged)
-  * `qdevice_p` is now `device_init_p` (unchanged)
-  * `qdealloc_p` no longer releases the device, thus it can be used at any point of a quantum
+  - `qunitary_p` is now `unitary_p` (unchanged)
+  - `qmeasure_p` is now `measure_p` (unchanged)
+  - `qdevice_p` is now `device_init_p` (unchanged)
+  - `qdealloc_p` no longer releases the device, thus it can be used at any point of a quantum
      execution scope
-  * `device_release_p` is a new primitive that must be used to mark the end of a quantum execution
+  - `device_release_p` is a new primitive that must be used to mark the end of a quantum execution
      scope, which will release the quantum device
 
 * Catalyst has removed the `experimental_capture` keyword from the `qjit` decorator in favour of
@@ -150,13 +163,13 @@
   [(#1729)](https://github.com/PennyLaneAI/catalyst/pull/1729)
 
   Several internal changes were made for this update.
-  * LAPACK kernels are updated to adhere to the new JAX lowering rules for external functions.
+    - LAPACK kernels are updated to adhere to the new JAX lowering rules for external functions.
     [(#1685)](https://github.com/PennyLaneAI/catalyst/pull/1685)
 
-  * The trace stack is removed and replaced with a tracing context manager.
+    - The trace stack is removed and replaced with a tracing context manager.
     [(#1662)](https://github.com/PennyLaneAI/catalyst/pull/1662)
 
-  * A new `debug_info` argument is added to `Jaxpr`, the `make_jaxpr`
+    - A new `debug_info` argument is added to `Jaxpr`, the `make_jaxpr`
     functions, and `jax.extend.linear_util.wrap_init`.
     [(#1670)](https://github.com/PennyLaneAI/catalyst/pull/1670)
     [(#1671)](https://github.com/PennyLaneAI/catalyst/pull/1671)

frontend/catalyst/passes/__init__.py

@@ -39,6 +39,7 @@
     ions_decomposition,
     merge_ppr_ppm,
     merge_rotations,
+    ppm_compilation,
     ppr_to_ppm,
     to_ppr,
 )
@@ -56,4 +57,5 @@
     "apply_pass_plugin",
     "merge_ppr_ppm",
     "ppr_to_ppm",
+    "ppm_compilation",
 )

frontend/catalyst/passes/builtin_passes.py

@@ -669,3 +669,115 @@ def circuit():
         )
 
     return PassPipelineWrapper(qnode, passes)
+
+
+def ppm_compilation(
+    qnode=None, *, decompose_method="auto-corrected", avoid_y_measure=False, max_pauli_size=0
+):
+    R"""
+    Specify that the MLIR compiler pass for transforming
+    clifford+T gates into Pauli Product Measurements (PPM) will be applied.
+
+    This pass combines multiple sub-passes:
+
+    - :func:`~.passes.to_ppr` : Converts gates into Pauli Product Rotations (PPRs)
+    - :func:`~.passes.commute_ppr` : Commutes PPRs past non-Clifford PPRs
+    - :func:`~.passes.merge_ppr_ppm` : Merges PPRs into Pauli Product Measurements (PPMs)
+    - :func:`~.passes.ppr_to_ppm` : Decomposes PPRs into PPMs
+
+    The ``avoid_y_measure`` and ``decompose_method`` arguments are passed
+    to the :func:`~.passes.ppr_to_ppm` pass.
+    The ``max_pauli_size`` argument is passed to the :func:`~.passes.commute_ppr`
+    and :func:`~.passes.merge_ppr_ppm` passes.
+
+    Args:
+        qnode (QNode, optional): QNode to apply the pass to. If None, returns a decorator.
+        decompose_method (str, optional): The method to use for decomposing non-Clifford PPRs.
+            Options are ``"auto-corrected"`` and ``"clifford-corrected"``. Defaults to
+            ``"auto-corrected"``.
+            ``"auto-corrected"`` uses an additional measurement for correction.
+            ``"clifford-corrected"`` uses a Clifford rotation for correction.
+        avoid_y_measure (bool): Rather than performing a Pauli-Y measurement for Clifford rotations
+            (sometimes more costly), a :math:`Y` state (:math:`Y\vert 0 \rangle`) is used instead
+            (requires :math:`Y` state preparation). Defaults to ``False``.
+        max_pauli_size (int): The maximum size of the Pauli strings after commuting or merging.
+            Defaults to 0 (no limit).
+
+    Returns:
+        ~.QNode or callable: Returns decorated QNode if qnode is provided,
+        otherwise returns a decorator.
+
+    **Example**
+
+    If a merging resulted in a PPM acting on more than
+    ``max_pauli_size`` qubits (here, ``max_pauli_size = 2``), that merging would be skipped.
+    However, when decomposed into PPMs, at least one qubit will be applied, so the final
+    PPMs will act on at least one additional qubit.
+
+    .. code-block:: python
+
+        import pennylane as qml
+        from catalyst import qjit, measure
+        from catalyst.passes import ppm_compilation
+
+        pipeline = [("pipe", ["enforce-runtime-invariants-pipeline"])]
+        method = "clifford-corrected"
+
+        @qjit(pipelines=pipeline, target="mlir")
+        @ppm_compilation(decompose_method=method, avoid_y_measure=True, max_pauli_size=2)
+        @qml.qnode(qml.device("null.qubit", wires=2))
+        def circuit():
+            qml.CNOT([0, 1])
+            qml.CNOT([1, 0])
+            qml.adjoint(qml.T)(0)
+            qml.T(1)
+            return measure(0), measure(1)
+
+        print(circuit.mlir_opt)
+
+    Example MLIR Representation:
+
+    .. code-block:: mlir
+
+        . . .
+        %m, %out:3 = qec.ppm ["Z", "Z", "Z"] %1, %2, %4 : !quantum.bit, !quantum.bit, !quantum.bit
+        %m_0, %out_1:2 = qec.ppm ["Z", "Y"] %3, %out#2 : !quantum.bit, !quantum.bit
+        %m_2, %out_3 = qec.ppm ["X"] %out_1#1 : !quantum.bit
+        %m_4, %out_5 = qec.select.ppm(%m, ["X"], ["Z"]) %out_1#0 : !quantum.bit
+        %5 = arith.xori %m_0, %m_2 : i1
+        %6:2 = qec.ppr ["Z", "Z"](2) %out#0, %out#1 cond(%5) : !quantum.bit, !quantum.bit
+        quantum.dealloc_qb %out_5 : !quantum.bit
+        quantum.dealloc_qb %out_3 : !quantum.bit
+        %7 = quantum.alloc_qb : !quantum.bit
+        %8 = qec.fabricate  magic_conj : !quantum.bit
+        %m_6, %out_7:2 = qec.ppm ["Z", "Z"] %6#1, %8 : !quantum.bit, !quantum.bit
+        %m_8, %out_9:2 = qec.ppm ["Z", "Y"] %7, %out_7#1 : !quantum.bit, !quantum.bit
+        %m_10, %out_11 = qec.ppm ["X"] %out_9#1 : !quantum.bit
+        %m_12, %out_13 = qec.select.ppm(%m_6, ["X"], ["Z"]) %out_9#0 : !quantum.bit
+        %9 = arith.xori %m_8, %m_10 : i1
+        %10 = qec.ppr ["Z"](2) %out_7#0 cond(%9) : !quantum.bit
+        quantum.dealloc_qb %out_13 : !quantum.bit
+        quantum.dealloc_qb %out_11 : !quantum.bit
+        %m_14, %out_15:2 = qec.ppm ["Z", "Z"] %6#0, %10 : !quantum.bit, !quantum.bit
+        %from_elements = tensor.from_elements %m_14 : tensor<i1>
+        %m_16, %out_17 = qec.ppm ["Z"] %out_15#1 : !quantum.bit
+        . . .
+
+    """
+    passes = {
+        "ppm_compilation": {
+            "decompose-method": decompose_method,
+            "avoid-y-measure": avoid_y_measure,
+            "max-pauli-size": max_pauli_size,
+        }
+    }
+
+    if qnode is None:
+        return functools.partial(
+            ppm_compilation,
+            decompose_method=decompose_method,
+            avoid_y_measure=avoid_y_measure,
+            max_pauli_size=max_pauli_size,
+        )
+
+    return PassPipelineWrapper(qnode, passes)

frontend/catalyst/passes/pass_api.py

@@ -378,4 +378,5 @@ def _API_name_to_pass_name():
         "commute_ppr": "commute_ppr",
         "merge_ppr_ppm": "merge_ppr_ppm",
         "ppr_to_ppm": "ppr_to_ppm",
+        "ppm_compilation": "ppm_compilation",
     }