♻️ Replace pybind11 with nanobind

.clang-tidy

@@ -30,7 +30,8 @@ Checks: |
   readability-*,
   -readability-identifier-length,
   -readability-magic-numbers,
-  -readability-function-cognitive-complexity
+  -readability-function-cognitive-complexity,
+  -*-prefer-static-over-anonymous-namespace
 
 CheckOptions:
   - key: readability-identifier-naming.ClassCase
@@ -73,5 +74,3 @@ CheckOptions:
     value: CamelCase
   - key: readability-identifier-naming.VariableCase
     value: camelBack
-  - key: misc-include-cleaner.IgnoreHeaders
-    value: pybind11/detail/.*

.github/workflows/cd.yml

@@ -12,7 +12,7 @@ permissions:
 jobs:
   build-sdist:
     name: 🐍 Packaging
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-sdist.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-sdist.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
 
   # Builds wheels on all supported platforms using cibuildwheel.
   # The wheels are uploaded as GitHub artifacts `dev-cibw-*` or `cibw-*`, depending on whether
@@ -31,7 +31,7 @@ jobs:
             windows-2022,
             windows-11-arm,
           ]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       runs-on: ${{ matrix.runs-on }}
 

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ concurrency:
 jobs:
   change-detection:
     name: 🔍 Change
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-change-detection.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-change-detection.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
 
   cpp-tests-ubuntu:
     name: 🇨‌ Test 🐧
@@ -30,7 +30,7 @@ jobs:
           - runs-on: ubuntu-24.04
             compiler: gcc
             config: Debug
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-ubuntu.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-ubuntu.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       runs-on: ${{ matrix.runs-on }}
       compiler: ${{ matrix.compiler }}
@@ -50,7 +50,7 @@ jobs:
           - runs-on: macos-14
             compiler: clang
             config: Debug
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-macos.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-macos.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       runs-on: ${{ matrix.runs-on }}
       compiler: ${{ matrix.compiler }}
@@ -71,7 +71,7 @@ jobs:
           - runs-on: windows-2022
             compiler: msvc
             config: Debug
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-windows.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-windows.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       runs-on: ${{ matrix.runs-on }}
       compiler: ${{ matrix.compiler }}
@@ -88,7 +88,7 @@ jobs:
         runs-on: [ubuntu-24.04, ubuntu-24.04-arm]
         compiler: [gcc, clang, clang-20, clang-21]
         config: [Release, Debug]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-ubuntu.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-ubuntu.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       runs-on: ${{ matrix.runs-on }}
       compiler: ${{ matrix.compiler }}
@@ -105,7 +105,7 @@ jobs:
         runs-on: [macos-14, macos-15, macos-15-intel]
         compiler: [clang, clang-20, clang-21, gcc-14, gcc-15]
         config: [Release, Debug]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-macos.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-macos.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       runs-on: ${{ matrix.runs-on }}
       compiler: ${{ matrix.compiler }}
@@ -123,7 +123,7 @@ jobs:
         runs-on: [windows-2022, windows-2025, windows-11-arm]
         compiler: [msvc, clang]
         config: [Release]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-windows.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-windows.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       runs-on: ${{ matrix.runs-on }}
       compiler: ${{ matrix.compiler }}
@@ -133,7 +133,7 @@ jobs:
     name: 🇨‌ Coverage
     needs: change-detection
     if: fromJSON(needs.change-detection.outputs.run-cpp-tests)
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-coverage.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-coverage.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     permissions:
       contents: read
       id-token: write
@@ -142,14 +142,14 @@ 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@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-linter.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       cmake-args: -DBUILD_MQT_CORE_BENCHMARKS=ON -DBUILD_MQT_CORE_MLIR=ON -DBUILD_MQT_CORE_BINDINGS=ON
       clang-version: 21
       build-project: true
       files-changed-only: true
       setup-python: true
-      install-pkgs: "pybind11==3.0.1"
+      install-pkgs: "nanobind==2.10.2"
       cpp-linter-extra-args: "-std=c++20"
       setup-mlir: true
 
