MLIR Conversion(s)

.github/workflows/ci_catalyst.yml

@@ -0,0 +1,122 @@
+name: Catalyst CI
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "mlir/**"
+  pull_request:
+    paths:
+      - "mlir/**"
+      - ".github/workflows/ci_catalyst.yml"
+  merge_group:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  cpp-test-catalyst:
+    name: 🇨‌ Test MLIR with LLVM@${{ matrix.llvm-version }}
+    runs-on: macos-14
+    strategy:
+      matrix:
+        llvm-version: [19]
+    env:
+      CMAKE_BUILD_PARALLEL_LEVEL: 4
+      CTEST_PARALLEL_LEVEL: 4
+      FORCE_COLOR: 3
+    steps:
+      # check out the repository
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # set up ccache for faster C++ builds
+      - name: Setup ccache
+        uses: Chocobo1/setup-ccache-action@v1
+        with:
+          prepend_symlinks_to_path: false
+          override_cache_key: c++-tests-mlir-catalyst
+
+      # set up mold as linker for faster C++ builds
+      - name: Set up mold as linker
+        uses: rui314/setup-mold@v1
+
+      # set up uv for faster Python package management
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: 3.13
+          activate-environment: true
+
+      # make sure ninja is installed
+      - name: Install Ninja
+        run: uv tool install ninja
+
+      # make sure the lit test runner is installed
+      - name: Install lit
+        run: uv pip install lit
+
+      # install LLVM 19 and MLIR via Homebrew and set up environment variables
+      - name: Install LLVM and MLIR via Homebrew
+        run: |
+          brew install llvm@19
+          brew link --force --overwrite llvm@19
+          echo "CC=$(brew --prefix llvm@19)/bin/clang" >> $GITHUB_ENV
+          echo "CXX=$(brew --prefix llvm@19)/bin/clang++" >> $GITHUB_ENV
+          echo "MLIR_DIR=$(brew --prefix llvm@19)/lib/cmake/mlir" >> $GITHUB_ENV
+          echo "LLVM_DIR=$(brew --prefix llvm@19)/lib/cmake/llvm" >> $GITHUB_ENV
+          echo "$(brew --prefix llvm@19)/bin" >> $GITHUB_PATH
+
+      # clone PennyLane Catalyst (from patched branch) - excl. submodules
+      - name: Clone PennyLane Catalyst
+        run: |
+          git clone --branch mqt_integration --depth=1 https://github.com/flowerthrower/catalyst.git catalyst
+
+      - name: Set macOS deployment target for linker
+        run: echo "MACOSX_DEPLOYMENT_TARGET=14.0" >> $GITHUB_ENV
+
+      # configure only MLIRQuantum dialect (skip building tools)
+      - name: Configure MLIRQuantum dialect
+        run: |
+          cmake -G Ninja -S catalyst/mlir -B catalyst/mlir/build \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DMLIR_DIR=$MLIR_DIR \
+            -DLLVM_DIR=$LLVM_DIR \
+            -DCATALYST_BUILD_TOOLS=OFF \
+            -DEnzyme_DIR="none"
+
+      # build MLIRQuantum
+      - name: Build MLIRQuantum dialect
+        run: |
+          cmake --build catalyst/mlir/build --target MLIRQuantum
+
+      - name: Check Catalyst CMake config
+        run: test -f catalyst/mlir/build/lib/cmake/catalyst/CatalystConfig.cmake
+
+      # configure the project with CMake
+      - name: Configure CMake for MLIR
+        run: |
+          cmake -G Ninja -S . -B build \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DBUILD_MQT_CORE_MLIR=ON \
+            -DENABLE_MQT_CORE_MLIR_CATALYST_PLUGIN=ON \
+            -DCatalyst_DIR="$PWD/catalyst/mlir/build/lib/cmake/catalyst"
+
+      # build the project
+      - name: Build MLIR quantum-opt
+        run: cmake --build build --config Release --target quantum-opt
+
+      # run conversion pipeline
+      - name: Run conversion -> catalystquantum-to-mqtopt
+        run: |
+          ./build/mlir/tools/quantum-opt/quantum-opt \
+            --pass-pipeline="builtin.module(catalystquantum-to-mqtopt)" \
+            mlir/test/Conversion/quantum.mlir
+      - name: Run conversion -> mqtopt-to-catalystquantum
+        run: |
+          ./build/mlir/tools/quantum-opt/quantum-opt \
+            --pass-pipeline="builtin.module(mqtopt-to-catalystquantum)" \
+            mlir/test/Conversion/mqtopt.mlir

cmake/ExternalDependencies.cmake

