🚸 Improve QDMI Integration (backport #1694) (#1698)

## Description

This PR originally only aimed to address #1352.
However, working on it prompted several follow-ups and improvements for
the QDMI support layer as well as a couple of bugfixes.

The main change here is still that all QDMI devices are now built as
shared libraries by default and that the respective dynamic wrappers
have been removed.
The QDMI Qiskit wrapper now supports multi-controlled gates as exposed
by the DDSIM device.
The QDMI Python tests have been significantly streamlined, and a lot of
the mocking code is replaced with actual device executions.

I will leave this in draft until CI is green because I expect Windows to
cause some problems.
Edit: As expected, Windows is acting up big again.
Edit2: I think I have a working version now. Only took 10h 🫠 

Fixes #1352 

## Checklist



- [x] The pull request only contains commits that are focused and
relevant to this change.
- [x] I have added appropriate tests that cover the new/changed
functionality.
- [x] I have updated the documentation to reflect these changes.
- [x] I have added entries to the changelog for any noteworthy
additions, changes, fixes, or removals.
- [x] I have added migration instructions to the upgrade guide (if
needed).
- [x] The changes follow the project's style guidelines and introduce no
new warnings.
- [x] The changes are fully tested and pass the CI checks.
- [x] I have reviewed my own code changes.

**If PR contains AI-assisted content:**

- [x] I have disclosed the use of AI tools in the PR description as per
our [AI Usage
Guidelines](https://github.com/munich-quantum-toolkit/core/blob/main/docs/ai_usage.md).
- [x] AI-assisted commits include an `Assisted-by: [Model Name] via
[Tool Name]` footer.
- [x] I confirm that I have personally reviewed and understood all
AI-generated content, and accept full responsibility for it.



(cherry picked from commit 4fe097c)

---------

Co-authored-by: Lukas Burgholzer <burgholzer@me.com>
Co-authored-by: Daniel Haag <121057143+denialhaag@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -9,8 +9,28 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ## [Unreleased]
 
+### Added
+
+- 🚸 Add a measurement instruction to the default SC QDMI device ([#1694]) ([**@burgholzer**])
+- ✨ Add support for multi-controlled gates to the QDMI Qiskit backend converter ([#1694]) ([**@burgholzer**])
+
+### Changed
+
+- ♻️ Build all built-in QDMI devices as shared libraries ([#1694]) ([**@burgholzer**])
+- ⬆️ Update minimum supported Qiskit version to 1.1.0 ([#1694]) ([**@burgholzer**])
+
+### Fixed
+
+- 🐛 Fix segfault in DD `sample` method when idle classical bits are present ([#1694]) ([**@burgholzer**])
+
+### Removed
+
+- 🔥 Remove shared library wrappers for QDMI devices ([#1694]) ([**@burgholzer**])
+
 ## [3.5.1] - 2026-04-23
 
+_If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#351)._
+
 ### Fixed
 
 - 🐛 Fix malformed include directories in exported `nlohmann_json` CMake targets for component-based installs ([#1662]) ([**@burgholzer**])
@@ -21,7 +41,7 @@ _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#350)._
 
 ### Added
 
-- ✨ Add support for multi-controlled gates to ZX package ([#1380]) ([**@keefehuang**])
+- ✨ Add support for multi-controlled gates to ZX package ([#1380]) ([**@keefehuang**], [**@denialhaag**])
 - ✨ Add Sampler and Estimator primitives to the QDMI-Qiskit interface ([#1507]) ([**@marcelwa**])
 
 ### Changed
@@ -342,6 +362,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 
 <!-- PR links -->
 
+[#1694]: https://github.com/munich-quantum-toolkit/core/pull/1694
 [#1662]: https://github.com/munich-quantum-toolkit/core/pull/1662
 [#1654]: https://github.com/munich-quantum-toolkit/core/pull/1654
 [#1652]: https://github.com/munich-quantum-toolkit/core/pull/1652

UPGRADING.md

@@ -4,14 +4,33 @@ This document describes breaking changes and how to upgrade. For a complete list
 
 ## [Unreleased]
 
+### Changes to builtin QDMI devices
+
+The builtin QDMI devices (with prefixes `MQT_SC`, `MQT_NA`, and `MQT_DDSIM`) are now all built as shared libraries by default.
+In turn, the shared library wrappers (with prefixes `MQT_SC_DYN` and `MQT_NA_DYN`) have been removed entirely.
+MQT Core's QDMI driver will automatically load the shared libraries of the builtin devices if they are available in the library search path.
+If you were previously using the statically builtin devices, no changes should be necessary as the shared libraries are now the default.
+If you were previously using the shared library wrappers, you should switch to using the builtin devices instead, which are now shared libraries by default.
+
+### Broader operation support in QDMI Qiskit converter
+
+The QDMI Qiskit converter now supports a broader range of operations, including multi-controlled gates such as `mcx`, `mcz`, `mcrx`, and more.
+As a consequence, these operations can now be directly used without requiring decomposition, for example, with the builtin `DDSIM` QDMI device.
+
+### Minimum supported Qiskit version
+
+From this release onwards, MQT Core requires Qiskit version 1.1.0 or higher.
+This is due to the fact that we are relying on some fixes to Qiskit primitives that were introduced in that version.
+If you are using MQT Core with Qiskit, please ensure that you have updated to Qiskit 1.1.0 or higher to avoid any compatibility issues.
+
 ## [3.5.1]
 
 No breaking changes.
 
 ### Component-based CMake installs
 
 Fixed exported `nlohmann_json` CMake metadata so `find_package(mqt-core CONFIG)` no longer propagates an invalid `.../COMPONENT` include directory in component-based installations.
-Anyone relying on an installed version of `mqt-core` shall update from `3.5.0` to `3.5.1`.
+Anyone relying on an installed version of `mqt-core` should update from 3.5.0 to 3.5.1.
 
 ## [3.5.0]
 

cmake/AddMQTCoreLibrary.cmake

@@ -21,12 +21,14 @@ function(kebab_to_camel output input)
 endfunction()
 
 function(add_mqt_core_library name)
-  cmake_parse_arguments(ARG "" "ALIAS_NAME" "" ${ARGN})
-  if(BUILD_MQT_CORE_SHARED_LIBS)
+  cmake_parse_arguments(ARG "FORCE_SHARED;HIDDEN_VISIBILITY" "ALIAS_NAME" "" ${ARGN})
+
+  if(ARG_FORCE_SHARED OR BUILD_MQT_CORE_SHARED_LIBS)
     add_library(${name} SHARED ${ARG_UNPARSED_ARGUMENTS})
   else()
     add_library(${name} ${ARG_UNPARSED_ARGUMENTS})
   endif()
+
   if(NOT ARG_ALIAS_NAME)
     # remove prefix 'mqt-' from target name if exists
     string(REGEX REPLACE "^${MQT_CORE_TARGET_NAME}" "" ALIAS_NAME_ARG ${name})
@@ -41,6 +43,14 @@ function(add_mqt_core_library name)
   # Add link libraries for warnings and options
   target_link_libraries(${name} PRIVATE MQT::ProjectWarnings MQT::ProjectOptions)
 
+  if(ARG_HIDDEN_VISIBILITY)
+    set_target_properties(
+      ${name}
+      PROPERTIES C_VISIBILITY_PRESET hidden
+                 CXX_VISIBILITY_PRESET hidden
+                 VISIBILITY_INLINES_HIDDEN 1)
+  endif()
+
   # Set versioning information
   set_target_properties(
     ${name}

cmake/PackageAddTest.cmake

@@ -11,6 +11,8 @@ macro(PACKAGE_ADD_TEST testname linklibs)
   if(NOT TARGET ${testname})
     # create an executable in which the tests will be stored
     add_executable(${testname} ${ARGN})
+    # Ensure test executables remain runnable from the build tree during GoogleTest discovery
+    set_property(TARGET ${testname} PROPERTY BUILD_WITH_INSTALL_RPATH FALSE)
     # link the Google test infrastructure and a default main function to the test executable.
     target_link_libraries(${testname} PRIVATE ${linklibs} GTest::gmock GTest::gtest_main
                                               MQT::ProjectOptions MQT::ProjectWarnings)
@@ -30,6 +32,8 @@ macro(PACKAGE_ADD_TEST_WITH_WORKING_DIR testname linklibs test_working_directory
   if(NOT TARGET ${testname})
     # create an executable in which the tests will be stored
     add_executable(${testname} ${ARGN})
+    # Ensure test executables remain runnable from the build tree during GoogleTest discovery
+    set_property(TARGET ${testname} PROPERTY BUILD_WITH_INSTALL_RPATH FALSE)
     # link the Google test infrastructure and a default main function to the test executable.
     target_link_libraries(${testname} PRIVATE ${linklibs} GTest::gmock GTest::gtest_main
                                               MQT::ProjectOptions MQT::ProjectWarnings)

docs/qdmi/driver.md

@@ -10,9 +10,9 @@ mystnb:
 
 ## Objective
 
-A QDMI Driver manages the communication between QDMI devices, such as [MQT Core's NA QDMI Device](na_device.md), and QDMI clients, see the [QDMI specification](https://munich-quantum-software-stack.github.io/QDMI/).
+A QDMI Driver manages the communication between QDMI devices, such as [MQT Core's NA QDMI Device](na_device.md) or [MQT Core's DDSIM QDMI Device](ddsim_device.md), and QDMI clients, see the [QDMI specification](https://munich-quantum-software-stack.github.io/QDMI/).
 It is responsible for loading the device, forwarding requests from the client to the device, and sending back the results.
-The MQT Core's QDMI Driver, {cpp:class}`qdmi::Driver`, comes with the [MQT Core's NA QDMI Device](na_device.md) that is already statically linked into the driver and can directly be used.
+MQT Core's QDMI Driver, {cpp:class}`qdmi::Driver`, comes with several preloaded devices that can be used directly.
 Other devices can be loaded dynamically at runtime via {cpp:func}`qdmi::Driver::addDynamicDeviceLibrary`.
 
 ## Python Bindings
@@ -38,4 +38,5 @@ available_devices = session.get_devices()
 # Print the name of every device
 for device in available_devices:
     print(device.name())
+
 ```

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

@@ -146,22 +146,6 @@ class DynamicDeviceLibrary final : public DeviceLibrary {
   ~DynamicDeviceLibrary() override;
 };
 
-// Macro to define a static library class that inherits from DeviceLibrary.
-// It binds all device library functions to the functions of the static library.
-// @param prefix is the prefix used for the function names in the library.
-#define DECLARE_STATIC_LIBRARY(prefix)                                         \
-  class prefix##DeviceLibrary final : public DeviceLibrary {                   \
-  public:                                                                      \
-    prefix##DeviceLibrary();                                                   \
-                                                                               \
-    ~prefix##DeviceLibrary() override;                                         \
-  };
-
-// Call the above macro for all static libraries that we want to support.
-DECLARE_STATIC_LIBRARY(MQT_NA)
-DECLARE_STATIC_LIBRARY(MQT_DDSIM)
-DECLARE_STATIC_LIBRARY(MQT_SC)
-
 /**
  * @brief The status of a session.
  * @details This enum defines the possible states of a session in the QDMI
@@ -178,9 +162,6 @@ enum class SessionStatus : uint8_t {
  */
 struct QDMI_Device_impl_d {
 private:
-  // Since we treat this struct as a class, we apply also the naming scheme for
-  // classes, i.e., an underscore at the end of member names.
-
   /**
    * @brief The device library that provides the device interface functions.
    * @note This must be a pointer type as we need access to dynamic and static
@@ -265,9 +246,6 @@ struct QDMI_Device_impl_d {
  */
 struct QDMI_Job_impl_d {
 private:
-  // Since we treat this struct as a class, we apply also the naming scheme for
-  // classes, i.e., an underscore at the end of member names.
-
   /// @brief The device job handle.
   QDMI_Device_Job deviceJob_ = nullptr;
   /// @brief The device associated with the job.
@@ -350,8 +328,6 @@ struct QDMI_Job_impl_d {
 /**
  * @brief Definition of the QDMI Session.
  */
-// Since we treat this struct as a class, we apply also the naming scheme for
-// classes, i.e., an underscore at the end of member names.
 struct QDMI_Session_impl_d {
 private:
   /// @brief The status of the session.

json/sc/device.json

@@ -185,6 +185,7 @@
   ],
   "operations": [
     { "name": "r", "numParameters": 2, "numQubits": 1 },
-    { "name": "cz", "numParameters": 0, "numQubits": 2 }
+    { "name": "cz", "numParameters": 0, "numQubits": 2 },
+    { "name": "measure", "numParameters": 0, "numQubits": 1 }
   ]
 }

pyproject.toml

@@ -49,7 +49,7 @@ dynamic = ["version"]
 
 [project.optional-dependencies]
 qiskit = [
-  "qiskit[qasm3-import]>=1.0.0",
+  "qiskit[qasm3-import]>=1.1.0",
 ]
 
 [project.scripts]
@@ -98,9 +98,7 @@ build.targets = [
   "mqt-core-na-bindings",
   "mqt-core-qdmi-ddsim-device",
   "mqt-core-qdmi-na-device",
-  "mqt-core-qdmi-na-device-dyn",
   "mqt-core-qdmi-sc-device",
-  "mqt-core-qdmi-sc-device-dyn",
 ]
 
 install.components = [
@@ -343,7 +341,7 @@ docs = [
   "sphinxcontrib-bibtex>=2.6.5",
   "sphinxcontrib-svg2pdfconverter>=1.3.0",
   "sphinxext-opengraph>=0.13.0",
-  "qiskit[qasm3-import,visualization]>=1.0.0",
+  "qiskit[qasm3-import,visualization]>=1.1.0",
   "openqasm-pygments>=0.2.0",
   "breathe>=4.36.0",
   "graphviz>=0.21.0",
@@ -357,7 +355,7 @@ test = [
   "pytest-cov>=7.0.0",
   "pytest-sugar>=1.1.1",
   "pytest-xdist>=3.8.0",
-  "qiskit[qasm3-import]>=1.0.0",
+  "qiskit[qasm3-import]>=1.1.0",
   "numpy>=2.1; python_version >= '3.13'",
   "numpy>=2.3.2; python_version >= '3.14'",
 ]
@@ -366,5 +364,5 @@ dev = [
   {include-group = "test"},
   "lit>=18.1.8",
   "nox>=2025.11.12",
-  "ty==0.0.29",
+  "ty==0.0.34",
 ]