✨ Adopt exact QDMI 1.4 payload contracts across Core by burgholzer · Pull Request #2226 · munich-quantum-toolkit/core

burgholzer · 2026-08-24T14:50:35Z

🤖 AI text below 🤖

Lead: @simon1hofmann. Cross-repository coordination: @burgholzer.

Description

Keep the runtime portion of the experimental QDMI program-capability contract independently reviewable. This branch targets v4.1, without compiler-only #2219, replaceable drivers, metadata cleanup, or native multi-program adoption.

Native multi-program jobs and indexed results were extracted into #2373 using QDMI #509's existing format enum. This prototype instead uses QDMI #508's exact format descriptors, optional feature records, single-program submission, and format-defined output bytes. Mechanical Qiskit/PennyLane adaptations remain here so this runtime builds and its SDK consumers import and run coherently.

Current mainline optional shots, binary transport, DDSIM QCO simulation, session ownership, concurrent single-program execution, and fail-closed target inference are preserved. It does not replace concurrent submissions with synthetic aggregate jobs.

Design and release gate

This is a non-blocking Core 4.1 / QDMI 1.4 candidate, not Core 4.0 scope or a settled public contract. QDMI #523 and Core #2365 must record the format/capability decisions before this becomes merge-ready. In particular, provider-neutral execution guarantees, opaque payload semantics, and supported versus native operations remain design work.

Refs #2365, #2373, Munich-Quantum-Software-Stack/QDMI#508, Munich-Quantum-Software-Stack/QDMI#523.

Core #2227 is the separate adapter between this runtime and #2219's compiler model. Neither foundation depends on that adapter or on the other foundation. The development QDMI pin must be replaced with a released dependency before publishing release artifacts.

Validation

Independent native suite: 3,874 passed; one existing skip.
Python QDMI, Qiskit and PennyLane suite: 399 passed.
Generated stubs, repository lint and C++ lint passed.
Tests retain current concurrency and optional-shot regressions, and exercise descriptors, optional feature metadata, binary/text framing, retrieval, SDK serialization and results.
Hosted CI and design review remain separate gates.

AI assistance was used for extraction, rebasing, implementation adaptations, tests, documentation and this description.

Interface acceptance

Describe the device-and-format-specific contract through #2365 and QDMI #523. Do not assume full OpenQASM/QIR language support or a universal native/verbatim compilation boundary. The prototype remains a priority for Core 4.1, not a release blocker.

Before the interface change merges, link a working Core consumer and a demonstration with at least one existing provider, preferably both where applicable. Compatibility evidence suffices when a provider needs no changes. Development revisions may support these tests; published artifacts must use released dependencies.

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-24T16:23:59Z

Codecov Report

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

Files with missing lines	Patch %	Lines
include/mqt-core/qdmi/common/Common.hpp	28.5%	10 Missing ⚠️
python/mqt/core/plugins/pennylane/converter.py	87.8%	8 Missing ⚠️
src/qdmi/Client.cpp	96.8%	4 Missing ⚠️
src/qdmi/devices/dd/Device.cpp	98.1%	2 Missing ⚠️
python/mqt/core/plugins/qiskit/backend.py	98.2%	1 Missing ⚠️
src/qdmi/driver/Driver.cpp	96.0%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

burgholzer

This one took quite a bit of time to review. and there are still several areas that I would like to see changed. However, I have the feeling this is going to be the last iteration on this before it is ready.

@denialhaag @simon1hofmann do you have any feedback on top of the above?

burgholzer · 2026-08-25T09:51:10Z

+[[nodiscard]] inline std::string
+decodeText(std::string value, const std::string_view description) {
+  if (value.empty() || value.back() != '\0') {
+    throw std::invalid_argument(std::string(description) +
+                                " is not null-terminated");
+  }
+  if (value.find('\0') != value.size() - 1U) {
+    throw std::invalid_argument(std::string(description) +
+                                " contains an embedded null byte");
+  }
+  value.pop_back();
+  return value;
+}


I am likely the one being too dense here, but it feels like this may be introducing off-by-one errors or false requirements.
an std::string is always null-terminated and IIRC the null terminator is not accounted in size(). I want to make absolutely sure that this doesn't introduce an architecture where strings are essentially <chars>\0\0 in memory.

