✨ Add support for QDMI child devices to the driver and FoMaC libraries (backport #1897) (#1898)

## Description

This PR adds support for the newly introduced child device feature of
QDMI v1.3.2 to the MQT Core Driver and the FoMaC libraries.

Assisted-by: gpt-5.6-sol via Codex CLI

@ystade FYI

## 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 e78c99a)

---------

Co-authored-by: Lukas Burgholzer <burgholzer@me.com>

Author: mergify[bot]

CHANGELOG.md

@@ -12,11 +12,18 @@ releases may include breaking changes.
 
 ### Added
 
+- ✨ Add support for QDMI child devices to the driver and FoMaC libraries
+  ([#1897]) ([**@burgholzer**])
 - ✨ Add typed custom property and result queries to the C++ and Python FoMaC
   libraries ([#1895]) ([**@burgholzer**])
 - ✨ Add support for custom job parameters to C++ and Python FoMaC library
   ([#1887]) ([**@flowerthrower**], [**@burgholzer**])
 
+### Changed
+
+- ⬆️ Raise the minimum supported QDMI version to 1.3.2 ([#1897])
+  ([**@burgholzer**])
+
 ## [3.7.0] - 2026-07-09
 
 _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#370)._
@@ -572,6 +579,7 @@ changelogs._
 
 <!-- PR links -->
 
+[#1897]: https://github.com/munich-quantum-toolkit/core/pull/1897
 [#1895]: https://github.com/munich-quantum-toolkit/core/pull/1895
 [#1887]: https://github.com/munich-quantum-toolkit/core/pull/1887
 [#1873]: https://github.com/munich-quantum-toolkit/core/pull/1873

UPGRADING.md

@@ -6,6 +6,14 @@ of changes including minor and patch releases, please refer to the
 
 ## [Unreleased]
 
+### QDMI child devices
+
+The QDMI driver now translates device-library-specific `QDMI_Child_Device`
+handles into client-facing `QDMI_Device` handles backed by dedicated child
+sessions. Direct child devices can be queried through
+`fomac::Device::getChildDevices()` in C++ and `Device.child_devices()` in
+Python. Devices without child-device support continue to behave unchanged.
+
 ## [3.7.0]
 
 The shared library ABI version (`SOVERSION`) is increased from `3.6` to `3.7`.

bindings/fomac/fomac.cpp

@@ -359,6 +359,9 @@ when the custom slot is unsupported.)pb");
              &fomac::Device::getSupportedProgramFormats,
              "Returns the list of program formats supported by the device.");
 
+  device.def("child_devices", &fomac::Device::getChildDevices,
+             "Returns the direct child devices managed by this device.");
+
   device.def(
       "query_custom_property",
       [](const fomac::Device& self, const fomac::CustomProperty customProperty,

cmake/ExternalDependencies.cmake

@@ -75,7 +75,7 @@ if(BUILD_MQT_CORE_TESTS)
 endif()
 
 # cmake-format: off
-set(QDMI_MINIMUM_VERSION 1.3.0
+set(QDMI_MINIMUM_VERSION 1.3.2
         CACHE STRING "Minimum QDMI version")
 set(QDMI_VERSION 1.3.2
         CACHE STRING "QDMI version")

include/mqt-core/fomac/FoMaC.hpp

@@ -472,6 +472,14 @@ class Device {
   [[nodiscard]] std::vector<QDMI_Program_Format>
   getSupportedProgramFormats() const;
 
+  /**
+   * @brief Returns the direct child devices managed by this device.
+   * @return The child devices, or an empty vector if child devices are not
+   * supported.
+   * @see QDMI_DEVICE_PROPERTY_CHILDDEVICES
+   */
+  [[nodiscard]] std::vector<Device> getChildDevices() const;
+
   /**
    * @brief Queries an implementation-defined custom device property.
    * @tparam T Expected value type. Use `std::vector<std::byte>` to retrieve the

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

@@ -167,33 +167,48 @@ struct QDMI_Device_impl_d {
    * @note This must be a pointer type as we need access to dynamic and static
    * libraries that are subclasses of qdmi::DeviceLibrary.
    */
-  std::unique_ptr<qdmi::DeviceLibrary> library_;
+  std::shared_ptr<qdmi::DeviceLibrary> library_;
   /// @brief The device session handle.
   QDMI_Device_Session deviceSession_ = nullptr;
+  /// Client-facing wrappers for direct child devices.
+  std::vector<std::unique_ptr<QDMI_Device_impl_d>> childDevices_;
   /**
    * @brief Map of jobs to their corresponding unique pointers of
    * QDMI_Job_impl_d objects.
    */
   std::unordered_map<QDMI_Job, std::unique_ptr<QDMI_Job_impl_d>> jobs_;
 
 public:
+  /**
+   * @brief Constructs a top-level QDMI device from an exclusively owned
+   * library.
+   * @param lib is the device library to take ownership of.
+   * @param config is the configuration for device session parameters.
+   */
+  explicit QDMI_Device_impl_d(std::unique_ptr<qdmi::DeviceLibrary>&& lib,
+                              const qdmi::DeviceSessionConfig& config = {})
+      : QDMI_Device_impl_d(std::shared_ptr(std::move(lib)), config) {}
+
   /**
    * @brief Constructor for the QDMI device.
    * @details This constructor initializes the device session and allocates
    * the device session handle.
-   * @param lib is a unique pointer to the device library that provides the
+   * @param lib is a shared pointer to the device library that provides the
    * device interface functions.
    * @param config is the configuration for device session parameters.
+   * @param childDevice optionally selects a child device for this wrapper.
    */
-  explicit QDMI_Device_impl_d(std::unique_ptr<qdmi::DeviceLibrary>&& lib,
-                              const qdmi::DeviceSessionConfig& config = {});
+  explicit QDMI_Device_impl_d(std::shared_ptr<qdmi::DeviceLibrary> lib,
+                              const qdmi::DeviceSessionConfig& config = {},
+                              QDMI_Child_Device childDevice = nullptr);
 
   /**
    * @brief Destructor for the QDMI device.
    * @details This destructor frees the device session and clears the jobs map.
    */
   ~QDMI_Device_impl_d() {
     jobs_.clear();
+    childDevices_.clear();
     if (library_ && deviceSession_ != nullptr) {
       library_->device_session_free(deviceSession_);
     }

python/mqt/core/fomac.pyi

@@ -307,6 +307,9 @@ class Device:
     def supported_program_formats(self) -> list[ProgramFormat]:
         """Returns the list of program formats supported by the device."""
 
+    def child_devices(self) -> list[Device]:
+        """Returns the direct child devices managed by this device."""
+
     @overload
     def query_custom_property(self, custom_property: CustomProperty, value_type: type[str]) -> str | None: ...
     @overload

src/fomac/FoMaC.cpp

@@ -286,6 +286,34 @@ std::vector<QDMI_Program_Format> Device::getSupportedProgramFormats() const {
       QDMI_DEVICE_PROPERTY_SUPPORTEDPROGRAMFORMATS);
 }
 
+std::vector<Device> Device::getChildDevices() const {
+  size_t size = 0;
+  auto result = QDMI_device_query_device_property(
+      device_, QDMI_DEVICE_PROPERTY_CHILDDEVICES, 0, nullptr, &size);
+  if (result == QDMI_ERROR_NOTSUPPORTED) {
+    return {};
+  }
+  qdmi::throwIfError(result, "Querying child devices size");
+  if (size % sizeof(QDMI_Device) != 0) {
+    throw std::runtime_error("Invalid child device list size");
+  }
+
+  std::vector<QDMI_Device> handles(size / sizeof(QDMI_Device));
+  if (size != 0) {
+    result = QDMI_device_query_device_property(
+        device_, QDMI_DEVICE_PROPERTY_CHILDDEVICES, size,
+        static_cast<void*>(handles.data()), nullptr);
+    qdmi::throwIfError(result, "Querying child devices");
+  }
+
+  std::vector<Device> devices;
+  devices.reserve(handles.size());
+  std::ranges::transform(
+      handles, std::back_inserter(devices),
+      [](QDMI_Device_impl_d* const handle) { return Device(handle); });
+  return devices;
+}
+
 Job Device::submitJob(const std::string& program,
                       const QDMI_Program_Format format, const size_t numShots,
                       const std::optional<CustomJobParameter>& custom1,
@@ -751,7 +779,7 @@ std::vector<Device> Session::getDevices() {
   devices.reserve(qdmiDevices.size());
   std::ranges::transform(
       qdmiDevices, std::back_inserter(devices),
-      [](const QDMI_Device& dev) -> Device { return Device(dev); });
+      [](QDMI_Device_impl_d* const& dev) -> Device { return Device(dev); });
   return devices;
 }
 } // namespace fomac

src/qdmi/driver/Driver.cpp

@@ -16,6 +16,7 @@
 #include <qdmi/device.h>
 #include <spdlog/spdlog.h>
 
+#include <algorithm>
 #include <array>
 #include <cassert>
 #include <cstddef>
@@ -169,8 +170,9 @@ DynamicDeviceLibrary::~DynamicDeviceLibrary() {
 } // namespace qdmi
 
 QDMI_Device_impl_d::QDMI_Device_impl_d(
-    std::unique_ptr<qdmi::DeviceLibrary>&& lib,
-    const qdmi::DeviceSessionConfig& config)
+    std::shared_ptr<qdmi::DeviceLibrary> lib,
+    const qdmi::DeviceSessionConfig& config,
+    QDMI_Child_Device_impl_d* const childDevice)
     : library_(std::move(lib)) {
   if (library_->device_session_alloc(&deviceSession_) != QDMI_SUCCESS) {
     throw std::runtime_error("Failed to allocate device session");
@@ -213,10 +215,77 @@ QDMI_Device_impl_d::QDMI_Device_impl_d(
   setParameter(config.custom4, QDMI_DEVICE_SESSION_PARAMETER_CUSTOM4);
   setParameter(config.custom5, QDMI_DEVICE_SESSION_PARAMETER_CUSTOM5);
 
+  if (childDevice != nullptr) {
+    const auto status =
+        static_cast<QDMI_STATUS>(library_->device_session_set_parameter(
+            deviceSession_, QDMI_DEVICE_SESSION_PARAMETER_CHILDDEVICE,
+            sizeof(QDMI_Child_Device), static_cast<const void*>(&childDevice)));
+    if (status != QDMI_SUCCESS) {
+      library_->device_session_free(deviceSession_);
+      deviceSession_ = nullptr;
+      std::ostringstream ss;
+      ss << "Failed to select child device: " << qdmi::toString(status);
+      throw std::runtime_error(ss.str());
+    }
+  }
+
   if (library_->device_session_init(deviceSession_) != QDMI_SUCCESS) {
     library_->device_session_free(deviceSession_);
+    deviceSession_ = nullptr;
     throw std::runtime_error("Failed to initialize device session");
   }
+
+  // Child sessions represent leaf devices in the QDMI multicore
+  // workflow. Only top-level sessions discover and wrap child handles.
+  if (childDevice != nullptr) {
+    return;
+  }
+
+  size_t childrenSize = 0;
+  auto status =
+      static_cast<QDMI_STATUS>(library_->device_session_query_device_property(
+          deviceSession_, QDMI_DEVICE_PROPERTY_CHILDDEVICES, 0, nullptr,
+          &childrenSize));
+  if (status == QDMI_ERROR_NOTSUPPORTED) {
+    return;
+  }
+  if (status != QDMI_SUCCESS || childrenSize % sizeof(QDMI_Child_Device) != 0) {
+    library_->device_session_free(deviceSession_);
+    deviceSession_ = nullptr;
+    if (status != QDMI_SUCCESS) {
+      throw std::runtime_error("Failed to query child devices: " +
+                               std::string(qdmi::toString(status)));
+    }
+    throw std::runtime_error("Device returned an invalid child device list");
+  }
+
+  std::vector<QDMI_Child_Device> children(childrenSize /
+                                          sizeof(QDMI_Child_Device));
+  if (childrenSize != 0) {
+    status =
+        static_cast<QDMI_STATUS>(library_->device_session_query_device_property(
+            deviceSession_, QDMI_DEVICE_PROPERTY_CHILDDEVICES, childrenSize,
+            static_cast<void*>(children.data()), nullptr));
+    if (status != QDMI_SUCCESS) {
+      library_->device_session_free(deviceSession_);
+      deviceSession_ = nullptr;
+      throw std::runtime_error("Failed to query child devices: " +
+                               std::string(qdmi::toString(status)));
+    }
+  }
+
+  try {
+    childDevices_.reserve(children.size());
+    for (auto* const child : children) {
+      childDevices_.emplace_back(
+          std::make_unique<QDMI_Device_impl_d>(library_, config, child));
+    }
+  } catch (...) {
+    childDevices_.clear();
+    library_->device_session_free(deviceSession_);
+    deviceSession_ = nullptr;
+    throw;
+  }
 }
 
 auto QDMI_Device_impl_d::createJob(QDMI_Job* job) -> int {
@@ -244,6 +313,25 @@ auto QDMI_Device_impl_d::freeJob(QDMI_Job job) -> void {
 auto QDMI_Device_impl_d::queryDeviceProperty(QDMI_Device_Property prop,
                                              const size_t size, void* value,
                                              size_t* sizeRet) const -> int {
+  if (prop == QDMI_DEVICE_PROPERTY_CHILDDEVICES) {
+    if (childDevices_.empty()) {
+      return QDMI_ERROR_NOTSUPPORTED;
+    }
+    const auto requiredSize = childDevices_.size() * sizeof(QDMI_Device);
+    if (value != nullptr) {
+      if (size < requiredSize) {
+        return QDMI_ERROR_INVALIDARGUMENT;
+      }
+      auto* devices = static_cast<QDMI_Device*>(value);
+      std::ranges::transform(
+          childDevices_, devices,
+          [](const auto& child) -> QDMI_Device { return child.get(); });
+    }
+    if (sizeRet != nullptr) {
+      *sizeRet = requiredSize;
+    }
+    return QDMI_SUCCESS;
+  }
   return library_->device_session_query_device_property(deviceSession_, prop,
                                                         size, value, sizeRet);
 }
@@ -424,7 +512,7 @@ auto Driver::addDynamicDeviceLibrary(const std::string& libName,
                                      const DeviceSessionConfig& config)
     -> QDMI_Device {
   devices_.emplace_back(std::make_unique<QDMI_Device_impl_d>(
-      std::make_unique<DynamicDeviceLibrary>(libName, prefix), config));
+      std::make_shared<DynamicDeviceLibrary>(libName, prefix), config));
   return devices_.back().get();
 }
 

test/fomac/test_fomac.cpp

@@ -440,6 +440,10 @@ TEST_P(DeviceTest, SupportedProgramFormats) {
   EXPECT_NO_THROW(std::ignore = device.getSupportedProgramFormats());
 }
 
+TEST_P(DeviceTest, ChildDevices) {
+  EXPECT_TRUE(device.getChildDevices().empty());
+}
+
 TEST_P(DeviceTest, UnsupportedCustomPropertyReturnsNullopt) {
   EXPECT_EQ(device.queryCustomProperty<std::vector<std::byte>>(
                 CustomProperty::Custom1),