|
QDMI v1.3.4-dev
Quantum Device Management Interface
|
|
QDMI v1.3.4-dev
Quantum Device Management Interface
|
This document describes breaking changes and provides guidance for upgrading between versions. For a complete list of changes, including minor and patch releases, please refer to the changelog.
QDMI replaces the program-format enum with an exact QDMI_Program_Format descriptor. The descriptor contains an ID, packed Semantic Versioning release, profile, and text or binary encoding. Devices list every accepted descriptor in QDMI_DEVICE_PROPERTY_SUPPORTEDPROGRAMFORMATS. Clients must submit one of those exact values and must not infer version compatibility. Descriptor identity is a value contract: callers can reconstruct a canonical value and compare it with QDMI_program_format_equal.
Text payloads contain exactly one trailing NUL and no earlier NUL; their size includes that NUL. Binary payloads are nonempty arbitrary byte sequences.
QDMI reserves the unqualified IDs openqasm and qir for standard formats. Vendor formats use <vendor>.<custom-format-identifier> IDs such as iqm.circuit; the vendor component is not a reverse domain name.
Use the following replacements for the removed enum values:
| Removed value | QDMI_Program_Format replacement |
|---|---|
| QDMI_PROGRAM_FORMAT_QASM2 | {QDMI_MAKE_VERSION(2, 0, 0), QDMI_PROGRAM_ENCODING_TEXT, "openqasm", ""} |
| QDMI_PROGRAM_FORMAT_QASM3 | {QDMI_MAKE_VERSION(3, 0, 0), QDMI_PROGRAM_ENCODING_TEXT, "openqasm", ""} |
| QDMI_PROGRAM_FORMAT_QIRBASESTRING | {QDMI_MAKE_VERSION(1, 0, 0), QDMI_PROGRAM_ENCODING_TEXT, "qir", "base"} |
| QDMI_PROGRAM_FORMAT_QIRBASEMODULE | {QDMI_MAKE_VERSION(1, 0, 0), QDMI_PROGRAM_ENCODING_BINARY, "qir", "base"} |
| QDMI_PROGRAM_FORMAT_QIRADAPTIVESTRING | {QDMI_MAKE_VERSION(1, 0, 0), QDMI_PROGRAM_ENCODING_TEXT, "qir", "adaptive"} |
| QDMI_PROGRAM_FORMAT_QIRADAPTIVEMODULE | {QDMI_MAKE_VERSION(1, 0, 0), QDMI_PROGRAM_ENCODING_BINARY, "qir", "adaptive"} |
| QDMI_PROGRAM_FORMAT_QPY | No standard replacement; providers must document a vendor-namespaced descriptor |
| QDMI_PROGRAM_FORMAT_IQMJSON | A provider-defined descriptor with a namespaced ID |
| QDMI_PROGRAM_FORMAT_CALIBRATION | No descriptor; use a provider extension to trigger calibration |
| QDMI_PROGRAM_FORMAT_BATCHJOB | No descriptor; use QDMI_job_set_programs |
| QDMI_PROGRAM_FORMAT_CUSTOM1 through CUSTOM5 | A provider-defined descriptor with a namespaced ID |
| QDMI_PROGRAM_FORMAT_MAX | No replacement |
QDMI defines no version, profile, wire, or result semantics for the removed QPY and IQM JSON values. A provider can expose either format with a vendor-namespaced descriptor and must document that descriptor and its payload and result contract.
The QIR replacements above preserve the QIR 1.0 meaning of the removed enum values. A current QIR 2.1 descriptor instead uses QDMI_MAKE_VERSION(2, 1, 0). The descriptor version identifies the QIR specification and is independent of the version in a QIR output-schema stream.
Standard descriptors define exact mappings. They filter zone sites from QDMI_DEVICE_PROPERTY_SITES and preserve the provider order of the remaining regular sites. OpenQASM quantum instructions match a reported local operation by name, qubit arity, and parameter arity. OpenQASM q[i] maps to the i-th regular site, while OpenQASM 3 $i maps by QDMI_SITE_PROPERTY_INDEX to a regular site. A QIR function named __quantum__qis__NAME__body matches the reported local operation named NAME, with the same qubit and parameter arity. Statically identified QIR qubits map by QDMI_SITE_PROPERTY_INDEX to regular sites. A device that advertises QIR must assign the regular sites exactly the index set [0, N), where N is QDMI_DEVICE_PROPERTY_QUBITSNUM. Format- or profile-mandated measurement, output, and runtime primitives do not need corresponding operation records. The standard mappings do not define how a payload selects a zoned operation.
The new QDMI_device_session_query_program_features device function and QDMI_device_query_program_features client function query optional execution features for one exact descriptor. A successful query returns the complete list of optional QDMI_Program_Feature records. A successful empty query means that only the format's normative baseline is supported. QDMI_ERROR_NOTSUPPORTED means that feature metadata is unknown. Boolean features use value zero. Width features, such as integer computation, use one feature group per supported width. A standard descriptor does not imply support for every construct that its source format can express.
Use QDMI_PROGRAM_FEATURE_UNCONSTRAINED(id, value) to initialize an unrestricted feature without naming the constraint fields. Repeated records for one feature and value add conjunctive typed constraints. QDMI initially defines maximum control-flow nesting depth, loop iteration count, and multiway case count. A client must treat a known feature group as unusable if any constraint is unknown, malformed, duplicated, or not defined for that feature.
Device plugins and clients must use matching minor-version headers. A QDMI 1.3 client must not pass an enum value to a QDMI 1.4 device, and a QDMI 1.4 client must not call the new query on a QDMI 1.3 device.
Calibration and batch submission are no longer program formats. QDMI_DEVICE_PROPERTY_NEEDSCALIBRATION remains available, but QDMI does not define a portable calibration trigger. Use QDMI_job_set_programs to submit an ordered program list as one job. One exact format, shot count, lifecycle, and job ID apply to the complete list. Retrieve each result with QDMI_job_get_results; its program index matches the input order. A support probe passes programs == NULL and a nonzero count. It succeeds only for that exact descriptor and cardinality and does not change the job. Text programs contain exactly one trailing NUL. Binary programs are arbitrary nonempty byte sequences.
QDMI_JOB_PARAMETER_PROGRAM and QDMI_DEVICE_JOB_PARAMETER_PROGRAM were removed. Use QDMI_job_set_programs and QDMI_device_job_set_programs for both single- and multi-program jobs. Setting the same QDMI_JOB_PARAMETER_PROGRAMFORMAT keeps the payload. Setting a different supported format clears the payload. Failed setters leave the complete prior state unchanged. QDMI_JOB_PROPERTY_PROGRAMSNUM returns QDMI_ERROR_BADSTATE until a payload is set and then reports the exact count.
The result getter now takes a zero-based program index:
Use index zero for a single-program job. A multi-program job exposes no partial results. Retrieval by job ID succeeds only when the implementation can restore the exact historical descriptor, program count, aggregate status, and result index mapping. Otherwise, it returns QDMI_ERROR_NOTSUPPORTED.
QDMI_JOB_RESULT_SHOTS and histogram keys now describe payload-declared flat bit outputs. OpenQASM 2 uses creg declarations in source order. OpenQASM 3 uses explicit bit-valued outputs, or the language's implicit outputs when none are declared. Both use increasing bit indices within each declaration. QIR uses primitive result-recording call order. These rules assign logical slots from zero. Strings write the highest slot first and slot zero at the right, so slot values [1, 0, 0] produce "001". The payload schema owns the slots; their width and order are independent of device sites. Logical qubit zero remains the least-significant basis bit for state and probability results. A provider returns QDMI_ERROR_NOTSUPPORTED when an output cannot be represented losslessly as a fixed-width bit string. QDMI_JOB_RESULT_PROGRAMOUTPUT returns a format-defined output byte sequence when a flat bit result cannot represent the payload result. A QIR specification that defines an output schema uses a complete output-schema stream for every shot. Older QIR or provider-defined descriptors can return QDMI_ERROR_NOTSUPPORTED. The byte sequence need not be NUL-terminated.
On the client interface, job properties report the exact descriptor submitted by the client. On the device interface, they report the descriptor executed by the device. A translating driver must retain this mapping, including for job retrieval, or reject retrieval with QDMI_ERROR_NOTSUPPORTED. A retrieved job can report its historical descriptor after the device stops advertising that descriptor.
Each QDMI enum with CUSTOM members reserves the inclusive range from 999999995 through INT32_MAX for provider-defined values. The existing CUSTOM1 through CUSTOM5 names remain aliases for the first five values. Values between an enum's regular MAX member and 999999995 are invalid; unrecognized values in the custom range are valid inputs that return QDMI_ERROR_NOTSUPPORTED.
Every QDMI 1.4 device library must export QDMI_device_session_retrieve_device_job_by_id and QDMI_device_job_set_programs. The existing QDMI_device_job_get_results export now takes a program index. A device can return QDMI_ERROR_NOTSUPPORTED from retrieval or a program-list support probe when it cannot provide the complete contract. Drivers no longer accept missing symbols. Add stubs and update the result-getter signature before rebuilding an older device library against the QDMI 1.4 headers.
Jobs can now be retrieved by their ID via the new functions QDMI_session_retrieve_job_by_id (client interface) and QDMI_device_session_retrieve_device_job_by_id (device interface). The ID is the one reported by QDMI_JOB_PROPERTY_ID and QDMI_DEVICE_JOB_PROPERTY_ID, respectively.
A retrieved job can be queried, waited for, cancelled, and used to fetch results, but its parameters cannot be set and it cannot be submitted again. Devices that do not support this must return QDMI_ERROR_NOTSUPPORTED.
Two optional properties have been added:
Both are optional; implementations that cannot provide a trustworthy value return QDMI_ERROR_NOTSUPPORTED.
Device targets can now publish their stable ID and symbol prefix via the new configure_qdmi_device_target CMake function, which sets and exports the QDMI_DEVICE_ID and QDMI_DEVICE_PREFIX target properties.
Newly generated projects use this by default and expose an overridable <PREFIX>_QDMI_DEVICE_ID cache variable that defaults to <lowercase-prefix>.default. Existing device implementations can adopt it by calling the function for their device target. Once distributed, the ID should remain stable so that applications can keep referring to the same device.
The type used to represent core / processing-unit related information has been changed. A new device library implementation specific opaque pointer type named QDMI_Child_Device has been introduced for the QDMI_DEVICE_PROPERTY_CHILDDEVICES data queried via the device_query_interface.
CMake presets have been added to provide a standardized and reproducible way to configure builds across different platforms. These presets are also used in our CI.
On Unix systems, the debug, release, and coverage presets can be used to configure, build, and test QDMI.
Additionally, the lint preset can be used to configure and build QDMI in preparation for a clang-tidy run.
This release adds three new properties and parameters to the interface to enable support for multicore architectures:
The respective changes are additive and non-breaking, but device implementations that want to support multicore architectures will need to implement the new properties and parameters.
As of this release, the QDMI header-only library is no longer required to be linked into QDMI device implementations. Instead, each QDMI device now bundles all necessary headers in its own include directory. This allows distributing any QDMI device implementation in a truly standalone manner. You can remove the qdmi::qdmi target from the CMake configuration of your device implementation.
To properly resolve the imports, you will need to adjust the header includes in your device implementation. Any include of the form
must be replaced with
where my is the prefix of your device implementation.
Device implementations may now be compiled with hidden symbol visibility, which is a common best practice for C++ libraries to reduce symbol clashes and improve load times. In practice, this means that only symbols explicitly marked for export are accessible from outside the device library.
The header my_qdmi/export.h (where my is your device prefix) provides the export macro MY_QDMI_EXPORT. Use this header to control, which symbols are part of your public API.
All QDMI interface functions are already marked for export in my_qdmi/device.h. You only need to add MY_QDMI_EXPORT manually for additional custom public functions.
To enable this behavior, add the following CMake code to your device target's configuration:
where MY is your device prefix.
The QDMI device template has been updated to be compatible with the latest version of the QDMI specification and to include several improvements. Most importantly, as described above, the device implementation no longer needs to link against the QDMI header-only library and is now built with hidden symbol visibility by default.
Beyond that, the template has been extended to include:
In order to avoid a mismatch in the target name for the qdmi_project_warnings target between the source and installed versions of QDMI, the target alias has been adjusted. If your project relies on qdmi::project_warnings, you need to change it to qdmi::qdmi_project_warnings. More rationale is available in the PR description.
The CMake functionality for handling the prefixing of QDMI devices was refactored to improve the usability and flexibility. Particularly, the generate_device_defs_executable CMake function has been changed to allow the optional specification of the QDMI device target to link via a TARGET keyword argument. Example usage:
This change is expected to be fully backwards compatible.
The QDMI device template has been significantly updated to be more useful and provide a fully fletched starting point for new devices. This includes updating the existing template code with the latest best practices, including updating the CMake version range to 3.24-4.2 and using C++20 features.
In addition to these basic changes, the template has been extended to include:
The corresponding documentation has been updated to reflect these changes.
In addition, the template instantiation workflow has changed: the template files are no longer written as a side effect of the CMake configure step. Instead, configuration only defines the prefix and output path, and the actual file generation happens when the explicit build target qdmi-template is invoked (use qdmi-template-clean to overwrite an existing output directory).
Version 1.2.0 introduces several breaking changes, primarily related to type system improvements, duration/length unit handling, and API enhancements for neutral atom devices. Please review all sections carefully when upgrading.
Two new program formats were added to the QDMI_Program_Format enum to support additional quantum programming frameworks:
These additions are backward-compatible and do not require changes to existing code.
Breaking Change: Length and duration properties now use integer types (int64_t or uint64_t) instead of double, and represent values in device-specific units rather than standard SI units.
Device implementations must now provide the following properties to define their unit system:
Before (v1.1.0):
After (v1.2.0):
To get the device's duration unit, use the QDMI_DEVICE_PROPERTY_DURATIONUNIT property.
Migration: Replace all occurrences of QDMI_SITE_PROPERTY_ID with QDMI_SITE_PROPERTY_INDEX in your codebase.
Version 1.2.0 adds comprehensive support for neutral atom quantum computing platforms through a set of new device, site, and operation properties. These additions are non-breaking and optional for non-neutral-atom devices.
These properties enable precise modeling of neutral atom device capabilities.
Two new functions have been added for querying job properties:
These functions allow clients to retrieve job metadata and previously set parameter values, enabling better job tracking and debugging.
Breaking Change: The functions QDMI_job_wait and QDMI_device_job_wait now require an additional timeout parameter.
Function Signatures:
Timeout Parameter:
Migration:
Four new authentication options have been added to QDMI_SESSION_PARAMETER and QDMI_DEVICE_SESSION_PARAMETER enums to support diverse authentication mechanisms:
Breaking Change: The addition of new authentication options has changed the numeric values of existing enum entries in QDMI_SESSION_PARAMETER and QDMI_DEVICE_SESSION_PARAMETER.
Impact:
Migration:
Device Implementation Requirements:
Breaking Change: The QDMI_JOB_STATUS enum values have been reordered to better reflect the typical job lifecycle progression.
Impact:
Migration:
Breaking Change: The minimum required CMake version has been raised from 3.19 to 3.24.
Migration:
Rationale: This change enables better build system features and improved dependency management.
For quick reference, here are all breaking changes in v1.2.0:
1.16.1