burgholzer · 2026-08-25T09:52:24Z

+  if (value.empty()) {
+    throw std::invalid_argument(std::string(description) +
+                                " is not null-terminated");
+  }


This error message feels wrong. are we sure this is useful, needed, and correct?

burgholzer · 2026-08-25T09:54:29Z

-      std::string value(size - 1, '\0');
+      std::string value(size, '\0');
      result = QDMI_device_query_device_property(device_.get(), prop, size,
                                                 value.data(), nullptr);
      qdmi::throwIfError(result, msg);
-      return value;
+      return detail::decodeText(std::move(value), msg);


This is another case where I would want to make absolutely sure this is correct and does not introduce off-by-one errors. There's more cases below.

burgholzer · 2026-08-25T09:59:10Z

+  job.def(
+      "get_results",
+      [](const qdmi::Job& self, const size_t programIndex,
+         const QDMI_Job_Result result) {
+        const auto value = self.getResults(programIndex, result);
+        return nb::bytes(reinterpret_cast<const char*>(value.data()),
+                         value.size());
+      },
+      "program_index"_a, "result"_a,
+      "Returns one indexed result as exact bytes.");


would it makes sense to flip the order of the arguments here so that the index could receive a default argument? Which would allow to simplify a few call sites.

burgholzer · 2026-08-25T10:01:34Z

+  job.def_prop_ro("programs_num", &qdmi::Job::getProgramsNum,
+                  "The number of programs in the job.");


Related to another comment from a PR as part of this stack: should this be called num_programs to align better with the rest of the bindings and Python exposure. May also be worth to already rename that on the C++ side before binding to Python.

burgholzer · 2026-08-25T10:31:50Z

-
-
-# MQT Core owns the two OpenQASM formats and registers them through the same
-# registry as everyone else, so the backend walks one ordered list of formats
-# with no format-specific branch. `mqt.core.plugins.qiskit.__init__` imports this
-# module whenever Qiskit is installed, so both formats are available as soon as
-# the adapter is.
-register_program_serializer(ProgramFormat.QASM3, _serialize_to_qasm3)
-register_program_serializer(ProgramFormat.QASM2, _serialize_to_qasm2)


This changes how program serialization for Qiskit is handled from the 3.9.1 release. Make sure all documentation is updated accordingly and there are no remaining fragments of the old integration style.

burgholzer · 2026-08-25T10:34:16Z