@@ -168,15 +168,15 @@ jobs:
             macos-14,
             windows-2022,
           ]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-tests.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-tests.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       runs-on: ${{ matrix.runs-on }}
 
   python-coverage:
     name: 🐍 Coverage
     needs: [change-detection, python-tests]
     if: fromJSON(needs.change-detection.outputs.run-python-tests)
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-coverage.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-coverage.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     permissions:
       contents: read
       id-token: write
@@ -190,23 +190,24 @@ jobs:
       fail-fast: false
       matrix:
         runs-on: [macos-15, windows-2025]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-tests.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-tests.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       runs-on: ${{ matrix.runs-on }}
 
   python-linter:
     name: 🐍 Lint
     needs: change-detection
     if: fromJSON(needs.change-detection.outputs.run-python-tests)
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-linter.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-linter.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
+      check-stubs: true
       enable-ty: true
 
   build-sdist:
     name: 🚀 CD
     needs: change-detection
     if: fromJSON(needs.change-detection.outputs.run-cd)
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-sdist.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-sdist.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
 
   build-wheel:
     name: 🚀 CD
@@ -224,7 +225,7 @@ jobs:
             windows-2022,
             windows-11-arm,
           ]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       runs-on: ${{ matrix.runs-on }}
 

.github/workflows/upstream.yml

@@ -19,7 +19,7 @@ jobs:
       fail-fast: false
       matrix:
         runs-on: [ubuntu-24.04, macos-14, windows-2022]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-qiskit-upstream-tests.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-qiskit-upstream-tests.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       runs-on: ${{ matrix.runs-on }}
       setup-z3: true
@@ -28,7 +28,7 @@ jobs:
     name: Create issue on failure
     needs: qiskit-upstream-tests
     if: ${{ always() }}
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-qiskit-upstream-issue.yml@654680ab77b3af8226a9f5cd9acfd157bd106f17 # v1.17.5
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-qiskit-upstream-issue.yml@2acb39781fa6ca7baa10c2a31a508cb0e2292d9e # v1.17.6
     with:
       tests-result: ${{ needs.qiskit-upstream-tests.result }}
     permissions:

.license-tools-config.json

@@ -33,6 +33,7 @@
     ".*\\.tex",
     "uv\\.lock",
     "py\\.typed",
-    ".*build.*"
+    ".*build.*",
+    "core_patterns.txt"
   ]
 }

.pre-commit-config.yaml

@@ -58,6 +58,12 @@ repos:
       - id: rst-directive-colons
       - id: rst-inline-touching-normal
 
+  # Check for license headers
+  - repo: https://github.com/emzeat/mz-lictools
+    rev: v2.9.0
+    hooks:
+      - id: license-tools
+
   # Ensure uv lock file is up-to-date
   - repo: https://github.com/astral-sh/uv-pre-commit
     rev: 0.9.18
@@ -101,12 +107,6 @@ repos:
       - id: blacken-docs
         additional_dependencies: [black==25.*]
 
-  # Check for license headers
-  - repo: https://github.com/emzeat/mz-lictools
-    rev: v2.9.0
-    hooks:
-      - id: license-tools
-
   # Clang-format the C++ part of the code base automatically
   - repo: https://github.com/pre-commit/mirrors-clang-format
     rev: v21.1.8

CHANGELOG.md

@@ -25,6 +25,9 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Changed
 
