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.

Unreleased

1.2.1 - 2025-12-22

Fix for using Installed Version of QDMI

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.

Changes to Prefix Handling

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:

generate_device_defs_executable("my_prefix" TARGET my_device)

This change is expected to be fully backwards compatible.

Updated QDMI device template

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:

installation instructions for the device library
boilerplate documentation infrastructure
a thin Python wrapper for distributing the device implementation
linter and formatter configuration
automatic license header generation
and more.

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).

1.2.0 - 2025-12-01

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.

New Program Formats (Non-Breaking)

Two new program formats were added to the QDMI_Program_Format enum to support additional quantum programming frameworks:

QDMI_PROGRAM_FORMAT_QPY: Binary representation of a Qiskit QuantumCircuit using the QPY format
QDMI_PROGRAM_FORMAT_IQMJSON: IQM's proprietary data transfer format serialized as JSON

These additions are backward-compatible and do not require changes to existing code.

Units for Length and Duration (Breaking Change)

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.

What Changed

All duration-related properties now return integer values in device-specific units
All length-related properties now return integer values in device-specific units
The raw integer values must be interpreted using unit metadata provided by the device

Required Changes for Device Implementations

Device implementations must now provide the following properties to define their unit system:

QDMI_DEVICE_PROPERTY_LENGTHUNIT: String describing the length unit (e.g., "m", "μm", "nm")
QDMI_DEVICE_PROPERTY_DURATIONUNIT: String describing the duration unit (e.g., "s", "ms", "ns")
QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR: Multiplier to apply to apply to raw length values to convert to the device's length unit
QDMI_DEVICE_PROPERTY_DURATIONSCALEFACTOR: Multiplier to apply to raw duration values to convert to the device's duration unit

Migration Example

Before (v1.1.0):

double t1;
QDMI_device_query_site_property(
      device, site, QDMI_SITE_PROPERTY_T1, sizeof(double), &t1, nullptr);
// T1 time in us

After (v1.2.0):

uint64_t t1 = 0;
QDMI_device_query_site_property(
  device, site, QDMI_SITE_PROPERTY_T1, sizeof(uint64_t), &t1, nullptr);
 
double scale_factor = 0.0;
QDMI_device_query_device_property(
  device, QDMI_DEVICE_PROPERTY_DURATIONSCALEFACTOR, sizeof(double),
  &scale_factor, nullptr);
 
// T1 time in device duration units
double t1_in_device_units = static_cast<double>(t1) * scale_factor;

To get the device's duration unit, use the QDMI_DEVICE_PROPERTY_DURATIONUNIT property.

size_t size = 0;
QDMI_device_query_device_property(
  device, QDMI_DEVICE_PROPERTY_DURATIONUNIT, 0, nullptr, &size);
std::string unit(size - 1, '\0');
QDMI_device_query_device_property(
  device, QDMI_DEVICE_PROPERTY_DURATIONUNIT, size, unit.data(),
  nullptr);

Property Naming and New Properties (Partially Breaking)

Breaking Change: Property Rename

QDMI_SITE_PROPERTY_ID has been renamed to QDMI_SITE_PROPERTY_INDEX for improved naming consistency

Migration: Replace all occurrences of QDMI_SITE_PROPERTY_ID with QDMI_SITE_PROPERTY_INDEX in your codebase.

New Properties (Non-Breaking)

QDMI_OPERATION_PROPERTY_SITES: Returns the list of sites to which an operation applies
QDMI_DEVICE_PROPERTY_SUPPORTEDPROGRAMFORMATS: Returns the list of supported program formats for the device. Devices are highly encouraged to implement support for this property.
QDMI_DEVICE_PROPERTY_PULSESUPPORT: Returns the degree of pulse-level control support using the QDMI_Device_Pulse_Support_Level enum
- Devices without pulse support should return QDMI_DEVICE_PULSE_SUPPORT_LEVEL_NONE
- Other levels include LEVEL_SITE, LEVEL_CHANNEL, and LEVEL_SITEANDCHANNEL

Neutral Atom Device Properties (Non-Breaking)

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.

Device-Level Properties

QDMI_DEVICE_PROPERTY_MINATOMDISTANCE: Minimum allowed distance between atoms (in device length units)

Site-Level Properties

QDMI_SITE_PROPERTY_XCOORDINATE, YCOORDINATE, ZCOORDINATE: Spatial coordinates of sites in device coordinate system
QDMI_SITE_PROPERTY_ISZONE: Boolean indicating whether a site is a zone (flexible atom placement area) or fixed position
QDMI_SITE_PROPERTY_XEXTENT, YEXTENT, ZEXTENT: Physical extent of zone sites (returns QDMI_ERROR_NOTSUPPORTED for regular fixed-position sites)
QDMI_SITE_PROPERTY_MODULEINDEX, SUBMODULEINDEX: Hierarchical module/submodule assignment for modular device architectures