@@ -73,3 +73,18 @@ endif()
 
 # Make all declared dependencies available.
 FetchContent_MakeAvailable(${FETCH_PACKAGES})
+
+if(ENABLE_MQT_CORE_MLIR_CATALYST_PLUGIN)
+  # Manually detect the installed Catalyst Python and get its cmake directory.
+  execute_process(
+    COMMAND "${Python_EXECUTABLE}" -c
+            "import catalyst, os; print(os.path.dirname(catalyst.__file__))"
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    OUTPUT_VARIABLE Python_Catalyst_DIR
+    ERROR_QUIET)
+  message(STATUS "Found Catalyst package: ${Python_Catalyst_DIR}")
+
+  # TODO: once the Catalyst Python package provides the necessary files set(Catalyst_DIR
+  # "${Python_Catalyst_DIR}/mlir/build/lib/cmake/catalyst")
+  find_package(Catalyst REQUIRED)
+endif()

mlir/CMakeLists.txt

@@ -26,6 +26,13 @@ string(REPLACE "." ";" MLIR_VERSION_COMPONENTS ${MLIR_VERSION})
 list(GET MLIR_VERSION_COMPONENTS 0 MLIR_VERSION_MAJOR)
 add_compile_definitions(MLIR_VERSION_MAJOR=${MLIR_VERSION_MAJOR})
 
+option(BUILD_MQT_CORE_CATALYST_PLUGIN "Enable Catalyst conversion passes" OFF)
+if(BUILD_MQT_CORE_CATALYST_PLUGIN)
+  message(STATUS "Found MLIR version ${MLIR_VERSION_MAJOR}.")
+  list(APPEND CMAKE_MODULE_PATH "${CATALYST_CMAKE_DIR}")
+  list(APPEND MLIR_INCLUDE_DIRS "${CATALYST_INCLUDE_DIRS}")
+endif()
+
 # Include the TableGen, LLVM and MLIR CMake modules.
 include(TableGen)
 include(AddLLVM)

mlir/include/mlir/CMakeLists.txt

@@ -7,3 +7,4 @@
 # Licensed under the MIT License
 
 add_subdirectory(Dialect)
+add_subdirectory(Conversion)

mlir/include/mlir/Conversion/CMakeLists.txt

@@ -0,0 +1,11 @@
+# Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+# Copyright (c) 2025 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+if(BUILD_MQT_CORE_CATALYST_PLUGIN)
+  add_subdirectory(Catalyst)
+endif()

mlir/include/mlir/Conversion/Catalyst/CMakeLists.txt

@@ -0,0 +1,10 @@
+# Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+# Copyright (c) 2025 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+add_subdirectory(MQTOptToCatalystQuantum)
+add_subdirectory(CatalystQuantumToMQTOpt)

mlir/include/mlir/Conversion/Catalyst/CatalystQuantumToMQTOpt/CMakeLists.txt

@@ -0,0 +1,13 @@
+# Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+# Copyright (c) 2025 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+set(LLVM_TARGET_DEFINITIONS CatalystQuantumToMQTOpt.td)
+mlir_tablegen(CatalystQuantumToMQTOpt.h.inc -gen-pass-decls -name CatalystQuantumToMQTOpt)
+add_public_tablegen_target(CatalystQuantumToMQTOptIncGen)
+
+add_mlir_doc(CatalystQuantumToMQTOpt CatalystQuantumToMQTOpt ./ -gen-pass-doc)

mlir/include/mlir/Conversion/Catalyst/CatalystQuantumToMQTOpt/CatalystQuantumToMQTOpt.h

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+#pragma once
+
+#include <mlir/Pass/Pass.h> // from @llvm-project
+
+namespace mlir::mqt::ir::conversions {
+
+#define GEN_PASS_DECL
+#include "mlir/Conversion/Catalyst/CatalystQuantumToMQTOpt/CatalystQuantumToMQTOpt.h.inc"
+
+#define GEN_PASS_REGISTRATION
+#include "mlir/Conversion/Catalyst/CatalystQuantumToMQTOpt/CatalystQuantumToMQTOpt.h.inc"
+
+} // namespace mlir::mqt::ir::conversions

mlir/include/mlir/Conversion/Catalyst/CatalystQuantumToMQTOpt/CatalystQuantumToMQTOpt.td

