MQT Core’s QDMI Driver Implementation

Objective

A QDMI Driver manages the communication between QDMI devices, such as MQT Core’s SC QDMI Device or MQT Core’s DDSIM QDMI Device, and QDMI clients, see the QDMI specification. It is responsible for loading the device, forwarding requests from the client to the device, and sending back the results. MQT Core’s QDMI Driver, qdmi::Driver, comes with several preloaded devices when the bundled devices are enabled. Other devices can be loaded dynamically at runtime via qdmi::Driver::registerDevice and qdmi::Driver::open. Built-in and external devices can also be registered through versioned QDMI device configuration.

The driver shares a loaded provider across path aliases with the same symbol prefix and retains it for the process lifetime. Closing a device session frees that session without finalizing the provider while another session may use it. Initialization is serialized within each loaded module. A slow provider initializer does not hold the driver cache lock while other modules are opened.

Building the Bundled Devices

Standalone MQT Core builds include the DDSIM and superconducting QDMI device libraries by default. When MQT Core is embedded in another CMake project using FetchContent or add_subdirectory, these device libraries are disabled by default so the consumer does not build implementations it may not use. They can be selected independently before making MQT Core available:

  • BUILD_MQT_CORE_QDMI_DDSIM_DEVICE

  • BUILD_MQT_CORE_QDMI_SC_DEVICE

The DDSIM device uses the MLIR compiler infrastructure for both OpenQASM and QIR programs. Its target is skipped when BUILD_MQT_CORE_MLIR is OFF, while the QDMI driver and superconducting device remain available.

For example, an embedded simulator consumer can enable only the DDSIM device, while CUDA-Q can enable the DDSIM and superconducting devices used by its integration tests.

The QDMI driver and QDMI libraries are available independently. Device-free builds can register external device libraries through QDMI device configuration. C++ test builds require every bundled device available in the selected build configuration.

Python Bindings

The QDMI interface is the low-level contract implemented by a QDMI device. The MQT Core QDMI driver loads device libraries and implements the QDMI client interface. The C++ QDMI library adds owning wrappers for QDMI devices, sites, operations, and jobs. The Python module exposes these QDMI entities through mqt.core.qdmi. Its mqt.core.qdmi.driver submodule provides device discovery, registration, and opening.

Native device opening, property queries, job calls, and compiler-target snapshots release Python’s GIL. Other Python threads can run while a provider waits for a remote response. Python argument and result conversion still holds the GIL. Concurrent calls into a shared device or job must satisfy the provider’s thread safety contract; releasing the GIL does not serialize provider access.

Usage

The following example opens each registered device by its stable ID.

1from mqt.core.qdmi.driver import open_device, registered_device_ids
2
3for device_id in registered_device_ids():
4    device = open_device(device_id)
5    print(device.name())

MQT Core DDSIM QDMI Device