🎉 RFC: Redesign of QDMI

[ystade]

Motivation

QDMI v1 was designed as a uniform interface for directly connected QPUs.
While it has proven valuable in that role, its monolithic structure makes it unsuitable for the full range of deployment scenarios encountered in modern HPC–quantum integration:

• Provider pooling: A single cloud or on-premise provider may expose multiple QPUs behind one access point. In v1, this can only be approximated by misusing a single device session to connect multiple QPUs via different base URLs—providers are not first-class entities.
• Federated HPC centers (stack-as-a-device): When another HPC center's entire software stack—including its own compilation, scheduling, and execution infrastructure—is accessed remotely, v1 provides no standardized abstraction. There is no way to distinguish such an orchestration layer from a raw QPU.
• Technology-specific bloat: All device properties for all technologies are packed into shared enums (QDMI_Device_Property, QDMI_Site_Property). As the number of supported technologies grows, the interface becomes increasingly cluttered with properties irrelevant to most devices.
• ABI rigidity: v1 exposes direct C symbol exports, so any addition to the interface risks breaking binary compatibility.

QDMI v2 resolves these issues through a modular architecture: a thin mandatory core captures what all devices share, while optional modules capture where they differ. This enables three integration scenarios—direct QPU access, provider pooling, and federated software stacks—through one uniform interface.

Changelog

New: Modular Architecture

The flat single-file interface is replaced by a structured module system:

• Core interface (qdmi/core.h): Mandatory for all devices. Manages the device lifecycle (context, session), exposes device identity and version, and provides the module-loading mechanism. Accessed via a function pointer table (QDMI_Core_Interface) obtained through the single entry point QDMI_initialize.
• QPU module (qdmi/qpu.h, ID "qpu"): Job submission and result retrieval for QPUs; replaces the v1 client job interface. Queried via QDMI_context_query_module_by_id(ctx, "qpu", &mod) followed by QDMI_context_get_module_interface.
• Provider module (qdmi/provider.h, ID "provider"): New. Exposes managed devices and returns the QDMI_Core_Interface* for each, enabling recursive composition of providers and orchestration layers.
• Orchestration layer module (qdmi/orchestration_layer.h, ID "ol"): New. Extends the provider module with job management functions and QDMI_job_set_device to designate the target QPU. Realizes the stack-as-a-device paradigm.
• Technology-specific modules: Superconducting ("sc") and neutral atom ("na") modules replace technology-specific properties in the shared device/site/operation enums. Each module owns its types (QDMI_SCQubit, QDMI_SCOperation, etc.) and function table.
• Custom modules: Any device may register modules with arbitrary IDs for vendor-specific extensions without modifying the standard interface.

New: Context and Function Tables

v1 relied on QDMI_device_initialize/QDMI_device_finalize as global lifecycle functions and exported individual symbols for each operation. v2 introduces:

• QDMI_initialize(version, callback, user_data, &context, &library): Single entry point resolving all library-level state into an opaque QDMI_Context and a QDMI_Library function table. The version parameter encodes the semantic version for forward/backward compatibility checking.
• All interfaces are exposed as function pointer structs (QDMI_Core_Interface, QDMI_QPU_Interface, etc.), not direct symbol exports. This decouples the ABI from the header layout and allows stable binary interfaces across releases.
• QDMI_context_finalize replaces QDMI_device_finalize.

Changed: Session Management

• Session allocation moves from the driver level to the context level: QDMI_context_allocate_session replaces QDMI_session_alloc.
• Authentication parameter setting is replaced by typed functions (QDMI_session_set_token, QDMI_session_set_authentication_file, QDMI_session_set_authentication_url, QDMI_session_set_username, QDMI_session_set_password), replacing the generic QDMI_session_set_parameter with its untyped void* value and enum key.
• QDMI_context_query_authentication_options allows clients to query which credential combinations a device accepts before allocating a session.

Changed: Job Interface

• The generic QDMI_job_set_parameter/QDMI_job_get_results pattern is replaced by typed functions: QDMI_job_set_payload_string, QDMI_job_set_payload_binary, QDMI_job_set_shot_count.
• Program formats are now first-class objects (QDMI_Program_Format) with a queryable string ID and packed version number. String and binary payload support are independently queryable per format.
• Result retrieval is split into dedicated functions: QDMI_job_get_shots, QDMI_job_get_histogram, QDMI_job_get_state_vector_dense/sparse, QDMI_job_get_probabilities_dense/sparse.
• The QDMI_Device type and QDMI_device_create_job are gone; jobs are created at the session level via QDMI_session_create_job within the QPU or orchestration layer module.

