MLIR Plugin

.clang-tidy

@@ -1,4 +1,5 @@
 FormatStyle: file
+HeaderFilterRegex: "^(?!.*plugins/).*"
 
 Checks: |
   bugprone-*,

.github/workflows/ci.yml

@@ -155,7 +155,7 @@ jobs:
     name: 🇨‌ Lint
     needs: change-detection
     if: fromJSON(needs.change-detection.outputs.run-cpp-linter)
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-linter.yml@ea4fccbb432596cbb6840a9608d6376b6b2c8ff7 # v1.17.2
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-linter.yml@v1.17
     with:
       cmake-args: -DBUILD_MQT_CORE_BENCHMARKS=ON -DBUILD_MQT_CORE_MLIR=ON -DBUILD_MQT_CORE_BINDINGS=ON
       clang-version: 21
@@ -164,6 +164,7 @@ jobs:
       setup-python: true
       install-pkgs: "pybind11==3.0.0"
       cpp-linter-extra-args: "-std=c++20"
+      cpp-linter-ignore-extra: "plugins/**"
 
   python-tests:
     name: 🐍 Test
@@ -243,6 +244,9 @@ jobs:
   mlir-tests:
     name: 🐉 Test
     needs: change-detection
+    permissions:
+      contents: read
+      id-token: write
     if: fromJSON(needs.change-detection.outputs.run-mlir)
     uses: ./.github/workflows/reusable-mlir-tests.yml
 

.github/workflows/ci_mlir_plugin.yml