@@ -0,0 +1,32 @@
+// Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+// Copyright (c) 2025 Munich Quantum Software Company GmbH
+// All rights reserved.
+//
+// SPDX-License-Identifier: MIT
+//
+// Licensed under the MIT License
+
+include "mlir/Pass/PassBase.td"
+
+def CatalystQuantumToMQTOpt : Pass<"catalystquantum-to-mqtopt"> {
+  let summary = "Convert Catalyst's `Quantum` to MQT's `MQTOpt` dialect.";
+
+  let description = [{
+    This pass converts Catalyst's `Quantum` to MQT's `MQTOpt` dialect.
+    The following operations are currently NOT converted (and instead marked legal):
+    - DeviceInitOp
+    - DeviceReleaseOp
+    - NamedObsOp
+    - ExpvalOp
+    - FinalizeOp
+    - ComputationalBasisOp
+    - StateOp
+    - InitializeOp
+   }];
+
+  // Define dependent dialects
+  let dependentDialects = [
+    "catalyst::quantum::QuantumDialect",
+    "::mqt::ir::opt::MQTOptDialect"
+  ];
+}

mlir/include/mlir/Conversion/Catalyst/MQTOptToCatalystQuantum/CMakeLists.txt

@@ -0,0 +1,13 @@
+# Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+# Copyright (c) 2025 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+set(LLVM_TARGET_DEFINITIONS MQTOptToCatalystQuantum.td)
+mlir_tablegen(MQTOptToCatalystQuantum.h.inc -gen-pass-decls -name MQTOptToCatalystQuantum)
+add_public_tablegen_target(MQTOptToCatalystQuantumIncGen)
+
+add_mlir_doc(MQTOptToCatalystQuantum MQTOptToCatalystQuantum ./ -gen-pass-doc)

mlir/include/mlir/Conversion/Catalyst/MQTOptToCatalystQuantum/MQTOptToCatalystQuantum.h

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+#pragma once
+
+#include <mlir/Pass/Pass.h> // from @llvm-project
+
+namespace mlir::mqt::ir::conversions {
+
+#define GEN_PASS_DECL
+#include "mlir/Conversion/Catalyst/MQTOptToCatalystQuantum/MQTOptToCatalystQuantum.h.inc"
+
+#define GEN_PASS_REGISTRATION
+#include "mlir/Conversion/Catalyst/MQTOptToCatalystQuantum/MQTOptToCatalystQuantum.h.inc"
+
+} // namespace mlir::mqt::ir::conversions

mlir/include/mlir/Conversion/Catalyst/MQTOptToCatalystQuantum/MQTOptToCatalystQuantum.td

@@ -0,0 +1,26 @@
+// Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+// Copyright (c) 2025 Munich Quantum Software Company GmbH
+// All rights reserved.
+//
+// SPDX-License-Identifier: MIT
+//
+// Licensed under the MIT License
+
+include "mlir/Pass/PassBase.td"
+
+def MQTOptToCatalystQuantum : Pass<"mqtopt-to-catalystquantum"> {
+  let summary = "Convert MQT's `MQTOpt` to Catalyst's `Quantum` dialect.";
+
+  let description = [{
+    This pass converts MQT's `MQTOpt` to Catalyst's `Quantum` dialect.
+    The following operations are currently NOT converted (and instead marked legal):
+    - UOp, U2Op
+    - SXOp, SXdgOp
+    - PeresOp, PeresdgOp
+    - ECROp
+  }];
+  let dependentDialects = [
+    "catalyst::quantum::QuantumDialect",
+    "::mqt::ir::opt::MQTOptDialect"
+  ];
+}

mlir/lib/CMakeLists.txt

@@ -7,3 +7,4 @@
 # Licensed under the MIT License
 
 add_subdirectory(Dialect)
+add_subdirectory(Conversion)

mlir/lib/Conversion/CMakeLists.txt

@@ -0,0 +1,11 @@
+# Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+# Copyright (c) 2025 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+if(BUILD_MQT_CORE_CATALYST_PLUGIN)
+  add_subdirectory(Catalyst)
+endif()

mlir/lib/Conversion/Catalyst/CMakeLists.txt

@@ -0,0 +1,10 @@
+# Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+# Copyright (c) 2025 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+add_subdirectory(MQTOptToCatalystQuantum)
+add_subdirectory(CatalystQuantumToMQTOpt)

mlir/lib/Conversion/Catalyst/CatalystQuantumToMQTOpt/CMakeLists.txt

@@ -0,0 +1,14 @@
+# Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+# Copyright (c) 2025 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+file(GLOB CONVERSION_SOURCES *.cpp)
+
+add_mlir_library(CatalystQuantumToMQTOpt ${CONVERSION_SOURCES} LINK_LIBS ${LIBRARIES} DEPENDS
+                 CatalystQuantumToMQTOptIncGen)
+
+target_link_libraries(CatalystQuantumToMQTOpt PRIVATE MLIRQuantum)