✨ Add an optional packaged QDMI Driver extension by burgholzer · Pull Request #2230 · munich-quantum-toolkit/core

burgholzer · 2026-08-24T19:09:36Z

🤖 AI text below 🤖

Description

Add an optional private extension to MQT Core's packaged QDMI Driver without extending the standard QDMI Client ABI.

This pull request:

discovers installed device manifests from wheel RECORD metadata without importing provider packages;
anchors manifest paths to their declared distribution and rejects ambiguous or unsafe metadata;
stages registry changes transactionally and freezes staging after successful Driver construction;
opens one exact device by stable Client ID with strict session configuration and provider-status propagation;
exposes the packaged extension through C++ and Python default_driver APIs; and
keeps generic Client loading and installed-consumer deployment in their separate stack layers.

Dependencies

This PR is stacked directly on #2233. That PR pins QDMI #513, stacked on QDMI #512 and #511.

Validation

focused native tests: 117/117 passed;
focused Python tests: 12/12 passed;
non-unity Clang 22 build and changed-file clang-tidy: passed;
stub generation: passed;
full repository lint: passed;
exact QDMI source and build cache: verified at d6ce0da02cba1a3b903f0b046ef23af6f00edc6a;
signed commit verification and diff checks: passed.

The preceding runtime-equivalent head passed Windows x64, Windows ARM, Windows Python, Slurm, C++ coverage, and all Codecov patch gates. Hosted CI is pending for the final lint-only amendment.

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-24T19:51:40Z

Codecov Report

❌ Patch coverage is 90.90909% with 34 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/qdmi/driver/Driver.cpp	87.0%	19 Missing ⚠️
src/qdmi/driver/DeviceRegistry.cpp	90.6%	12 Missing ⚠️
src/qdmi/Client.cpp	96.9%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

burgholzer

This one also triggered quite a couple of general comments that also apply down the stack and should be considered in the next iteration.

burgholzer · 2026-08-26T08:39:18Z

+freezes its registry. Staging the packaged library does not select it as the
+generic Client driver. The first successful raw standard or targeted session
+allocation selects a Client driver. A later targeted-session initialization or
+device query failure does not undo that selection.


I believe that some of this will (have to) change based on the review in the PR this is stacked on.

burgholzer · 2026-08-26T08:40:23Z

The wording here and throughout will have to be adapted based on the feedback on nomenclature in the lower PRs.

burgholzer · 2026-08-26T08:45:46Z

 class Device;
 class Operation;

