Namespace qdmi

namespace qdmi

Typedefs

using DeviceConfigurationSource = std::variant<InlineDeviceConfiguration, FileDeviceConfiguration>

One replaceable source for a runtime device description.

Enums

enum class SessionStatus : uint8_t

The status of a session.

This enum defines the possible states of a session in the QDMI library. A session can be either allocated or initialized.

Values:

enumerator ALLOCATED

The session has been allocated but not initialized.

enumerator INITIALIZED

The session has been initialized and is ready for use.

Functions

inline void unreachable()

Function used to mark unreachable code.

Uses compiler-specific extensions if possible. Even if no extension is used, undefined behavior is still raised by an empty function body and the noreturn attribute.

constexpr auto toString(const QDMI_STATUS result) -> const char*

Returns the string representation of the given status code result.

auto throwIfError(int result, const std::string &msg) -> void

Throws an exception if the result indicates an error.

Parameters:

• result – The result of a QDMI operation

• msg – The error message to include in the exception

Throws:

• std::bad_alloc – if the result is QDMI_ERROR_OUTOFMEM

• std::out_of_range – if the result is QDMI_ERROR_OUTOFRANGE

• std::invalid_argument – if the result is QDMI_ERROR_INVALIDARGUMENT

• std::runtime_error – for all other error results

constexpr auto toString(const QDMI_Session_Parameter param) -> const char*

Returns the string representation of the given session parameter param.

constexpr auto toString(const QDMI_Session_Property prop) -> const char*

Returns the string representation of the given session property prop.

constexpr auto toString(const QDMI_Device_Session_Parameter param) -> const char*

Returns the string representation of the given device session parameter param.

constexpr auto toString(const QDMI_Site_Property prop) -> const char*

Returns the string representation of the given site property prop.

constexpr auto toString(const QDMI_Operation_Property prop) -> const char*

Returns the string representation of the given operation property prop.

constexpr auto toString(const QDMI_Device_Property prop) -> const char*

Returns the string representation of the given device property prop.

struct DeviceDefinition

#include <Driver.hpp>

Stable registration for a QDMI device.

Registration records this metadata without loading the native library. Use Driver::open to create the corresponding device session.

Public Members

std::string id

Stable identifier used to open this device.

std::filesystem::path library

Path to the native QDMI device library.

std::string prefix

Prefix used for the QDMI device interface functions.

DeviceSessionConfig session

Parameters applied before the device session is initialized.

struct DeviceLibrary

#include <Driver.hpp>

Definition of the device library.

The device library contains function pointers to the QDMI device interface functions.

Subclassed by qdmi::DynamicDeviceLibrary

Public Members

decltype(QDMI_device_initialize) *device_initialize = {}

Function pointer to QDMI_device_initialize.

decltype(QDMI_device_finalize) *device_finalize = {}

Function pointer to QDMI_device_finalize.

decltype(QDMI_device_session_alloc) *device_session_alloc = {}

Function pointer to QDMI_device_session_alloc.

decltype(QDMI_device_session_init) *device_session_init = {}

Function pointer to QDMI_device_session_init.

decltype(QDMI_device_session_free) *device_session_free = {}

Function pointer to QDMI_device_session_free.

decltype(QDMI_device_session_set_parameter) *device_session_set_parameter = {}

Function pointer to QDMI_device_session_set_parameter.

decltype(QDMI_device_session_create_device_job) *device_session_create_device_job = {}

Function pointer to QDMI_device_session_create_device_job.

decltype(QDMI_device_session_retrieve_device_job_by_id) *device_session_retrieve_device_job_by_id = {}

Function pointer to QDMI_device_session_retrieve_device_job_by_id.

decltype(QDMI_device_job_free) *device_job_free = {}

Function pointer to QDMI_device_job_free.

decltype(QDMI_device_job_set_parameter) *device_job_set_parameter = {}

Function pointer to QDMI_device_job_set_parameter.

decltype(QDMI_device_job_query_property) *device_job_query_property = {}

Function pointer to QDMI_device_job_query_property.

decltype(QDMI_device_job_submit) *device_job_submit = {}

Function pointer to QDMI_device_job_submit.

decltype(QDMI_device_job_cancel) *device_job_cancel = {}

Function pointer to QDMI_device_job_cancel.

decltype(QDMI_device_job_check) *device_job_check = {}

Function pointer to QDMI_device_job_check.

decltype(QDMI_device_job_wait) *device_job_wait = {}

Function pointer to QDMI_device_job_wait.

decltype(QDMI_device_job_get_results) *device_job_get_results = {}

Function pointer to QDMI_device_job_get_results.

decltype(QDMI_device_session_query_device_property) *device_session_query_device_property = {}

Function pointer to QDMI_device_session_query_device_property.

decltype(QDMI_device_session_query_site_property) *device_session_query_site_property = {}

Function pointer to QDMI_device_session_query_site_property.

decltype(QDMI_device_session_query_operation_property) *device_session_query_operation_property = {}

Function pointer to QDMI_device_session_query_operation_property.

struct DeviceSessionConfig

#include <Driver.hpp>

Configuration for device session parameters.

This struct holds optional parameters that can be set on a device session before initialization. All parameters are optional.

Public Members

std::optional<std::string> baseUrl

Base URL for API endpoint.

std::optional<std::string> token

Authentication token.

std::optional<std::filesystem::path> authFile

Path to file containing authentication information.

std::optional<std::string> authUrl

URL to authentication server.

std::optional<std::string> username

Username for authentication.

std::optional<std::string> password

Password for authentication.

std::optional<DeviceConfigurationSource> deviceConfiguration

