♻️ Load a replaceable QDMI Client driver by burgholzer · Pull Request #2229 · munich-quantum-toolkit/core

burgholzer · 2026-08-24T16:33:16Z

🤖 AI text below 🤖

Description

Load one replaceable implementation of the standard QDMI 1.4 Client ABI instead of linking Core's C++ wrappers directly to the packaged Driver.

This pull request:

pins ✨ Add replaceable Client drivers and stable device IDs Munich-Quantum-Software-Stack/QDMI#511 at dcb57425fe650867344e5989eecc77d42231c3a4;
validates the complete Client ABI before allocating a session;
publishes one process-wide Driver selection only after successful allocation;
keeps the selected library and session-owned descendant handles alive;
opens devices through stable Client IDs and forwards generic authentication unchanged;
separates shared MQT::CoreQDMI from shared MQT::CoreQDMIDriver;
migrates the C++, Python, MLIR, Qiskit, PennyLane, and Slurm consumers; and
adds fake third-party and packaged-runtime regressions.

The packaged Driver remains the default when no explicit path or MQT_CORE_QDMI_DRIVER value is set. QDMI metadata cleanup #2233 is the next stack layer. The private packaged-Driver extension remains in the later #2230 layer, and installed/imported-consumer deployment hardening remains in the final #2231 layer.

This PR is stacked directly on #2162.

Validation on the exact final replay:

full release build: passed;
compiler tests: 152/152 passed;
isolated Client-ABI compiler tests: 3/3 passed;
Core QDMI tests: 230/230 passed;
Client and packaged runtime tests: 1/1 passed each;
Driver tests: 96/96 passed;
registry tests: 15/15 passed;
DDSIM tests: 53/53 passed;
SC tests: 44/44 passed, with one expected job-ID skip;
stub generation and full repository lint: passed; and
signed commit verification and diff checks: passed.

AI assistance: OpenAI Codex assisted with implementation, review, testing, and this description.

Checklist

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

If PR contains AI-assisted content:

Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
I have disclosed AI assistance in the PR description.
I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

codecov · 2026-08-24T17:56:49Z

Codecov Report

❌ Patch coverage is 93.33333% with 26 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/qdmi/Client.cpp	93.2%	17 Missing ⚠️
src/qdmi/driver/Driver.cpp	73.3%	8 Missing ⚠️
mlir/lib/Compiler/QDMIAdapter.cpp	87.5%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

burgholzer

Alright. I have quite a few ideas here for how to make this better and improve the overall wording. I really like how this is shaping up though. I did not think that replaceable drivers would feel so natural. Let's see how much of the custom driver extension will actually remain in the end.

burgholzer · 2026-08-25T13:05:24Z

This feels right, but it also feels fairly complex. Are we sure all of this is really needed to properly distribute this? Keep later PRs in the stack in mind for this.

