🐛 Let the QDMI client trigger a calibration run

[marcelwa]

🤖 AI text below 🤖

Stacked on #2114. The base of this PR is agent/2094-move-iqm-conversion, so the diff shown here is only this change. Merge #2114 first.

Description

Follow-up to the discussion in #2114, where reviewing the program-format classification turned up a bug behind it.

Device::submitJob rejected CALIBRATION and BATCH_JOB together, under one predicate that read as "carries no program payload":

if (hasNoGenericProgramPayload(format)) {
  throw std::invalid_argument(
      "Calibration and batch jobs do not use a generic program payload");
}

They are not the same case, and the calibration half was wrong.

Calibration

QDMI declares the format as `void*` A calibration program and says of it:

Triggering a calibration run does not require a program to be set via QDMI_DEVICE_JOB_PARAMETER_PROGRAM.

That is the explicit exception to QDMI_DEVICE_JOB_PARAMETER_PROGRAM being "required" — the payload is optional, not absent, and QDMI-on-IQM sends one. MQT Core rejected the format before any device call, so a calibration run could not be started at all, with or without a payload. Meanwhile QDMI_DEVICE_PROPERTY_NEEDSCALIBRATION is exposed as Device::getNeedsCalibration() and needs_calibration(): we told a caller a device needs calibration and gave them no way to act on it, even though the spec says exactly how.

This adds a dedicated entry point:

device.submit_calibration_job()                 # no payload
device.submit_calibration_job("configuration")  # text payload
device.submit_calibration_job(b"\x01\x02")      # exact bytes

Device::submitCalibrationJob in C++, with std::optional<std::span<const std::byte>> and a std::string convenience overload. It sets no shot count, because a calibration run executes no circuit. Its own entry point rather than a special case in submitJob, since the payload is optional and the shot count does not apply — submitJob now points there instead of failing silently on intent.

Batch jobs

A different problem. The spec requires the program for a batch job, but types it as a QDMI_Job* list — an array of live job handles. submitJob takes std::span<const std::byte>, so it structurally cannot express one, whatever the check says. MQT Core has no support for batch jobs and no device currently implements the feature; per the discussion, it was added for the multi-chip neutral-atom demonstrator, whose stack left MQT Core in #2137.

So this states the limitation instead of describing it as a missing payload, and leaves the door open:

MQT Core does not support batch jobs. A batch job's program is a list of job
handles, which this API cannot express

Validation

• ./build/release/test/qdmi/mqt-core-qdmi-test — 277 passed
• uv run --no-sync pytest test/python — 626 passed, 4 skipped
• uvx nox -s stubs — the stub diff contains only submit_calibration_job
• uvx nox -s lint — passes, full prek hook set

The bundled DD simulator and SC device both report NEEDSCALIBRATION = 0 and decline the format themselves, so the new tests assert what is actually verifiable here: the client no longer refuses before asking, and the failure arrives as a device error rather than an argument error. A device that supports calibration is needed to exercise the happy path.

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.

AI assistance: written by Claude Opus 5 via Claude Code, under my direction. The last checkbox is left for me to tick after my own review.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[burgholzer]

This also feels ready. Thanks for the fix @marcelwa 🙏🏼
Let's get this in 🚀