Typed runtime device-description source.

std::optional<std::string> custom1

Custom configuration parameter 1.

std::optional<std::string> custom2

Custom configuration parameter 2.

std::optional<std::string> custom3

Custom configuration parameter 3.

std::optional<std::string> custom4

Custom configuration parameter 4.

std::optional<std::string> custom5

Custom configuration parameter 5.

class Driver : public qdmi::Singleton<Driver>

#include <Driver.hpp>

The MQT QDMI driver class.

This driver discovers configured QDMI device definitions and opens their libraries. Additional definitions can be registered at runtime.

Note

This class is a singleton that manages the QDMI libraries and sessions. It is responsible for loading the libraries, allocating sessions, and providing access to the devices.

Public Functions

void registerDevice(DeviceDefinition definition, bool replace = false)

Registers a device definition without loading its library.

Parameters:

• definition – The definition to validate and store.

• replace – Whether an existing unopened definition may be replaced.

Throws:

• std::invalid_argument – If the definition is incomplete or its ID is already registered.

• std::runtime_error – If replacing an already opened definition.

auto registerDeviceIfAbsent(DeviceDefinition definition) -> bool

Registers a device definition unless its ID is already present.

Existing and explicitly disabled IDs are not inserted. The complete definition is validated before checking for either condition.

Parameters:

definition – The definition to validate and store.

Throws:

std::invalid_argument – If the definition is incomplete.

Returns:

Whether the definition was inserted.

auto registeredDeviceIds() const -> std::vector<std::string>

Lists the stable IDs of all registered devices.

This query includes runtime registrations and does not load device libraries or expose their definitions.

Returns:

The enabled device IDs in deterministic registration order.

auto open(std::string_view id) -> QDMI_Device

Opens the registered device with the given stable ID.

Throws:

• std::out_of_range – If the ID is unknown.

• std::runtime_error – If loading or session initialization fails.

Returns:

The existing device handle when the ID is already open.

auto sessionAlloc(QDMI_Session *session) -> int

Allocates a new session.

See also

QDMI_session_alloc

auto sessionFree(QDMI_Session session) -> void

Frees a session.

See also

QDMI_session_free

Public Static Functions

static auto get() -> Driver&

This out-of-line accessor keeps static-library consumers from instantiating separate singleton storage in different translation units.

Returns:

the process-wide Driver instance.

class DynamicDeviceLibrary : public qdmi::DeviceLibrary

#include <Driver.hpp>

Definition of the dynamic device library.

This class is used to load the QDMI device interface functions from a dynamic library at runtime. It inherits from DeviceLibrary and overrides the constructor and destructor to open and close the library.

Public Functions

DynamicDeviceLibrary(const std::string &libName, const std::string &prefix)

Constructs a DynamicDeviceLibrary object.

This constructor loads the QDMI device interface functions from the dynamic library specified by libName and prefix.

Parameters:

• libName – is the name of the dynamic library to load.

• prefix – is the prefix used for the function names in the library.

~DynamicDeviceLibrary() override

Destructor for the DynamicDeviceLibrary.

This destructor calls the QDMI_device_finalize function if it is not null and closes the dynamic library.

struct FileDeviceConfiguration

#include <Driver.hpp>

JSON file used to configure one QDMI device session.

struct InlineDeviceConfiguration

#include <Driver.hpp>

Inline JSON used to configure one QDMI device session.

template<class Concrete>
class Singleton

Public Functions

virtual ~Singleton() = default

Virtual destructor for the Singleton base class.

Public Static Functions

static inline auto get() -> Concrete&

Returns:

the singleton instance of the derived class.

namespace dd

class Device : public qdmi::Singleton<Device>

Public Functions

auto sessionAlloc(MQT_DDSIM_QDMI_Device_Session *session) -> QDMI_STATUS

Allocates a new device session.

See also

MQT_DDSIM_QDMI_device_session_alloc

auto sessionFree(MQT_DDSIM_QDMI_Device_Session session) -> void

Frees a device session.

See also

MQT_DDSIM_QDMI_device_session_free

auto queryProperty(QDMI_Device_Property prop, size_t size, void *value, size_t *sizeRet) const -> QDMI_STATUS

Query a device property.

See also

MQT_DDSIM_QDMI_device_session_query_device_property

auto generateUniqueID() -> int

Generates a unique ID.

auto setStatus(QDMI_Device_Status status) -> void

Sets the device status.

auto increaseRunningJobs() -> void

Bumps the number of running jobs and updates the status.

auto decreaseRunningJobs() -> void

Decreases the number of running jobs and updates the status.

namespace detail

Functions

int setDeviceConfigurationParameter(QDMI_Device_Session_Parameter parameter, size_t size, const void *value, std::optional<std::string> &inlineJson, std::optional<std::filesystem::path> &file)

Validate and store a CUSTOM1/CUSTOM2 string parameter.

A null value with size zero is a capability probe. Assignments contain one trailing NUL and no embedded NUL. A single NUL clears the selected value.

std::optional<LoadedDeviceConfiguration> loadDeviceConfiguration(const std::optional<std::string> &inlineJson, const std::optional<std::filesystem::path> &file, std::string_view inlineEnvironment, std::string_view fileEnvironment, std::string_view bundledFilename, const void *anchor, int &status)

Select and load one runtime device description.

A non-empty explicit inline value wins over an explicit file value. Without an explicit source, exactly one technology-specific environment variable may select inline JSON or a file. The final fallback is a file beside the shared module containing anchor.

struct LoadedDeviceConfiguration

#include <DeviceConfiguration.hpp>

JSON text selected for a provider session together with a safe source label.