✨ Add Python bindings for mqt-cc

.github/workflows/ci.yml

@@ -186,6 +186,8 @@ jobs:
     uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-tests.yml@e7f84f39ce2d3b6c5d1d04526b8f94f98e455143 # v2.2.0
     with:
       runs-on: ${{ matrix.runs-on }}
+      setup-mlir: true
+      llvm-version: 22.1.7
 
   python-coverage:
     name: 🐍 Coverage
@@ -208,6 +210,8 @@ jobs:
     uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-tests.yml@e7f84f39ce2d3b6c5d1d04526b8f94f98e455143 # v2.2.0
     with:
       runs-on: ${{ matrix.runs-on }}
+      setup-mlir: true
+      llvm-version: 22.1.7
 
   python-linter:
     name: 🐍 Lint
@@ -218,6 +222,8 @@ jobs:
       check-stubs: true
       enable-ty: true
       enable-mypy: false
+      setup-mlir: true
+      llvm-version: 22.1.7
 
   build-sdist:
     name: 🚀 CD
@@ -244,6 +250,8 @@ jobs:
     uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml@e7f84f39ce2d3b6c5d1d04526b8f94f98e455143 # v2.2.0
     with:
       runs-on: ${{ matrix.runs-on }}
+      setup-mlir: true
+      llvm-version: 22.1.7
 
   # this job does nothing and is only used for branch protection
   required-checks-pass:

.readthedocs.yaml

@@ -32,7 +32,7 @@ build:
       - asdf install uv latest
       - asdf global uv latest
       # Install MLIR
-      - curl -LsSf https://github.com/munich-quantum-software/setup-mlir/releases/latest/download/setup-mlir.sh | bash -s -- -v 22.1.0 -p $HOME/mlir
+      - curl -LsSf https://github.com/munich-quantum-software/setup-mlir/releases/download/v1.4.1/setup-mlir.sh | bash -s -- -v 22.1.7 -p $HOME/mlir
       # Build the MLIR documentation
       - uvx cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_MQT_CORE_MLIR=ON -DMLIR_DIR=$HOME/mlir/lib/cmake/mlir
       - uvx cmake --build build --target mlir-doc

CMakeLists.txt

@@ -119,11 +119,11 @@ if(MQT_CORE_INSTALL)
 endif()
 
 cmake_dependent_option(BUILD_MQT_CORE_QIR_RUNNER "Build the QIR runner of the MQT Core project" ON
-                       "BUILD_MQT_CORE_MLIR" OFF)
+                       "BUILD_MQT_CORE_MLIR;NOT BUILD_MQT_CORE_BINDINGS" OFF)
 
 cmake_dependent_option(
   BUILD_MQT_CORE_QDMI_DDSIM_WITH_QIR "Enable QIR program format support for the DDSIM QDMI Device"
-  ON "BUILD_MQT_CORE_MLIR" OFF)
+  ON "BUILD_MQT_CORE_MLIR;NOT BUILD_MQT_CORE_BINDINGS" OFF)
 
 # add main library code
 add_subdirectory(src)

UPGRADING.md

@@ -6,7 +6,7 @@ of changes including minor and patch releases, please refer to the
 
 ## [Unreleased]
 
-### MLIR enabled by default for C++ builds
+### MLIR enabled by default for C++ and Python package builds
 
 The MLIR-based functionality within MQT Core has long been experimental and
 opt-in. Starting with this release, MLIR is enabled by default for C++ library
@@ -20,11 +20,16 @@ Please follow the instructions there to install the distribution for your
 platform. You can then point CMake to the installation directory using the
 `-DMLIR_DIR=/path/to/mlir/installation/lib/cmake/mlir` option.
 
+As of this release, MLIR is also enabled for Python package builds, since the
+package now exposes an MLIR-based compiler entry point in `mqt.core.mlir`.
+
+For local development, you can configure `MLIR_DIR` once in a repository-local
+`.env` file (for example, `MLIR_DIR=/path/to/installation/lib/cmake/mlir`). MQT
+Core's CMake setup will pick this up automatically when `MLIR_DIR` is not
+otherwise provided.
+
 The MLIR components can still be manually disabled by passing
-`-DBUILD_MQT_CORE_MLIR=OFF` to CMake. MLIR is also not enabled for the Python
-package builds because no functionality depends on it yet. This is expected to
-change in the future, when we expose the MLIR-based functionality via the Python
-package.
+`-DBUILD_MQT_CORE_MLIR=OFF` to CMake.
 
 Known limitations:
 
@@ -34,9 +39,6 @@ Known limitations:
 - AppleClang 17+ is required to build MQT Core with MLIR enabled due to some
   C++20 features being used that are not yet properly supported by older
   versions.
-- Our pre-built distributions are compiled in Release mode. On Windows, this
-  leads to ABI incompatibilities with debug builds. Either build in Release mode
-  or build LLVM from source in Debug mode to resolve this.
 
 ### Removal of the density matrix support from the DD package
 

bindings/CMakeLists.txt

@@ -10,3 +10,7 @@ add_subdirectory(ir)
 add_subdirectory(dd)
 add_subdirectory(fomac)
 add_subdirectory(na)
+
+if(BUILD_MQT_CORE_MLIR)
+  add_subdirectory(mlir)
+endif()

bindings/mlir/CMakeLists.txt

@@ -0,0 +1,44 @@
+# Copyright (c) 2023 - 2026 Chair for Design Automation, TUM
+# Copyright (c) 2025 - 2026 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+set(TARGET_NAME "${MQT_CORE_TARGET_NAME}-mlir-bindings")
+
+if(NOT TARGET ${TARGET_NAME})
+  # collect source files
+  file(GLOB_RECURSE SOURCES *.cpp)
+
+  # declare the Python module
+  add_mqt_python_binding_nanobind(
+    CORE
+    ${TARGET_NAME}
+    ${SOURCES}
+    MODULE_NAME
+    mlir
+    INSTALL_DIR
+    .
+    LINK_LIBS
+    MQTCompilerPipeline
+    MLIRQCTranslation
+    MLIRParser
+    MLIRJeffTranslation
+    MLIRJeffToQCO
+    MLIRQCOToQC
+    MLIRTargetLLVMIRExport
+    MLIRBuiltinToLLVMIRTranslation
+    MLIRLLVMToLLVMIRTranslation
+    MQT::MLIRSupport
+    MQT::CoreIR)
+
+  # install the Python stub file in editable mode for better IDE support
+  if(SKBUILD_STATE STREQUAL "editable")
+    install(
+      FILES ${PROJECT_SOURCE_DIR}/python/mqt/core/mlir.pyi
+      DESTINATION .
+      COMPONENT ${MQT_CORE_TARGET_NAME}_Python)
+  endif()
+endif()