+        self._capabilities = DeviceCapabilities(
+            qjit_compatible=False,
+            runtime_code_generation=False,
+            dynamic_qubit_management=False,


feels like the capability management could be better here. dynamic qubit management is an explicit payload capability.
Carefully check for a suitable mapping between feature of the payload and how that maps to PennyLane.

burgholzer · 2026-08-25T10:35:56Z

+                if len(dependencies) > 16:
+                    msg = "A conditional depends on more than 16 measurements."
+                    raise ValidationError(msg)


Is this an artificial limitation or an actual PennyLane limitation?

burgholzer · 2026-08-25T10:37:57Z

QDMI v1.4 also introduces multi-program job submission.
Qiskit backend run natively supports passing QuantumCircuit | Sequence[QuantumCircuit]. the latter case can now be natively be handled by QDMI instead of in the QDMI backend code itself. This should clean up the implementation quite a bit.
With the planned changes to the DDSIM QDMI backend, this can also be properly tested.

burgholzer · 2026-08-25T10:39:08Z

I am not familiar enough with PennyLane to judge, but I would guess it also supports the submission of multiple circuits to a device as part of one job. This should now work natively with QDMI v1.4
Explore whether the device itself can be improved in that regard.

simon1hofmann

Went through the changes and have some comments that should be double-checked.

simon1hofmann · 2026-08-25T11:29:02Z

@@ -505,15 +613,16 @@
      // Update the measurement counts.
      ++counts_[runtime.getMeasurements()];


getMeasurements() stores slot 0 first, but QDMI requires the highest slot first. Values [1,0,0] therefore produce "100" instead of "001".

If this is true, then we may want to adjust the QIR runtime function itself so that it follows the same convention. We should generally try to stick to the same convention throughout MQT Core wherever we can; even if this means changes now.

simon1hofmann · 2026-08-25T11:30:18Z

  switch (result) {
  case QDMI_JOB_RESULT_HIST_KEYS:
  case QDMI_JOB_RESULT_HIST_VALUES:
    if (numShots_ == 0) {
      return QDMI_ERROR_INVALIDARGUMENT;
    }
    return getHistogram(result, size, data, sizeRet);


Sampled jobs always expose histograms even when bool, integer, floating-point, or container outputs are omitted. QDMI requires QDMI_ERROR_NOTSUPPORTED when output cannot be represented losslessly.

Hm. This feels a bit wrong to me. Shouldn't it be up to getHistogram to report the error? Maybe I am misinterpreting this though?

Yes that should be reported by getHistogram, but that function currently never reports that error 🤔

🤖 AI text below 🤖
Yes, getHistogram is the better place to report this. My concern was about the current behavior, not that the check must live in this switch. getHistogram currently always succeeds, while counts_ only contains RESULT/RESULT_ARRAY bits. For AdaptiveRecordOutputs.ll, that omits the recorded integer and double values, so the three-bit histogram is only a partial representation. Under the pinned QDMI contract, the histogram queries must return QDMI_ERROR_NOTSUPPORTED in that case. Container records alone do not invalidate the histogram; that part of my wording was too broad.

Hm. We may want to adjust the QDMI spec here. This feels overly restrictive. It may still make sense to export a histogram, even though there is further output in the proprietary results.
Good time to make changes to the open QDMI PRs so this becomes less of a hassle.

simon1hofmann · 2026-08-25T11:31:23Z

+        capabilities = self._program_capabilities or set()
+        for capability, instruction, name in (
+            ("forward-branching", IfElseOp, "if_else"),
+            ("counted-iteration", ForLoopOp, "for_loop"),
+            ("conditional-loop", WhileLoopOp, "while_loop"),
+            ("multiway-branching", SwitchCaseOp, "switch_case"),
+        ):
+            if capability in capabilities:
+                target.add_instruction(instruction, name=name)


Circuits using measurement-driven branches and measured-qubit reuse are accepted without the separately required capabilities.

Is that something that we can reasonably express in Qiskit? without going entirely out of our way checking the program?
This may become a little easier once we can actually wedge the compiler collection between the input program and the required output program.

Probably not..
Just noticed that for example in this test: test_mock_backend.py:547-566 mid-circuit-measurement should be required due to the circuit.measure(0, 0), but boolean-computation is not needed.

simon1hofmann · 2026-08-25T11:31:42Z

+            pending = list(bound_circuit.data)
+            while pending:
+                instruction = pending.pop()
                op_name = instruction.operation.name
+                for block in getattr(instruction.operation, "blocks", ()):
+                    pending.extend(block.data)
+                if op_name in {"if_else", "for_loop", "while_loop", "switch_case"}:
+                    if op_name not in self._target.operation_names:
+                        msg = f"Unsupported control flow operation: '{op_name}'"
+                        raise UnsupportedOperationError(msg)
+                    continue


Circuits using measurement-driven branches and measured-qubit reuse are accepted without the separately required capabilities.

simon1hofmann · 2026-08-25T11:34:28Z

    std::ostringstream output;
    runtime.setOstream(output);
    if (const auto rc = jitSession.run(); rc != 0) {
      throw std::runtime_error(
          llvm::formatv("QIR program failed with error: {}", rc));
    }
    auto state = runtime.takeState();
    dd_ = std::move(state.dd);
    stateVecDD_ = state.edge;
  });


State extraction neither emits the required QIR header nor assigns programOutput_ (observed at :916-918).

State extraction itself should likely not do this at all. But we should definitely be exposing the output stream from QIR through the new result type, which should already be captured by the QIR runner.

simon1hofmann · 2026-08-25T11:36:19Z