@@ -0,0 +1,187 @@
+name: MLIR Plugin CI
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "plugins/**"
+  pull_request:
+    paths:
+      - "plugins/**"
+      - ".github/workflows/ci_mlir_plugin.yml"
+  merge_group:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  cpp-test-mlir-catalyst-plugin-exact-mlir:
+    name: 🧩 Test MLIR Catalyst Plugin on ${{ matrix.runs-on }} from exact MLIR source
+    runs-on: ${{ matrix.runs-on }}
+    strategy:
+      matrix:
+        runs-on: [ubuntu-24.04, ubuntu-24.04-arm, macos-14]
+      fail-fast: false
+    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 gcc as compiler
+      - name: Set up GCC as compiler
+        if: runner.os == 'Linux'
+        run: |
+          echo "C_COMPILER=gcc-14" >> $GITHUB_ENV
+          echo "CXX_COMPILER=g++-14" >> $GITHUB_ENV
+          echo "CC=gcc-14" >> $GITHUB_ENV
+          echo "CXX=g++-14" >> $GITHUB_ENV
+
+      # 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: mlir-plugin-${{ matrix.runs-on }}-exact-mlir
+
+      # 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
+
+      # Check out the LLVM commit Catalyst is based on
+      - name: Checkout llvm
+        uses: actions/checkout@v4
+        with:
+          repository: llvm/llvm-project
+          ref: f8cb7987c64dcffb72414a40560055cb717dbf74
+          path: llvm-project
+
+      # Install LLVM
+      - name: Install LLVM
+        working-directory: llvm-project
+        run: |
+          cmake \
+            -S llvm \
+            -B build_llvm \
+            -G Ninja \
+            -DLLVM_ENABLE_PROJECTS=mlir \
+            -DLLVM_BUILD_EXAMPLES=OFF \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DLLVM_BUILD_TESTS=OFF \
+            -DLLVM_INCLUDE_TESTS=OFF \
+            -DLLVM_INCLUDE_EXAMPLES=OFF \
+            -DLLVM_ENABLE_ASSERTIONS=ON \
+            -DLLVM_ENABLE_ZLIB=FORCE_ON \
+            -DLLVM_ENABLE_ZSTD=OFF \
+            -DCMAKE_CXX_VISIBILITY_PRESET=default
+          cmake --build build_llvm --config Release
+          echo "MLIR_DIR=$(pwd)/build_llvm/lib/cmake/mlir" >> $GITHUB_ENV
+          echo "LLVM_DIR=$(pwd)/build_llvm/lib/cmake/llvm" >> $GITHUB_ENV
+
+      # Build the plugin package
+      - name: Build mqt-core-catalyst-plugin
+        working-directory: plugins/catalyst
+        run: uv sync --verbose --active
+
+        # Print shared library dependencies for the plugin
+      - name: Print shared library dependencies for mqt-core-catalyst-plugin
+        run: |
+          if [ "$(uname)" = "Linux" ]; then
+              ldd .venv/lib/python3.13/site-packages/mqt/core/plugins/catalyst/mqt-core-catalyst-plugin.so || true
+          elif [ "$(uname)" = "Darwin" ]; then
+              otool -l .venv/lib/python3.13/site-packages/mqt/core/plugins/catalyst/mqt-core-catalyst-plugin.dylib || true
+          fi
+
+      # Print shared library dependencies for Catalyst
+      - name: Print shared library dependencies for Catalyst
+        run: |
+          if [ "$(uname)" = "Linux" ]; then
+              ldd $(which catalyst) || true
+          elif [ "$(uname)" = "Darwin" ]; then
+              otool -l $(which catalyst) || true
+          fi
+
+      # Reconfigure CMake for LIT
+      - name: Reconfigure CMake for LIT
+        working-directory: plugins/catalyst
+        run: |
+          BUILD_DIR=$(find build -type d -name Release | head -n1)
+          if [ -z "$BUILD_DIR" ]; then
+            BUILD_DIR="build"
+          fi
+
+          # Verify lit is installed, install if missing
+          if ! command -v lit &> /dev/null; then
+            echo "lit not found, installing..."
+            python -m pip install lit
+          fi
+
+          cmake -S . \
+            -B "$BUILD_DIR" \
+            -DLLVM_EXTERNAL_LIT=$(which lit) \
+            -DPython3_EXECUTABLE=$(which python) \
+            -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+
+      # Run clang-tidy on plugin code
+      - name: Run clang-tidy on plugin
+        working-directory: plugins/catalyst
+        run: |
+          BUILD_DIR=$(find build -type d -name Release | head -n1)
+          if [ -z "$BUILD_DIR" ]; then
+            BUILD_DIR="build"
+          fi
+
+          # Check if compilation database exists
+          if [ ! -f "$BUILD_DIR/compile_commands.json" ]; then
+            echo "No compilation database found, skipping clang-tidy"
+            exit 0
+          fi
+
+          # Find all C++ source files in the plugin
+          FILES=$(find lib include -name "*.cpp" -o -name "*.h" 2>/dev/null || true)
+          if [ -z "$FILES" ]; then
+            echo "No C++ files found to analyze"
+            exit 0
+          fi
+
+          # Find Catalyst include directory
+          CATALYST_INCLUDE=$(find .venv -path "*/catalyst/include" -type d | head -n1)
+          if [ -z "$CATALYST_INCLUDE" ]; then
+            echo "Catalyst include directory not found, running without extra includes"
+            EXTRA_ARGS=""
+          else
+            echo "Found Catalyst includes at: $CATALYST_INCLUDE"
+            EXTRA_ARGS="--extra-arg=-I$CATALYST_INCLUDE"
+          fi
+
+          echo "Running clang-tidy on plugin files..."
+          echo "$FILES" | xargs clang-tidy \
+            -p="$BUILD_DIR" \
+            --config-file=.clang-tidy \
+            --format-style=file \
+            $EXTRA_ARGS \
+            || echo "clang-tidy completed with warnings"
+
+      # Run the MLIR LIT tests
+      - name: Run LIT tests
+        working-directory: plugins/catalyst
+        run: |
+          BUILD_DIR=$(find build -type d -name Release | head -n1)
+          if [ -z "$BUILD_DIR" ]; then
+            BUILD_DIR="build"
+          fi
+          ninja -C "$BUILD_DIR" check-mqt-core-catalyst-plugin
+
+      # Run the plugin Python tests
+      - name: Run pytest for mqt-core-catalyst-plugin
+        working-directory: plugins/catalyst
+        run: python -m pytest -s --verbose