Operation-Level Properties

QDMI_OPERATION_PROPERTY_INTERACTIONRADIUS: Radius within which an operation affects nearby atoms
QDMI_OPERATION_PROPERTY_BLOCKINGRADIUS: Radius within which other operations are blocked during execution
QDMI_OPERATION_PROPERTY_ISZONED: Boolean indicating whether the operation is applied to a zone (area) rather than fixed sites
QDMI_OPERATION_PROPERTY_IDLINGFIDELITY: Fidelity of idling atoms within the operation's interaction area (relevant for zoned operations)
QDMI_OPERATION_PROPERTY_MEANSHUTTLINGSPEED: Average speed for atom movement operations

These properties enable precise modeling of neutral atom device capabilities.

Job Property Query and Timeout (Breaking Change)

New Job Property Query Functions (Non-Breaking)

Two new functions have been added for querying job properties:

QDMI_job_query_property: Client-side function to query job properties
QDMI_device_job_query_property: Device-side implementation function

These functions allow clients to retrieve job metadata and previously set parameter values, enabling better job tracking and debugging.

Breaking Change: Timeout Parameter Required

Breaking Change: The functions QDMI_job_wait and QDMI_device_job_wait now require an additional timeout parameter.

Function Signatures:

// Before (v1.1.0)
int QDMI_job_wait(QDMI_Job job);
int QDMI_device_job_wait(QDMI_Device_Job job);
 
// After (v1.2.0)
int QDMI_job_wait(QDMI_Job job, size_t timeout);
int QDMI_device_job_wait(QDMI_Device_Job job, size_t timeout);

Timeout Parameter:

Type: size_t
Unit: Seconds
Value 0: Wait indefinitely (equivalent to old behavior)
Non-zero: Maximum wait time in seconds
New return code: QDMI_ERROR_TIMEOUT when timeout expires before job completion

Migration:

// To maintain v1.1.0 behavior (indefinite wait):
QDMI_job_wait(job, 0);
 
// Or specify an explicit timeout (e.g., 30 seconds):
int ret = QDMI_job_wait(job, 30);
if (ret == QDMI_ERROR_TIMEOUT) {
    // Handle timeout case
}

Authentication Options (Breaking Change)

New Authentication Parameters (Non-Breaking)

Four new authentication options have been added to QDMI_SESSION_PARAMETER and QDMI_DEVICE_SESSION_PARAMETER enums to support diverse authentication mechanisms:

QDMI_SESSION_PARAMETER_AUTHFILE: Path to a file containing authentication credentials
QDMI_SESSION_PARAMETER_AUTHURL: URL endpoint for authentication
QDMI_SESSION_PARAMETER_USERNAME: Username for authentication
QDMI_SESSION_PARAMETER_PASSWORD: Password for authentication

Breaking Change: Enum Value Ordering

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:

Code that relies on specific numeric values of enum constants will break
Code using the enum symbolic names will continue to work correctly

Migration:

Recommended: Always use symbolic enum names (e.g., QDMI_SESSION_PARAMETER_HOST) rather than numeric values
If numeric values were stored or transmitted, update serialization/deserialization code to use version-aware mapping

Device Implementation Requirements:

Device implementations should document the authentication parameters they support
Unsupported parameters should return QDMI_ERROR_NOTSUPPORTED
New parameters are optional; existing authentication mechanisms remain valid

Job Status Enum Updates (Breaking Change)

Breaking Change: The QDMI_JOB_STATUS enum values have been reordered to better reflect the typical job lifecycle progression.

Impact:

Code relying on numeric values of QDMI_JOB_STATUS enum constants will break
Code using symbolic names will continue to work correctly

Migration:

Use symbolic enum names (e.g., QDMI_JOB_STATUS_QUEUED) instead of numeric values
Review any code that performs numeric comparisons or ordering of job status values
Update serialization/deserialization code to be version-aware

CMake Version Requirement (Breaking Change)

Breaking Change: The minimum required CMake version has been raised from 3.19 to 3.24.

Migration:

Update your CMake installation to version 3.24 or later
Update CI/CD pipelines and build documentation to reflect the new requirement
Most modern Linux distributions and development environments provide CMake 3.24+

Rationale: This change enables better build system features and improved dependency management.

Summary of Breaking Changes

For quick reference, here are all breaking changes in v1.2.0:

Duration/length properties: Changed from double to integer types with device-specific units
QDMI_SITE_PROPERTY_ID: Renamed to QDMI_SITE_PROPERTY_INDEX
Job wait functions: Now require timeout parameter
QDMI_SESSION_PARAMETER enums: Reordered due to new authentication options
QDMI_JOB_STATUS enum: Reordered to reflect job lifecycle
CMake: Minimum version raised to 3.24