+[[nodiscard]] constexpr bool
+isValidProgramFormat(const QDMI_Program_Format& format) noexcept {
+  return format.version != 0U && format.id[0] != '\0' &&
+         (format.encoding == QDMI_PROGRAM_ENCODING_TEXT ||
+          format.encoding == QDMI_PROGRAM_ENCODING_BINARY) &&
+         detail::isCanonicalFixedString(format.id) &&
+         detail::isCanonicalFixedString(format.profile);
+}


It accepts binary OpenQASM, unsupported QIR profiles and unqualified vendor IDs, causing NOTSUPPORTED where QDMI requires INVALIDARGUMENT.

Fair enough. Validation could be more strict here.

simon1hofmann · 2026-08-25T11:37:34Z

    -> QDMI_STATUS {
  if ((data != nullptr && size == 0) ||
-      IS_INVALID_ARGUMENT(result, QDMI_JOB_RESULT)) {
+      IS_INVALID_ARGUMENT(result, QDMI_JOB_RESULT) || programIndex != 0U) {


Index 1 on a completed single-program job returns INVALIDARGUMENT; QDMI requires OUTOFRANGE.

This is true, but the actual implementation will likely change a bit based on the other review comments. It is still good to make use of OUTOFRANGE for out of range access to the result list.

simon1hofmann · 2026-08-25T11:38:35Z

 auto QDMI_Session_impl_d::setParameter(QDMI_Session_Parameter param,
                                       const size_t size,
                                       const void* value) const -> int {
  if ((value != nullptr && size == 0) || param >= QDMI_SESSION_PARAMETER_MAX) {
    return QDMI_ERROR_INVALIDARGUMENT;
  }
  if (status_ != qdmi::SessionStatus::ALLOCATED) {
    return QDMI_ERROR_BADSTATE;
  }
  return QDMI_ERROR_NOTSUPPORTED;
 }

 auto QDMI_Session_impl_d::querySessionProperty(QDMI_Session_Property prop,
                                               size_t size, void* value,
                                               size_t* sizeRet) const -> int {
  if ((value != nullptr && size == 0) || prop >= QDMI_SESSION_PROPERTY_MAX) {
    return QDMI_ERROR_INVALIDARGUMENT;


The >= *_MAX checks reject QDMI’s valid custom range 999999995..INT32_MAX instead of returning NOTSUPPORTED.

I believe this is fixed in a later PR down the line in this PR stack. Might be worth pulling the changes in here already.

After checking again, this might not actually be fixed yet. And it definitely should be fixed. Here would be a good place to do so.

simon1hofmann · 2026-08-25T11:39:47Z

    @overload
    def get_custom_result(self, custom_property: CustomProperty, value_type: type[str]) -> str | None: ...
    @overload
    def get_custom_result(self, custom_property: CustomProperty, value_type: type[bool]) -> bool | None: ...
    @overload
    def get_custom_result(self, custom_property: CustomProperty, value_type: type[int]) -> int | None: ...
    @overload
    def get_custom_result(self, custom_property: CustomProperty, value_type: type[float]) -> float | None: ...
    @overload
    def get_custom_result(self, custom_property: CustomProperty, value_type: type[bytes]) -> bytes | None: ...
    @overload
    def get_custom_result(
        self, custom_property: CustomProperty, value_type: type[str | bool | int | float | bytes]
    ) -> str | bool | int | float | bytes | None:
        """Return an implementation-defined custom job result.

        The caller must provide the type documented by the device implementation.
        Use ``bytes`` to retrieve the value without interpretation. Returns ``None``
        when the custom slot is unsupported.
        """


The runtime binding accepts program_index: int = 0, but every overload omits it, so valid multi-program calls fail static type checking.

This is definitely an oversight and needs to be fixed either in the bindings themselves or in the pattern file.

denialhaag

Some additional comments from my side, none of which I'm super sure about myself:

denialhaag · 2026-08-25T17:54:01Z



 cpp_api_tagfile = ("_build/doxygen/mqt-core.tag", "cpp/", "_build/doxygen/xml")
+_qdmi_api_base = "https://munich-quantum-software-stack.github.io/QDMI/pr-preview/pr-509/"


Just noting that this likely needs to be changed before merging.

Yeah. It needs to at least point to a merged version on the develop branch.
Before the eventual v4 release it needs to be pinned to a released version (the v1.4.0 tag).

denialhaag · 2026-08-25T17:54:15Z

 # run, you must also specify the path to the tagfile here.

-TAGFILES               = _build/qdmi.tag=https://munich-quantum-software-stack.github.io/QDMI/v1.3.2/
+TAGFILES               = _build/qdmi.tag=https://munich-quantum-software-stack.github.io/QDMI/pr-preview/pr-509/


coderabbitai · 2026-08-25T20:05:20Z

Important

Approval pending

CodeRabbit has no unresolved comments, but it has not reviewed the latest commit.

Use the checkbox below to review the latest commit. CodeRabbit will approve the changes if it finds no blocking issues.

🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Retain the design-gated exact-format and optional-feature prototype with its mechanical SDK consumers. Extract native multi-program jobs and indexed results into their own enum-based workstream; preserve current optional shots, binary transport, target inference, and simulator concurrency. 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 QDMI Anything related to QDMI labels Aug 24, 2026

burgholzer self-assigned this Aug 24, 2026

burgholzer mentioned this pull request Aug 24, 2026

✨ Build target environments from QDMI payloads #2227

Draft

12 tasks

burgholzer force-pushed the codex/qdmi-v14-payload-contract branch from ee2c0b4 to f19a838 Compare August 24, 2026 14:55

This was referenced Aug 24, 2026

♻️ Define target compilation with payload specifications #2219

Draft

✨ Legalize control flow for selected payloads #2162

Draft

burgholzer force-pushed the codex/qdmi-v14-payload-contract branch 2 times, most recently from b9a5363 to 31d6f2d Compare August 24, 2026 16:01

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

burgholzer force-pushed the codex/selected-payload-environment branch from bb0240b to 28284fa Compare August 24, 2026 23:47

burgholzer force-pushed the codex/qdmi-v14-payload-contract branch from 31d6f2d to b7d1f2a Compare August 24, 2026 23:47

burgholzer commented Aug 25, 2026

View reviewed changes

simon1hofmann requested changes Aug 25, 2026

View reviewed changes

burgholzer marked this pull request as ready for review August 25, 2026 12:20

denialhaag reviewed Aug 25, 2026

View reviewed changes

This was referenced Aug 26, 2026

💥 Remove obsolete QDMI calibration and pulse metadata #2233

Draft

♻️ Redesign QDMI device management #1901

Closed

burgholzer modified the milestones: QDMI Support, v4.1.0 - QDMI 1.4 / MQSF Sep 1, 2026

burgholzer force-pushed the codex/selected-payload-environment branch from 28284fa to be4c87a Compare September 4, 2026 10:41

burgholzer mentioned this pull request Sep 4, 2026

✨ Adopt native multi-program QDMI jobs #2373

Draft

12 tasks

burgholzer force-pushed the codex/qdmi-v14-payload-contract branch from b7d1f2a to 2ff9471 Compare September 4, 2026 11:15

burgholzer changed the base branch from codex/selected-payload-environment to main September 4, 2026 11:16

burgholzer marked this pull request as draft September 4, 2026 11:16

mergify Bot added the conflict label Sep 4, 2026

burgholzer mentioned this pull request Sep 4, 2026

💡 Design program-format and execution-capability contracts Munich-Quantum-Software-Stack/QDMI#523

Open

burgholzer changed the base branch from main to v4.1 September 4, 2026 14:52

burgholzer assigned simon1hofmann Sep 4, 2026

		job.def_prop_ro("programs_num", &qdmi::Job::getProgramsNum,
		"The number of programs in the job.");

		@@ -505,15 +613,16 @@
		// Update the measurement counts.
		++counts_[runtime.getMeasurements()];



		cpp_api_tagfile = ("_build/doxygen/mqt-core.tag", "cpp/", "_build/doxygen/xml")
		_qdmi_api_base = "https://munich-quantum-software-stack.github.io/QDMI/pr-preview/pr-509/"

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

Design and release gate

Validation

Interface acceptance

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!

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

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

burgholzer commented Aug 24, 2026 •

edited

Loading

codecov Bot commented Aug 24, 2026 •

edited

Loading