+- ♻️ Migrate Python bindings from `pybind11` to `nanobind` ([#1383]) ([**@denialhaag**], [**@burgholzer**])
+- 📦️ Provide Stable ABI wheels for Python 3.12+ ([#1383]) ([**@burgholzer**], [**@denialhaag**])
+- 🚚 Create dedicated `mqt.core.na` submodule to closely follow the structure of other submodules ([#1383]) ([**@burgholzer**])
 - ✨ Add common definitions and utilities for QDMI ([#1355]) ([**@burgholzer**])
 - 🚚 Move `NA` QDMI device in its right place next to other QDMI devices ([#1355]) ([**@burgholzer**])
 - ♻️ Allow repeated loading of QDMI device library with potentially different session configurations ([#1355]) ([**@burgholzer**])
@@ -285,6 +288,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 
 [#1385]: https://github.com/munich-quantum-toolkit/core/pull/1385
 [#1384]: https://github.com/munich-quantum-toolkit/core/pull/1384
+[#1383]: https://github.com/munich-quantum-toolkit/core/pull/1383
 [#1382]: https://github.com/munich-quantum-toolkit/core/pull/1382
 [#1381]: https://github.com/munich-quantum-toolkit/core/pull/1381
 [#1378]: https://github.com/munich-quantum-toolkit/core/pull/1378

CMakeLists.txt

@@ -7,7 +7,7 @@
 # Licensed under the MIT License
 
 # set required cmake version
-cmake_minimum_required(VERSION 3.24...4.0)
+cmake_minimum_required(VERSION 3.24...4.2)
 
 project(
   mqt-core
@@ -47,7 +47,8 @@ if(BUILD_MQT_CORE_BINDINGS)
   endif()
 
   # top-level call to find Python
-  find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module)
+  find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module
+                                               ${SKBUILD_SABI_COMPONENT})
 endif()
 
 # check if this is the master project or used via add_subdirectory

README.md

@@ -107,7 +107,6 @@ The project relies on some external dependencies:
 
 - [boost/multiprecision](https://github.com/boostorg/multiprecision): A library for multiprecision arithmetic (used in the ZX package).
 - [nlohmann/json](https://github.com/nlohmann/json): A JSON library for modern C++.
-- [pybind/pybind11_json](https://github.com/pybind/pybind11_json): A library for using `nlohmann::json` with `pybind11` (only used for creating the Python bindings).
 - [google/googletest](https://github.com/google/googletest): A testing framework for C++ (only used in tests).
 
 CMake will automatically look for installed versions of these libraries. If it does not find them, they will be fetched automatically at configure time via the [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) module (check out the documentation for more information on how to customize this behavior).

UPGRADING.md

@@ -52,12 +52,24 @@ In the process, the `mqt-core-dd-compare` entry point as well as the `evaluation
 The `eval/dd_evaluation.py` script acts as a drop-in replacement for the previous CLI entry point.
 Since the `eval` directory is not part of the Python package, this functionality is only available via source installations or by cloning the repository.
 
-### Removal of Python 3.13t wheels
+### Python wheels
 
+This release contains two changes to the distributed wheels.
+
+First, we have removed all wheels for Python 3.13t.
 Free-threading Python was introduced as an experimental feature in Python 3.13.
 It became stable in Python 3.14.
-To conserve space on PyPI and to reduce the CD build times, we have removed all wheels for Python 3.13t from our CI.
-We continue to provide wheels for the regular Python versions 3.10 to 3.14, as well as 3.14t.
+
+Second, for Python 3.12+, we are now providing Stable ABI wheels instead of separate version-specific wheels.
+This was enabled by migrating our Python bindings from `pybind11` to `nanobind`.
+
+Both of these changes were made in the interest of conserving PyPI space and reducing CI/CD build times.
+The full list of wheels now reads:
+
+- 3.10
+- 3.11
+- 3.12+ Stable ABI
+- 3.14t
 
 ## [3.3.0]
 

bindings/.clang-tidy

@@ -0,0 +1,6 @@
+InheritParentConfig: true
+Checks: |
+  -*-avoid-c-arrays,
+  -cppcoreguidelines-owning-memory,
+  -misc-redundant-expression,
+  -*-pro-bounds-avoid-unchecked-container-access

bindings/CMakeLists.txt

@@ -6,14 +6,7 @@
 #
 # Licensed under the MIT License
 
-# add the IR bindings package
 add_subdirectory(ir)
-
-# add the DD bindings package
 add_subdirectory(dd)
-
-# add the NA bindings package
-add_subdirectory(na)
-
-# add the FoMaC bindings package
 add_subdirectory(fomac)
+add_subdirectory(na)

bindings/core_patterns.txt

@@ -0,0 +1,3 @@
+_hashable_values_:
+
+_unhashable_values_map_:

bindings/dd/CMakeLists.txt

@@ -11,7 +11,7 @@ if(NOT TARGET ${MQT_CORE_TARGET_NAME}-dd-bindings)
   file(GLOB_RECURSE DD_SOURCES **.cpp)
 
   # declare the Python module
-  add_mqt_python_binding(
+  add_mqt_python_binding_nanobind(
     CORE
     ${MQT_CORE_TARGET_NAME}-dd-bindings
     ${DD_SOURCES}