burgholzer · 2026-08-25T14:24:25Z

    std::same_as<T, std::vector<std::byte>>;

 namespace detail {
+struct ClientApi {


Likely ClientAPI would be better suited here. There may be other places benefitting from the improved spelling.

burgholzer · 2026-08-25T14:25:33Z

This should very closely follow the implementation in the driver so that this has a common look and feel that does not diverge too much. Aligning the two should be a priority here.

burgholzer · 2026-08-25T14:26:47Z

-   * @param id Stable registered device ID.
-   * @param overrides Session values that replace registered defaults.
-   * @return An owning device wrapper for the new session.
+   * @brief Opens a Client-visible QDMI device in a fresh session.


Suggested change

* @brief Opens a Client-visible QDMI device in a fresh session.

* @brief Opens a client-visible QDMI device in a fresh session.

Worth establishing consistently

burgholzer · 2026-08-25T14:29:56Z

+  ClientSession(const ClientSession&) = delete;
+  ClientSession& operator=(const ClientSession&) = delete;


should this define (defaulted) move constructors and assignment?

burgholzer · 2026-08-26T06:46:39Z

Given how the new code here shares quite a bit of code with the loading logic in the driver, does it make sense to introduce a shared support library (could be header-only) that centralizes a bit of the code and avoids duplication?
I'd only do this if it genuinely saves code.

burgholzer · 2026-08-26T06:47:32Z

+       {directory / filename, directory / "lib" / filename,
+        directory / "bin" / filename,
+        directory.parent_path() / "lib" / filename,
+        directory.parent_path() / "bin" / filename}) {


Should this also cover lib64. IIRC we had problems with that already at some point on manylinux images.

burgholzer · 2026-08-26T06:48:51Z

+    -> LoadedClient {
+  auto* const library = openLibrary(path);
+  if (library == nullptr) {
+    throw std::runtime_error("Cannot load QDMI Client driver '" +


just to annotate this once more: We shouldn't use "QDMI Client driver" but simply "QDMI driver".

burgholzer · 2026-08-26T06:53:49Z

+                           const SessionConfig& config) {
+  if (id.empty() || id.find('\0') != std::string_view::npos) {
+    throw std::invalid_argument(
+        "QDMI device ID must not be empty or contain null bytes");
+  }
+  Session session(config);
+  auto devices = session.getDevices();
+  std::string available;
+  for (const auto& device : devices) {
+    const auto candidateId = device.getId();
+    if (candidateId == id) {
+      return device;
+    }
+    if (!available.empty()) {
+      available += ", ";
+    }
+    available += candidateId;
+  }
+  throw std::out_of_range("QDMI Client session has no device with ID '" +
+                          std::string(id) + "'; available IDs: " + available);


This feels like something that should be improved in the QDMI client interface upstream so that code like this becomes way simpler (and closer to what the custom driver extension actually offered before).

burgholzer · 2026-08-26T06:55:22Z

I get where most of the changes are coming from here and it is quite natural that there are substantial additions given the replaceable driver. However, some of the code, especially around lifetime handling feels more complicated than it necessarily needs to be in my opinion. Maybe some opportunities for simplification arise out of the consequences of the other review comments.

Route Core through one validated standard QDMI 1.4 Client ABI while keeping the packaged Driver as a separate shared library. Select devices by stable Client IDs, retain session-owned handles, support generic authentication and UTF-8 loader paths, and update in-tree consumers and runtime tests. Assisted-by: GPT-5.6 Sol via Codex

Move feature-group coverage to an isolated compiler test that uses the standard fake Client. This preserves public-boundary coverage without linking the Core QDMI target back to private Driver code. Delay Windows discovery for QDMI tests until runtime dependencies have been staged. Assisted-by: GPT-5.6 Sol via Codex

Reject successful or warning allocations that return a null handle before printing a warning or fixing process selection. Cover both the first-selection and selected-driver paths with the standard fake Client. Assisted-by: GPT-5.6 Sol via Codex

Retain semantic rejection and device-ID checks without pinning platform-specific lower-layer diagnostics. Assisted-by: GPT-5.6 Sol via Codex

burgholzer added dependencies Pull requests that update a dependency file feature New feature or request c++ Anything related to C++ code python Anything related to Python code packaging Anything related to Python packaging QDMI Anything related to QDMI labels Aug 24, 2026

burgholzer self-assigned this Aug 24, 2026

burgholzer added dependencies Pull requests that update a dependency file feature New feature or request c++ Anything related to C++ code python Anything related to Python code packaging Anything related to Python packaging QDMI Anything related to QDMI labels Aug 24, 2026

burgholzer force-pushed the codex/qdmi-client-runtime-c1 branch 2 times, most recently from 010d76c to 295a166 Compare August 24, 2026 16:50

mergify Bot added the conflict label Aug 24, 2026

burgholzer force-pushed the codex/qdmi-client-runtime-c1 branch from 295a166 to 785c041 Compare August 24, 2026 18:13

mergify Bot removed the conflict label Aug 24, 2026

burgholzer force-pushed the codex/qdmi-client-runtime-c1 branch from 785c041 to 7eb542d Compare August 24, 2026 18:59

burgholzer force-pushed the codex/qdmi-client-runtime-c1 branch 2 times, most recently from 2aa8996 to cfc4815 Compare August 24, 2026 19:06

burgholzer mentioned this pull request Aug 24, 2026

✨ Add an optional packaged QDMI Driver extension #2230

Draft

12 tasks

burgholzer force-pushed the codex/qdmi-client-runtime-c1 branch from cfc4815 to 3de68c6 Compare August 24, 2026 20:10

burgholzer mentioned this pull request Aug 24, 2026

💥 Remove obsolete QDMI calibration and pulse metadata #2233

Draft

12 tasks

burgholzer force-pushed the codex/qdmi-client-runtime-c1 branch from 3de68c6 to 32bb143 Compare August 24, 2026 23:47

burgholzer added this to the QDMI Support milestone Aug 25, 2026

burgholzer commented Aug 26, 2026

View reviewed changes

mergify Bot added the conflict label Aug 26, 2026

burgholzer mentioned this pull request Aug 27, 2026

♻️ Redesign QDMI device management #1901

Closed

burgholzer added 4 commits August 27, 2026 13:56

🐛 Reject null QDMI Client sessions

fc6c71e

Reject successful or warning allocations that return a null handle before printing a warning or fixing process selection. Cover both the first-selection and selected-driver paths with the standard fake Client. Assisted-by: GPT-5.6 Sol via Codex

✅ Test QDMI adapter rejection contracts

7504600

Retain semantic rejection and device-ID checks without pinning platform-specific lower-layer diagnostics. Assisted-by: GPT-5.6 Sol via Codex

burgholzer force-pushed the codex/qdmi-client-runtime-c1 branch from 32bb143 to 7504600 Compare August 27, 2026 14:03

burgholzer removed the conflict label Aug 27, 2026

mergify Bot added conflict and removed conflict labels Aug 27, 2026

Navigation Menu

Uh oh!

Uh oh!

♻️ Load a replaceable QDMI Client driver - #2229

♻️ Load a replaceable QDMI Client driver#2229
burgholzer wants to merge 4 commits into
codex/classical-control-supportfrom
codex/qdmi-client-runtime-c1

burgholzer commented Aug 24, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Aug 24, 2026 •

edited

Loading

Uh oh!

burgholzer left a comment

Uh oh!

burgholzer Aug 25, 2026

Uh oh!

burgholzer Aug 25, 2026

Uh oh!

burgholzer Aug 25, 2026

Uh oh!

burgholzer Aug 25, 2026

Uh oh!

burgholzer Aug 25, 2026

Uh oh!

burgholzer Aug 26, 2026

Uh oh!

burgholzer Aug 26, 2026

Uh oh!

burgholzer Aug 26, 2026

Uh oh!

burgholzer Aug 26, 2026

Uh oh!

burgholzer Aug 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	* @brief Opens a Client-visible QDMI device in a fresh session.
	* @brief Opens a client-visible QDMI device in a fresh session.

		ClientSession(const ClientSession&) = delete;
		ClientSession& operator=(const ClientSession&) = delete;

Uh oh!

Uh oh!

Conversation

burgholzer commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

codecov Bot commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

burgholzer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

burgholzer commented Aug 24, 2026 •

edited

Loading

codecov Bot commented Aug 24, 2026 •

edited

Loading