.gitignore

@@ -136,8 +136,9 @@ python/**/_version.py
 # SKBuild cache dir
 _skbuild/
 
-# Any build dirs in the tests
+# Any build dirs
 test/**/build/
+plugins/**/build/
 
 # Common editor files
 *~
@@ -167,9 +168,7 @@ Thumbs.db
 /distro/plans/main.fmf
 /distro/tests/main.fmf
 
-/docs/**/build
 .vs
-out/build
 
 node_modules/
 wheelhouse/

cmake/SetupMLIR.cmake

@@ -16,7 +16,9 @@ set(MQT_MLIR_MIN_VERSION
 # MLIR must be installed on the system
 find_package(MLIR REQUIRED CONFIG)
 if(MLIR_VERSION VERSION_LESS MQT_MLIR_MIN_VERSION)
-  message(FATAL_ERROR "MLIR version must be at least ${MQT_MLIR_MIN_VERSION}")
+  message(
+    FATAL_ERROR "MLIR version must be at least ${MQT_MLIR_MIN_VERSION} but found ${MLIR_VERSION}")
+
 endif()
 message(STATUS "Using MLIRConfig.cmake in: ${MLIR_DIR}")
 message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")

plugins/catalyst/.clang-format

@@ -0,0 +1 @@
+BasedOnStyle: InheritParentConfig

plugins/catalyst/.clang-tidy

@@ -0,0 +1,2 @@
+InheritParentConfig: true
+HeaderFilterRegex: ".*"

plugins/catalyst/CMakeLists.txt

@@ -0,0 +1,65 @@
+# 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 required cmake version
+cmake_minimum_required(VERSION 3.24...4.0)
+
+project(
+  mqt-core-catalyst-plugin
+  LANGUAGES C CXX
+  VERSION 0.1.0
+  DESCRIPTION "MQT Core MLIR Plugin for Catalyst")
+
+set(CMAKE_CXX_STANDARD
+    20
+    CACHE STRING "C++ standard to conform to")
+
+if(ENABLE_COVERAGE)
+  add_compile_options(--coverage -O0)
+  add_link_options(--coverage)
+endif()
+
+include(cmake/ExternalDependencies.cmake)
+
+set(MQT_MLIR_PLUGIN_SOURCE_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include")
+set(MQT_MLIR_PLUGIN_BUILD_INCLUDE_DIR "${CMAKE_CURRENT_BINARY_DIR}/include")
+
+# MLIR must be installed on the system
+find_package(MLIR REQUIRED CONFIG)
+
+# Add the paths to the MLIR and LLVM CMake modules.
+list(APPEND CMAKE_MODULE_PATH "${MLIR_CMAKE_DIR}")
+list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
+
+# Include the TableGen, LLVM and MLIR CMake modules.
+include(TableGen)
+include(AddLLVM)
+include(AddMLIR)
+include(HandleLLVMOptions)
+
+include_directories(${LLVM_INCLUDE_DIRS})
+include_directories(${MLIR_INCLUDE_DIRS})
+include_directories(BEFORE ${MQT_MLIR_PLUGIN_SOURCE_INCLUDE_DIR})
+include_directories(BEFORE ${MQT_MLIR_PLUGIN_BUILD_INCLUDE_DIR})
+include_directories(${CATALYST_INCLUDE_DIRS})
+
+link_directories(${LLVM_BUILD_LIBRARY_DIR})
+add_definitions(${LLVM_DEFINITIONS})
+
+if(APPLE)
+  set(BASEPOINT @loader_path)
+else()
+  set(BASEPOINT $ORIGIN)
+endif()
+set(CMAKE_INSTALL_RPATH ${BASEPOINT} ${BASEPOINT}/${CMAKE_INSTALL_LIBDIR})
+set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
+set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)
+
+add_subdirectory(include)
+add_subdirectory(lib)
+add_subdirectory(test)

plugins/catalyst/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+Copyright (c) 2025 Munich Quantum Software Company GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.