+namespace default_driver {


Is "default_driver" really what we want to use in terms of nomenclature?
Maybe "builtin_driver" would already be better.
Outside of MQT Core, I'd generally like to refer to it as the MQT Core QDMI Driver. I am not sure how well this flows internally in the project.
Maybe the driver we have could be framed as the QDMI Driver, while the framework also offers support for third-party drivers.
This already affects a lower PR in the stack and should correspondingly be updated there already.

burgholzer · 2026-08-26T08:53:34Z

+  if (auto xdg = environmentUtf8("XDG_CONFIG_HOME")) {
+    appendIfFile(files, pathFromUtf8(*xdg) / "mqt-core" / "qdmi.json");
+  } else if (auto home = environmentUtf8("HOME")) {
+    appendIfFile(files,
+                 pathFromUtf8(*home) / ".config" / "mqt-core" / "qdmi.json");


Is the Utf8 in these names really that important? I'd argue we can just drop it (likely already in a PR further down the stack)

burgholzer · 2026-08-26T08:57:24Z

+/// Stages one low-precedence package manifest before the driver is frozen.
+auto stagePackageManifest(const std::filesystem::path& path) -> int;
+
+/// Freezes and returns the staged package manifests.
+[[nodiscard]] auto freezePackageManifests()
+    -> std::vector<std::filesystem::path>;
+
+/// Reopens package-manifest staging after driver construction fails.
+void rollbackPackageManifestFreeze();


Another nomenclature thing "Package Manifest" does not sound like the very best fit.
Maybe "Device Library Manifest" or something more in the direction of "Device Record(s)". I am pretty sure there is good established terminology in CS for that that we can comfortably apply to quantum. This also already applies further down the stack.

burgholzer · 2026-08-26T09:08:28Z

+  LoadedClient::AddManifest addManifest{};
+  LoadedClient::SessionAllocForDevice sessionAllocForDevice{};


Does it make sense to list these as separate members here, or would it make more sense to define some kind of Extension POD to aggregate the extension functionality. Might make it easier if we want to extend it in the future.

burgholzer · 2026-08-26T09:12:00Z

The added code here does not only feel overly complex, it also feels like it does not really concern this PR but rather #2229 and the implementation there.
Since this adds quite a bit of complexity, it may make sense to already fold the relevant parts into #2229 and look at the big picture as to whether the added complexity really makes sense or whether there is a more minimal but equally powerful solution.

burgholzer · 2026-08-26T09:16:07Z

+constexpr auto WARNING_MODE = "MQT_CORE_QDMI_TEST_DEVICE_WARNING";
+
+[[nodiscard]] auto warningMode() -> std::string_view {
+  const auto* const value = std::getenv(WARNING_MODE);
+  return value == nullptr ? std::string_view{} : std::string_view{value};
+}
+
+[[nodiscard]] auto successfulStatus(const std::string_view operation) -> int {
+  const auto mode = warningMode();
+  return mode == "all" || mode == operation ||
+                 (mode == "children-null" && operation == "children")
+             ? QDMI_WARN_GENERAL
+             : QDMI_SUCCESS;
+}


This whole warning handling feels like it is adding something that we have not really used before. No one in the QDMI community that I know of has been using warnings so far, so I am not sure the ecosystem is equipped to deal with the consequences of getting QDMI_WARN_GENERAL instead of QDMI_SUCCESS.
Obviously, we could set a good precedent here, but this feels like it does not necessarily belong in this PR stack, but rather a follow-up.
This would probably also mandate something like "warnings as errors", which only further complicates the design.
For now, I think we should stick with logging warnings, but not making use of QDMI_WARN_GENERAL

burgholzer · 2026-08-26T09:25:50Z

We should absolutely make sure that all of these tests added here are genuinely useful or just pin down implementation details instead of asserting useful/expected behavior. This holds for the entire PR stack!

burgholzer · 2026-08-26T09:28:24Z

Let's try to minimize test files that only contain a single test. If we continue like this, we'll have more test files than actual library files, which is certainly not sustainable. Mitigate that in the next round of iteration on the entire stack.
Do not add tests simply to meet the 90% coverage target. If it cannot reasonably be met without going out of ones way, it should be purposely decided that it is not necessary to cover all possible failure conditions.

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-default-driver-extension-c2 branch from 9e7ae7b to 15473b3 Compare August 24, 2026 19:10

burgholzer removed the dependencies Pull requests that update a dependency file label Aug 24, 2026

burgholzer mentioned this pull request Aug 24, 2026

🔧 Harden installed QDMI runtime staging #2231

Draft

12 tasks

This was referenced Aug 24, 2026

💥 Remove obsolete QDMI calibration and pulse metadata #2233

Draft

♻️ Load a replaceable QDMI Client driver #2229

Draft

burgholzer force-pushed the codex/qdmi-default-driver-extension-c2 branch from 15473b3 to 1496655 Compare August 24, 2026 20:21

burgholzer changed the base branch from codex/qdmi-client-runtime-c1 to codex/qdmi-v14-cleanup-adoption August 24, 2026 20:21

burgholzer force-pushed the codex/qdmi-default-driver-extension-c2 branch 6 times, most recently from e81a275 to 5c00537 Compare August 24, 2026 23:01

burgholzer force-pushed the codex/qdmi-default-driver-extension-c2 branch from 5c00537 to 8a351cf Compare August 24, 2026 23:48

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

burgholzer commented Aug 26, 2026

View reviewed changes

burgholzer mentioned this pull request Aug 27, 2026

♻️ Redesign QDMI device management #1901

Closed

✨ Add an optional packaged QDMI Driver extension

5565e80

Assisted-by: GPT-5.6 Sol via Codex

burgholzer force-pushed the codex/qdmi-default-driver-extension-c2 branch from 8a351cf to 5565e80 Compare August 27, 2026 14:03

Navigation Menu

Uh oh!

Uh oh!

✨ Add an optional packaged QDMI Driver extension - #2230

✨ Add an optional packaged QDMI Driver extension#2230
burgholzer wants to merge 1 commit into
codex/qdmi-v14-cleanup-adoptionfrom
codex/qdmi-default-driver-extension-c2

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 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!

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

		LoadedClient::AddManifest addManifest{};
		LoadedClient::SessionAllocForDevice sessionAllocForDevice{};

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

Dependencies

Validation

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