feat: add graph visualization for compiled programs

.codecov.yml

@@ -7,3 +7,6 @@ coverage:
   status:
     project: false
     patch: true
+
+ignore:
+  - "frontend/catalyst/python_interface"

.github/workflows/check-catalyst.yaml

@@ -473,6 +473,9 @@ jobs:
         # macOS requirements.txt
         python3 -m pip install cuda-quantum==0.6.0
         python3 -m pip install oqc-qcaas-client
+        # Install graphviz for testing the mlir-op-graph integration
+        sudo apt-get install -y graphviz
+        python3 -m pip install graphviz
         make frontend
 
     - name: Get Cached LLVM Build
@@ -556,6 +559,9 @@ jobs:
         sudo apt-get install -y libasan6 make
         python3 --version | grep ${{ needs.constants.outputs.primary_python_version }}
         python3 -m pip install -r requirements.txt
+        # Install graphviz for testing the mlir-op-graph integration
+        sudo apt-get install -y graphviz
+        python3 -m pip install graphviz
         make frontend
 
     - name: Get Cached LLVM Build

doc/releases/changelog-dev.md

@@ -2,11 +2,57 @@
 
 <h3>New features since last release</h3>
 
+* Compiled programs can be visualized.
+  [(#2213)](https://github.com/PennyLaneAI/catalyst/pull/2213)
+  [(#2229)](https://github.com/PennyLaneAI/catalyst/pull/2229)
+
 * Added ``catalyst.switch``, a qjit compatible, index-switch style control flow decorator.
   [(#2171)](https://github.com/PennyLaneAI/catalyst/pull/2171)
 
 <h3>Improvements 🛠</h3>
 
+* Add an experimental `outline_state_evolution_pass` xDSL pass to `catalyst.python_interface.transforms`,
+  which moves all quantum gate operations to a private callable.
+  [(#8367)](https://github.com/PennyLaneAI/pennylane/pull/8367)
+
+* A new experimental `split_non_commuting_pass` compiler pass has been added to 
+  `catalyst.python_interface.transforms`. This pass splits quantum functions that
+  measure observables on the same wires into multiple function executions, where
+  each execution measures observables on different wires (using the "wires" grouping
+  strategy). The original function is replaced with calls to these generated functions,
+  and the results are combined appropriately.
+  [(#8531)](https://github.com/PennyLaneAI/pennylane/pull/8531)
+
+* Add the `PCPhaseOp` operation to the xDSL Quantum dialect.
+  [(#8621)](https://github.com/PennyLaneAI/pennylane/pull/8621)
+
+* Users can now apply xDSL passes without the need to pass the `pass_plugins` argument to
+  the `qjit` decorator.
+  [(#8572)](https://github.com/PennyLaneAI/pennylane/pull/8572)
+  [(#8573)](https://github.com/PennyLaneAI/pennylane/pull/8573)
+  [(#2169)](https://github.com/PennyLaneAI/catalyst/pull/2169)
+  [(#2183)](https://github.com/PennyLaneAI/catalyst/pull/2183)
+
+* The :meth:`catalyst.python_interface.transforms.convert_to_mbqc_formalism_pass` now 
+  supports :class:`~xdsl.dialects.scf.IndexSwitchOp` in IR and ignores regions that have no body.
+  [(#8632)](https://github.com/PennyLaneAI/pennylane/pull/8632)
+
+* The `convert_to_mbqc_formalism` compilation pass now outlines the operations to represent a gate
+  in the MBQC formalism into subroutines in order to reduce the IR size for large programs.
+  [(#8619)](https://github.com/PennyLaneAI/pennylane/pull/8619)
+
+* The :meth:`catalyst.python_interface.Compiler.run` method now accepts a string as input,
+  which is parsed and transformed with xDSL.
+  [(#8587)](https://github.com/PennyLaneAI/pennylane/pull/8587)
+
+* An `is_xdsl_pass` function has been added to the `catalyst.python_interface.pass_api` module.
+  This function checks if a pass name corresponds to an xDSL implemented pass.
+  [(#8572)](https://github.com/PennyLaneAI/pennylane/pull/8572)
+
+* A new `catalyst.python_interface.utils` submodule has been added, containing general-purpose utilities for
+  working with xDSL. This includes a function that extracts the concrete value of scalar, constant SSA values.
+  [(#8514)](https://github.com/PennyLaneAI/pennylane/pull/8514)
+
 * Resource tracking now supports dynamic qubit allocation
   [(#2203)](https://github.com/PennyLaneAI/catalyst/pull/2203)
 
@@ -38,11 +84,6 @@
 * `qml.grad` and `qml.jacobian` can now be used with `qjit` when program capture is enabled.
   [(#2078)](https://github.com/PennyLaneAI/catalyst/pull/2078)
 
-* xDSL passes are now automatically detected when using the `qjit` decorator. 
-  This removes the need to pass the `pass_plugins` argument to the `qjit` decorator.
-  [(#2169)](https://github.com/PennyLaneAI/catalyst/pull/2169)
-  [(#2183)](https://github.com/PennyLaneAI/catalyst/pull/2183)
-
 * The ``mlir_opt`` property now correctly handles xDSL passes by automatically
   detecting when the Python compiler is being used and routing through it appropriately.
   [(#2190)](https://github.com/PennyLaneAI/catalyst/pull/2190)
@@ -75,6 +116,20 @@
 
 <h3>Bug fixes 🐛</h3>
 
+* The experimental xDSL :func:`~catalyst.python_interface.transforms.measurements_from_samples_pass`
+  pass has been updated to support `shots` defined by an `arith.constant` operation.
+  [(#8460)](https://github.com/PennyLaneAI/pennylane/pull/8460)
+
+* The experimental xDSL :func:`~catalyst.python_interface.transforms.diagonalize_measurements`
+  pass has been updated to fix a bug that included the wrong SSA value for final qubit insertion
+  and deallocation at the end of the circuit. A clear error is now also raised when there are
+  observables with overlapping wires.
+  [(#8383)](https://github.com/PennyLaneAI/pennylane/pull/8383)
+
+* Fixes a bug in the constructor of the xDSL Quantum dialect's `QubitUnitaryOp` that
+  prevented an instance from being constructed.
+  [(#8456)](https://github.com/PennyLaneAI/pennylane/pull/8456)
+
 * Fixes an issue where a heap-to-stack allocation conversion pass was causing SIGSEGV issues
   during program execution at runtime.
   [(#2172)](https://github.com/PennyLaneAI/catalyst/pull/2172)
@@ -130,6 +185,10 @@
 
 <h3>Internal changes ⚙️</h3>
 
+* Migrated the `pennylane.compiler.python_compiler` submodule from PennyLane to Catalyst.
+  It is now accessible as `catalyst.python_interface`.
+  [(#2199)](https://github.com/PennyLaneAI/catalyst/pull/2199)
+
 * Replaces the deprecated `shape_dtype_to_ir_type` function with the `RankedTensorType.get` method.
   [(#2159)](https://github.com/PennyLaneAI/catalyst/pull/2159)
 
@@ -181,6 +240,11 @@
 
 <h3>Documentation 📝</h3>
 
+* Added a "Unified Compiler Cookbook" RST file, along with tutorials, to `catalyst.python_interface.doc`,
+  which provides a quickstart guide for getting started with xDSL and its integration with PennyLane and
+  Catalyst.
+  [(#8571)](https://github.com/PennyLaneAI/pennylane/pull/8571)
+
 * A typo in the code example for :func:`~.passes.ppr_to_ppm` has been corrected.
   [(#2136)](https://github.com/PennyLaneAI/catalyst/pull/2136)
 

frontend/catalyst/compiler.py

@@ -376,14 +376,14 @@ def to_llvmir(*args, stdin=None, options: Optional[CompileOptions] = None):
 
 
 def to_mlir_opt(
-    *args, stdin=None, options: Optional[CompileOptions] = None, using_python_compiler=False
+    *args, stdin=None, options: Optional[CompileOptions] = None, using_unified_compiler=False
 ):
     """echo ${input} | catalyst --tool=opt *args *opts -"""
     # Check if we need to use Python compiler for xDSL passes
-    if using_python_compiler:
+    if using_unified_compiler:
         # Use Python compiler path for xDSL passes
         # pylint: disable-next=import-outside-toplevel
-        from pennylane.compiler.python_compiler import Compiler as PythonCompiler
+        from catalyst.python_interface import Compiler as PythonCompiler
 
         compiler = PythonCompiler()
         stdin = compiler.run(stdin, callback=None)
@@ -542,7 +542,7 @@ def check_nested_operations(op):
             return False
 
     @debug_logger
-    def is_using_python_compiler(self, mlir_module=None):
+    def is_using_unified_compiler(self, mlir_module=None):
         """Returns true if we need the Python compiler path.
 
         This happens when:
@@ -598,11 +598,11 @@ def run(self, mlir_module, *args, **kwargs):
             (str): filename of shared object
         """
 
-        if self.is_using_python_compiler(mlir_module):
+        if self.is_using_unified_compiler(mlir_module):
             # We keep this module here to keep xDSL requirement optional
             # Only move this is it has been decided that xDSL is no longer optional.
             # pylint: disable-next=import-outside-toplevel
-            from pennylane.compiler.python_compiler import Compiler as PythonCompiler
+            from catalyst.python_interface import Compiler as PythonCompiler
 
             compiler = PythonCompiler()
             mlir_module = compiler.run(mlir_module)

frontend/catalyst/jax_primitives_utils.py

@@ -378,9 +378,7 @@ def transform_named_sequence_lowering(jax_ctx: mlir.LoweringRuleContext, pipelin
 
                 try:
                     # pylint: disable=import-outside-toplevel
-                    from pennylane.compiler.python_compiler.pass_api import (
-                        is_xdsl_pass,
-                    )
+                    from catalyst.python_interface.pass_api import is_xdsl_pass
 
                     if is_xdsl_pass(_pass.name):
                         uses_xdsl_passes = True

frontend/catalyst/jit.py

@@ -582,13 +582,13 @@ def mlir_opt(self):
         """Obtain the MLIR representation after optimization"""
         if not self.mlir_module:
             return None
-        using_python_compiler = self.compiler.is_using_python_compiler(self.mlir_module)
+        using_unified_compiler = self.compiler.is_using_unified_compiler(self.mlir_module)
         stdin = self.mlir_module.operation.get_asm(
-            print_generic_op_form=using_python_compiler,
+            print_generic_op_form=using_unified_compiler,
             enable_debug_info=self.compile_options.use_nameloc,
         )
         return to_mlir_opt(
-            stdin=stdin, options=self.compile_options, using_python_compiler=using_python_compiler
+            stdin=stdin, options=self.compile_options, using_unified_compiler=using_unified_compiler
         )
 
     @debug_logger

frontend/catalyst/python_interface/__init__.py

@@ -0,0 +1,26 @@
+# Copyright 2025 Xanadu Quantum Technologies Inc.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Python Compiler API for integration of Catalyst with xDSL."""
+
+from .compiler import Compiler
+from .parser import QuantumParser
+from .pass_api import compiler_transform
+from .visualization import QMLCollector
+
+__all__ = [
+    "Compiler",
+    "compiler_transform",
+    "QuantumParser",
+    "QMLCollector",
+]

frontend/catalyst/python_interface/compiler.py

@@ -0,0 +1,83 @@
+# Copyright 2025 Xanadu Quantum Technologies Inc.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""This file contains the implementation of the PennyLane-xDSL integration API."""
+
+
+import io
+
+from jax._src.interpreters import mlir
+from jaxlib.mlir.dialects import stablehlo
+from jaxlib.mlir.ir import Context as jaxContext
+from jaxlib.mlir.ir import Module as jaxModule
+from pennylane.typing import Callable
+from xdsl.context import Context as xContext
+from xdsl.dialects.builtin import ModuleOp
+from xdsl.passes import ModulePass, PassPipeline
+from xdsl.printer import Printer
+
+from catalyst.python_interface.parser import QuantumParser
+from catalyst.python_interface.pass_api import ApplyTransformSequence
+
+
+# pylint: disable=too-few-public-methods
+class Compiler:
+    """Compiler namespace"""
+
+    @staticmethod
+    def run(
+        module: jaxModule | str,
+        callback: Callable[[ModulePass, ModuleOp, ModulePass], None] | None = None,
+    ) -> jaxModule | str:
+        """Runs the apply-transform-sequence pass.
+
+        The apply-transform-sequence pass is a "meta-pass". In other words,
+        it is a pass that runs other passes.
+
+        Args:
+            module: Either a Jax MLIR module or MLIR IR as a string
+            callback: Optional callback function called between passes
+
+        Returns:
+            jaxModule | str: jaxModule if the input was a jaxModule, else a string.
+        """
+        # Convert to generic text format
+        is_jax_module = isinstance(module, jaxModule)
+        if is_jax_module:
+            gentxtmod = module.operation.get_asm(
+                binary=False, print_generic_op_form=True, assume_verified=True
+            )
+        else:
+            gentxtmod = module
+
+        # Parse and transform with xDSL
+        ctx = xContext(allow_unregistered=True)
+        parser = QuantumParser(ctx, gentxtmod)
+        # xmod is modified in place
+        xmod = parser.parse_module()
+        pipeline = PassPipeline((ApplyTransformSequence(callback=callback),))
+        pipeline.apply(ctx, xmod)
+
+        # Convert back to string
+        buffer = io.StringIO()
+        Printer(stream=buffer, print_generic_format=True).print_op(xmod)
+
+        # Convert back to jaxModule if input was jaxModule
+        if is_jax_module:
+            with jaxContext() as jctx:
+                jctx.allow_unregistered_dialects = True
+                jctx.append_dialect_registry(mlir.upstream_dialects)
+                stablehlo.register_dialect(jctx)  # pylint: disable=no-member
+                newmod: jaxModule = jaxModule.parse(buffer.getvalue())
+            return newmod
+        return buffer.getvalue()