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,60 @@
 
 <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)
+  [(#2214)](https://github.com/PennyLaneAI/catalyst/pull/2214)
+  [(#2246)](https://github.com/PennyLaneAI/catalyst/pull/2246)
+  [(#2231)](https://github.com/PennyLaneAI/catalyst/pull/2231)
+
 * 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)
+
 * `qml.PCPhase` can be compiled and executed with capture enabled.
   [(#2226)](https://github.com/PennyLaneAI/catalyst/pull/2226)
 
@@ -84,6 +133,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)
@@ -139,6 +202,15 @@
 
 <h3>Internal changes ⚙️</h3>
 
+* The `catalyst.python_interface.visualization` module has been renamed to
+  `catalyst.python_interface.inspection`, and various utility functions within this module
+  have been streamlined.
+  [(#2237)](https://github.com/PennyLaneAI/catalyst/pull/2237)
+
+* 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)
+
 * Resource tracking now writes out at device destruction time instead of qubit deallocation
   time. The written resources will be the total amount of resources collected throughout the
   lifetime of the execution. For executions that split work between multiple functions,
@@ -197,6 +269,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 .inspection import QMLCollector
+from .parser import QuantumParser
+from .pass_api import compiler_transform
+
+__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()