⬆️🐍 Adopt nanobind 3 split-mode wheels

.github/workflows/cd.yml

@@ -32,6 +32,8 @@ jobs:
     uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml@f33c11c5cf68957b3074fff11ae43cfce2aaf593 # v2.2.3
     with:
       runs-on: ${{ matrix.runs-on }}
+      setup-mlir: true
+      llvm-version: 22.1.8
     permissions:
       contents: read
 

.github/workflows/ci.yml

@@ -117,7 +117,7 @@ jobs:
       build-project: true
       files-changed-only: true
       setup-python: true
-      install-pkgs: "nanobind==2.15.0"
+      install-pkgs: "nanobind==3.0.0"
       cpp-linter-extra-args: "-std=c++20 -Wunused-template"
       # Vendored third-party headers are checked upstream and are not maintained
       # according to MQT Core's clang-tidy configuration.

CHANGELOG.md

@@ -84,6 +84,18 @@ releases may include breaking changes.
 
 ### Changed
 
+- 💥 Require Python 3.11 or newer ([#2209]) ([**@denialhaag**],
+  [**@burgholzer**])
+- ⬆️ Update `nanobind` to version 3.0.0 ([#2209]) ([**@denialhaag**],
+  [**@burgholzer**])
+- 📦 Publish one split-mode `cp311-abi3` wheel for GIL-enabled CPython 3.11 and
+  newer ([#2209]) ([**@denialhaag**], [**@burgholzer**])
+- 📦 Publish one `cp315-abi3t` wheel for free-threaded CPython 3.15 and newer
+  ([#2209]) ([**@denialhaag**], [**@burgholzer**])
+- ⚡ Remove an extra dense copy from `VectorDD.get_vector` ([#2209])
+  ([**@burgholzer**])
+- 🐛 Protect process-wide DD, IR, and QDMI state for free-threaded Python
+  ([#2209]) ([**@burgholzer**])
 - 💥 Prune dead and misleading CoreIR APIs and remove random-number generator
   state from `QuantumComputation` ([#2111], [#2112]) ([**@simon1hofmann**])
 - 💥 Update QIR execution for QIR 2.1, isolated runtimes, reproducible
@@ -792,6 +804,7 @@ for previous changelogs._
 
 <!-- PR links -->
 
+[#2209]: https://github.com/munich-quantum-toolkit/core/pull/2209
 [#2211]: https://github.com/munich-quantum-toolkit/core/pull/2211
 [#2210]: https://github.com/munich-quantum-toolkit/core/pull/2210
 [#2216]: https://github.com/munich-quantum-toolkit/core/pull/2216

CMakeLists.txt

@@ -48,13 +48,8 @@ if(BUILD_MQT_CORE_BINDINGS)
       ON
       CACHE BOOL "Prevent multiple searches for Python and instead cache the results.")
 
-  if(DISABLE_GIL)
-    message(STATUS "Disabling Python GIL")
-    add_compile_definitions(Py_GIL_DISABLED)
-  endif()
-
   # top-level call to find Python
-  find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module
+  find_package(Python 3.11 REQUIRED COMPONENTS Interpreter Development.Module
                                                ${SKBUILD_SABI_COMPONENT})
 endif()
 

UPGRADING.md

@@ -14,6 +14,24 @@ factories. Move required implementations to the package that uses them. The
 `BUILD_MQT_CORE_BENCHMARKS` option and its legacy DD evaluation target were also
 removed.
 
+### Python 3.11 and split-mode wheels
+
+MQT Core now requires Python 3.11 or newer. Upgrade the Python environment
+before installing this release.
+
+MQT Core now uses nanobind 3 split mode. One `cp311-abi3` wheel supports
+GIL-enabled CPython 3.11 and newer. Free-threaded support starts with CPython
+3.15 and uses a separate `cp315-abi3t` wheel. MQT Core no longer publishes
+free-threaded CPython 3.13 or 3.14 wheels.
+
+nanobind 3 changes the nanobind ABI. Rebuild downstream native Python extensions
+that use MQT Core's nanobind-bound C++ types. Pure Python consumers do not need
+to recompile anything.
+
+The Python bindings depend on `nanobind-backend`, which supplies the
+interpreter-specific nanobind runtime. This dependency does not change the C++
+API or the Python import paths.
+
 ### Program serialization for QDMI Qiskit backends
 
 The Qiskit backend no longer decides in its own code how to turn a circuit into

bindings/dd/register_dd_package.cpp

@@ -323,7 +323,7 @@ Specifically, it
       [](dd::Package& p, const dd::vEdge& v, const qc::NonUnitaryOperation& op,
          const std::vector<bool>& measurements,
          const qc::Permutation& perm = {}) {
-        static std::mt19937_64 rng(std::random_device{}());
+        static thread_local std::mt19937_64 rng(std::random_device{}());
         auto measurementsCopy = measurements;
         return std::pair{
             applyMeasurement(op, v, p, rng, measurementsCopy, perm),
@@ -351,7 +351,7 @@ Specifically, it
       "apply_reset",
       [](dd::Package& p, const dd::vEdge& v, const qc::NonUnitaryOperation& op,
          const qc::Permutation& perm = {}) {
-        static std::mt19937_64 rng(std::random_device{}());
+        static thread_local std::mt19937_64 rng(std::random_device{}());
         return applyReset(op, v, p, rng, perm);
       },
       "vec"_a, "operation"_a, "permutation"_a = qc::Permutation{},
@@ -399,7 +399,7 @@ Specifically, it
   dd.def(
       "measure_collapsing",
       [](dd::Package& p, dd::vEdge& v, const dd::Qubit q) {
-        static std::mt19937_64 rng(std::random_device{}());
+        static thread_local std::mt19937_64 rng(std::random_device{}());
         return p.measureOneCollapsing(v, q, rng);
       },
       "vec"_a, "qubit"_a, R"pb(Measure a qubit and collapse the DD.
@@ -418,7 +418,7 @@ Specifically, it
   dd.def(
       "measure_all",
       [](dd::Package& p, dd::vEdge& v, const bool collapse = false) {
-        static std::mt19937_64 rng(std::random_device{}());
+        static thread_local std::mt19937_64 rng(std::random_device{}());
         return p.measureAll(v, collapse, rng);
       },
       "vec"_a, "collapse"_a = false, R"pb(Measure all qubits.

bindings/dd/register_matrix_dds.cpp

@@ -44,10 +44,11 @@ Matrix getMatrix(const dd::mEdge& m, const size_t numQubits,
 
   if (numQubits == 0U) {
     auto dataPtr = std::make_unique<std::complex<dd::fp>>(m.w);
-    auto* data = dataPtr.release();
+    auto* const data = dataPtr.get();
     const nb::capsule owner(data, [](void* ptr) noexcept {
       delete static_cast<std::complex<dd::fp>*>(ptr);
     });
+    [[maybe_unused]] const auto* const releasedDataPtr = dataPtr.release();
     return Matrix(data, {1, 1}, owner);
   }
 
@@ -60,10 +61,11 @@ Matrix getMatrix(const dd::mEdge& m, const size_t numQubits,
         dataPtr[(i * dim) + j] = c;
       },
       numQubits, threshold);
-  auto* data = dataPtr.release();
+  auto* const data = dataPtr.get();
   const nb::capsule owner(data, [](void* ptr) noexcept {
     delete[] static_cast<std::complex<dd::fp>*>(ptr);
   });
+  [[maybe_unused]] const auto* const releasedDataPtr = dataPtr.release();
   return Matrix(data, {dim, dim}, owner);
 }
 

bindings/dd/register_vector_dds.cpp

@@ -20,7 +20,6 @@
 #include <nanobind/stl/string.h>  // NOLINT(misc-include-cleaner)
 #include <nanobind/stl/vector.h>  // NOLINT(misc-include-cleaner)
 
-#include <algorithm>
 #include <cmath>
 #include <complex>
 #include <cstddef>
@@ -38,14 +37,14 @@ using Vector = nb::ndarray<nb::numpy, std::complex<dd::fp>, nb::ndim<1>>;
 
 // NOLINTNEXTLINE(misc-use-internal-linkage)
 Vector getVector(const dd::vEdge& v, const dd::fp threshold) {
-  auto vec = v.getVector(threshold);
-  auto dataPtr = std::make_unique<std::complex<dd::fp>[]>(vec.size());
-  std::ranges::copy(vec, dataPtr.get());
-  auto* data = dataPtr.release();
-  const nb::capsule owner(data, [](void* ptr) noexcept {
-    delete[] static_cast<std::complex<dd::fp>*>(ptr);
+  auto dataPtr = std::make_unique<dd::CVec>(v.getVector(threshold));
+  auto* const data = dataPtr->data();
+  const auto size = dataPtr->size();
+  const nb::capsule owner(dataPtr.get(), [](void* ptr) noexcept {
+    delete static_cast<dd::CVec*>(ptr);
   });
-  return Vector(data, {vec.size()}, owner);
+  [[maybe_unused]] const auto* const releasedDataPtr = dataPtr.release();
+  return Vector(data, {size}, owner);
 }
 
 // NOLINTNEXTLINE(misc-use-internal-linkage)

bindings/ir/operations/register_if_else_operation.cpp

@@ -66,7 +66,7 @@ Otherwise, the else operation is executed.
         new (self) qc::IfElseOperation(std::move(thenPtr), std::move(elsePtr),
                                        controlReg, expectedVal, kind);
       },
-      "then_operation"_a, nb::arg("else_operation").none(true),
+      "then_operation"_a, nb::arg("else_operation").none(),
       "control_register"_a, "expected_value"_a = 1U,
       "comparison_kind"_a = qc::ComparisonKind::Eq);
   ifElse.def(
@@ -81,7 +81,7 @@ Otherwise, the else operation is executed.
         new (self) qc::IfElseOperation(std::move(thenPtr), std::move(elsePtr),
                                        controlBit, expectedVal, kind);
       },
-      "then_operation"_a, nb::arg("else_operation").none(true), "control_bit"_a,
+      "then_operation"_a, nb::arg("else_operation").none(), "control_bit"_a,
       "expected_value"_a = true, "comparison_kind"_a = qc::ComparisonKind::Eq);
 
   ifElse.def_prop_ro("then_operation", &qc::IfElseOperation::getThenOp,

bindings/patterns.txt

@@ -135,7 +135,7 @@ mqt\.core\.mlir\.CompilerTarget\.from_device$:
         \doc
 
 mqt\.core\.mlir\.CompilerTarget\.from_device_id$:
-    \from mqt.core._compat.typing import Unpack
+    \from typing import Unpack
     \from mqt.core.typing import QDMISessionParameters
     @staticmethod
     def from_device_id(device_id: str, **session_parameters: Unpack[QDMISessionParameters]) -> CompilerTarget:

cmake/AddMQTPythonBinding.cmake

@@ -10,15 +10,22 @@ function(add_mqt_python_binding package_name target_name)
   cmake_parse_arguments(ARG "" "MODULE_NAME;INSTALL_DIR" "LINK_LIBS" ${ARGN})
   set(SOURCES ${ARG_UNPARSED_ARGUMENTS})
 
+  # nanobind 3.0 ignores scikit-build-core's abi3t signal on Windows. NB_ABI configures the nested
+  # nanobind_add_module call.
+  if(WIN32 AND Py_TARGET_ABI3T)
+    set(NB_ABI "${Python_VERSION_MAJOR}${Python_VERSION_MINOR}t")
+  endif()
+
   nanobind_add_module(
     # Name of the extension
     ${target_name}
-    # Target the stable ABI for Python 3.12+, which reduces the number of binary wheels
-    STABLE_ABI
     # Enable free-threaded support
     FREE_THREADED
     # Suppress compiler warnings from the nanobind library
     NB_SUPPRESS_WARNINGS
+    # Use nanobind's shared runtime. Split mode enables the Stable ABI internally.
+    BACKEND_MODULE
+    nanobind_backend
     # Source files
     ${SOURCES})
 
@@ -38,12 +45,29 @@ function(add_mqt_python_binding package_name target_name)
     set(module_name ${target_name})
   endif()
 
-  # A Python extension's only public native symbol is its module initializer. Keep symbols from
-  # statically linked dependencies local to avoid collisions with other extension modules.
+  # Keep statically linked dependencies local.
   if(APPLE)
     target_link_options(${target_name} PRIVATE "LINKER:-exported_symbol,_PyInit_${module_name}")
+
+    # Apple's x86-64 ABI requires unique RTTI. Its arm64 ABI compares non-unique RTTI names.
+    if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
+      target_link_options(
+        ${target_name}
+        PRIVATE
+        "LINKER:-exported_symbol,__ZTIN8nanobind4abi112python_errorE"
+        "LINKER:-exported_symbol,__ZTSN8nanobind4abi112python_errorE"
+        "LINKER:-exported_symbol,__ZTIN8nanobind4abi117builtin_exceptionE"
+        "LINKER:-exported_symbol,__ZTSN8nanobind4abi117builtin_exceptionE")
+    endif()
   elseif(UNIX)
     target_link_options(${target_name} PRIVATE "LINKER:--exclude-libs,ALL")
+
+    # nanobind 3.0 omits section garbage collection from split-mode targets.
+    target_link_options(
+      ${target_name}
+      PRIVATE
+      "$<$<OR:$<CONFIG:Release>,$<CONFIG:MinSizeRel>,$<CONFIG:RelWithDebInfo>>:LINKER:--gc-sections>"
+    )
   elseif(WIN32)
     set_target_properties(${target_name} PROPERTIES WINDOWS_EXPORT_ALL_SYMBOLS OFF)
   endif()

docs/conf.py

@@ -159,7 +159,6 @@ def format_url(self, _e: Entry) -> HRef:  # ruff:ignore[no-self-use]
 nitpick_ignore_regex = [
     ("py:class", r"Annotated\[numpy\.typing\.NDArray\[numpy\.complex128\], \{'shape': \(.*\)\}\]"),
     ("py:class", r"Ellipsis"),
-    ("py:class", r"mqt\.core\._compat\.typing\.Unpack"),
     ("py:class", r"ParametersType"),
     ("py:class", r"pennylane\.tape\.QuantumScriptOrBatch"),
     ("py:class", r"pennylane\.transforms\.core\.CompilePipeline"),

include/mqt-core/ir/Register.hpp

@@ -16,6 +16,7 @@
 
 #include "Definitions.hpp"
 
+#include <atomic>
 #include <cstddef>
 #include <functional>
 #include <stdexcept>
@@ -89,8 +90,9 @@ class QuantumRegister final : public Register<Qubit> {
 
 protected:
   static std::string generateName() {
-    static std::size_t counter = 0;
-    return "q" + std::to_string(counter++);
+    static std::atomic_size_t counter = 0;
+    return "q" +
+           std::to_string(counter.fetch_add(1, std::memory_order_relaxed));
   }
 };
 
@@ -106,8 +108,9 @@ class ClassicalRegister final : public Register<Bit> {
 
 protected:
   static std::string generateName() {
-    static std::size_t counter = 0;
-    return "c" + std::to_string(counter++);
+    static std::atomic_size_t counter = 0;
+    return "c" +
+           std::to_string(counter.fetch_add(1, std::memory_order_relaxed));
   }
 };
 

include/mqt-core/ir/operations/Expression.hpp

@@ -20,6 +20,7 @@
 #include <cstddef>
 #include <cstdint>
 #include <functional>
+#include <mutex>
 #include <numeric>
 #include <ostream>
 #include <stdexcept>
@@ -57,6 +58,7 @@ struct Variable {
   static inline std::unordered_map<std::string, std::size_t> registered{};
   static inline std::unordered_map<std::size_t, std::string> names{};
   static inline std::size_t nextId{};
+  static inline std::mutex registryMutex{};
   // NOLINTEND(cppcoreguidelines-avoid-non-const-global-variables)
 
   /**
@@ -69,7 +71,7 @@ struct Variable {
    * @brief Get the name of the variable.
    * @return Name of the variable.
    */
-  [[nodiscard]] std::string getName() const noexcept;
+  [[nodiscard]] std::string getName() const;
 
   /**
    * @brief Check whether this variable's id is equal to another variable's id.
@@ -113,7 +115,7 @@ struct Variable {
  * @brief Hash function for the Variable struct.
  */
 template <> struct std::hash<sym::Variable> {
-  std::size_t operator()(const sym::Variable& var) const noexcept {
+  std::size_t operator()(const sym::Variable& var) const {
     return std::hash<std::string>()(var.getName());
   }
 };

include/mqt-core/qdmi/driver/Driver.hpp

@@ -19,10 +19,12 @@
 #include <qdmi/client.h>
 #include <qdmi/device.h>
 
+#include <condition_variable>
 #include <cstddef>
 #include <cstdint>
 #include <filesystem>
 #include <memory>
+#include <mutex>
 #include <optional>
 #include <string>
 #include <string_view>
@@ -217,6 +219,8 @@ struct QDMI_Device_impl_d {
   QDMI_Device_Session deviceSession_ = nullptr;
   /// Client-facing wrappers for direct child devices.
   std::vector<std::unique_ptr<QDMI_Device_impl_d>> childDevices_;
+  /// Guards the owned job wrappers.
+  std::mutex jobsMutex_;
   /**
    * @brief Map of jobs to their corresponding unique pointers of
    * QDMI_Job_impl_d objects.
@@ -446,6 +450,15 @@ class Driver final : public Singleton<Driver> {
   /// @brief Private constructor to enforce the singleton pattern.
   Driver();
 
+  /// Guards all mutable driver state below.
+  mutable std::mutex stateMutex_;
+
+  /// Wakes callers waiting for a persistent device to finish opening.
+  std::condition_variable stateChanged_;
+
+  /// Ensures that the configured client catalog is materialized once.
+  std::once_flag clientCatalogOnce_;
+
   /**
    * @brief Vector of unique pointers to QDMI_Device_impl_d objects.
    */
@@ -463,12 +476,12 @@ class Driver final : public Singleton<Driver> {
   /// @brief Materialized devices exposed through the client API.
   std::vector<QDMI_Device> clientDevices_;
 
-  /// @brief Whether the configured client device catalog has been opened.
-  bool clientCatalogMaterialized_ = false;
-
   /// @brief Opened devices indexed by their stable registration ID.
   std::unordered_map<std::string, QDMI_Device> openedDevices_;
 
+  /// @brief Device IDs whose persistent sessions are being opened.
+  std::unordered_set<std::string> openingDeviceIds_;
+
   /**
    * @brief Map of sessions to their corresponding unique pointers to
    * QDMI_Session_impl_d objects.

noxfile.py

@@ -35,7 +35,7 @@
 if os.environ.get("CI", None):
     nox.options.error_on_missing_interpreters = True
 
-PYTHON_ALL_VERSIONS = ["3.10", "3.11", "3.12", "3.13", "3.14"]
+PYTHON_ALL_VERSIONS = ["3.11", "3.12", "3.13", "3.14"]
 
 
 @contextlib.contextmanager