New: Logging

A QDMI_Log_Callback mechanism is introduced at context, session, and job level, replacing ad-hoc error return codes as the sole feedback channel.

Upgrade Guide

Migrating a v1 device implementation to v2 requires the following steps:

1. Replace the entry point. Remove QDMI_device_initialize/QDMI_device_finalize and implement QDMI_initialize returning a QDMI_Context and a populated QDMI_Library struct. Use QDMI_context_finalize for teardown.

2. Implement the core interface. Populate a QDMI_Core_Interface struct with function pointers for context queries (id, name, version, authentication_options, modules) and session management (allocate_session, set_token, initialize, free). Export this struct via the get_interface function pointer in the QDMI_Library returned by QDMI_initialize.

3. Move device introspection to the QPU module. Remove implementations of QDMI_device_query_device_property, QDMI_device_query_site_property, and QDMI_device_query_operation_property. Technology-specific properties (coupling maps, T1/T2 times, site coordinates) move into the "sc" or "na" module function table respectively.

4. Rewrite the job interface. Replace QDMI_job_set_parameter/QDMI_job_get_results implementations with the typed payload setters and result getters defined in qdmi/job/functions.h. Populate a QDMI_QPU_Interface struct and register it as the "qpu" module.

5. Register modules. Implement QDMI_context_query_modules and QDMI_context_query_module_by_id to enumerate all modules the device supports. For each module, implement QDMI_context_get_module_interface to return the corresponding function table pointer.

6. Update authentication. Replace QDMI_device_session_set_parameter logic with typed setters. Implement QDMI_context_query_authentication_options to declare supported credential combinations.

7. Providers and orchestration layers (new implementations only). Implement the QDMI_Provider_Interface or QDMI_OrchestrationLayer_Interface struct and register it under the "provider" or "ol" module ID respectively.

Examples

The examples/ directory contains a self-contained proof-of-concept that exercises all three integration scenarios end-to-end. It is organised into four layers.

Client apps (examples/apps/)

Four numbered C programs correspond directly to the interaction patterns described above:

App	What it shows
1_bootstrapping	Dynamically loads a QDMI v2 shared library with dlopen/LoadLibrary, resolves QDMI_initialize, obtains a QDMI_Context and QDMI_Library, retrieves the QDMI_Core_Interface, allocates a session, sets a token, and initializes the session. This sequence is identical regardless of the device type behind the library.
2_job_lifecycle	Continues from 1_bootstrapping against a QPU. Loads the "qpu" module, negotiates a program format (openqasm 3.0), creates a job, attaches a Bell-state circuit as a string payload, sets the shot count, submits the job, waits for completion, and retrieves measurement results as bitstrings.
3_stack-as-a-device	Continues from 1_bootstrapping against an orchestration layer. Loads the "ol" module, queries the list of managed QPUs, retrieves the QDMI_Core_Interface and context of a managed device, and establishes a session with it—using the exact same bootstrapping sequence as app 1. Demonstrates the stack-as-a-device paradigm.
BONUS_end-to-end	Combines all steps into a single program that runs against the orchestration layer device, queries a managed QPU, and executes a full job lifecycle through the orchestration layer (including QDMI_job_set_device).

Example device implementations (examples/src/ and examples/include/)

Three mock devices implement the v2 interface in C++ and serve as reference implementations as well as targets for the apps and tests:

Device	Modules implemented	Description
qpu/	core, "qpu", "sc"	A simulated superconducting QPU with a five-qubit linear coupling map. Implements all core and QPU session functions, exposes superconducting qubit and operation handles, and executes submitted OpenQASM circuits with a trivial simulator.
provider/	core, "provider"	A provider that manages two instances of the example QPU. Loads them as dynamic libraries at runtime using the library_wrapper utility, and returns their QDMI_Core_Interface* and QDMI_Context through the provider module.
orchestration_layer/	core, "provider", "ol"	An orchestration layer that extends the provider by also accepting job submissions. Routes each job to the target QPU specified via QDMI_job_set_device, simulating a remote software stack.

Additionally, src/v1/ contains a legacy v1 device, and src/adapter/ provides a v1→v2 adapter that wraps any v1 device behind the new v2 interface, demonstrating a backwards-compatible migration path.