`device.h`¶

group QDMI Device Interface

Describes the functions to be implemented by a device or backend to be used with QDMI.

This is an interface between the QDMI driver and the device. It includes functions to initialize and finalize a device, as well as to manage sessions between a QDMI driver and a device, query properties of the device, and submit jobs to the device.

The device interface is split into three parts:

The device session interface for managing sessions between a QDMI driver and a device.
The device query interface for querying properties of the device.
The device job interface for submitting jobs to the device.

Functions

int IQM_QDMI_device_initialize(void)¶

Initialize a device.

A device can expect that this function is called exactly once in the beginning and has returned before any other functions are invoked on that device.

Returns:: QDMI_SUCCESS if the device was initialized successfully.
Returns:: QDMI_ERROR_FATAL if an unexpected error occurred.

int IQM_QDMI_device_finalize(void)¶

Finalize a device.

A device can expect that this function is called exactly once at the end of using the device, and no other functions are invoked on that device afterward.

Returns:: QDMI_SUCCESS if the device was finalized successfully.
Returns:: QDMI_ERROR_FATAL if the finalization failed, this could, for example, be due to a job that is still running.

group QDMI Device Session Interface

Provides functions to manage sessions between the driver and device.

A device session is a connection between a driver and a device that allows the driver to interact with the device. Sessions are used to authenticate with the device and to manage resources required for the interaction with the device.

The typical workflow for a device session is as follows:

Allocate a session with IQM_QDMI_device_session_alloc.
Set parameters for the session with IQM_QDMI_device_session_set_parameter.
Initialize the session with IQM_QDMI_device_session_init.
Run code to interact with the device using the device query interface and the device job interface.
Free the session with IQM_QDMI_device_session_free when it is no longer needed.

Typedefs

typedef struct IQM_QDMI_Device_Session_impl_d *IQM_QDMI_Device_Session¶

A handle for a device session.

An opaque pointer to a type defined by the device that encapsulates all information about a session between a driver and a device.

Functions

int IQM_QDMI_device_session_alloc(IQM_QDMI_Device_Session *session)¶

Allocate a new device session.

This is the main entry point for a driver to establish a session with a device. The returned handle can be used throughout the device session interface to refer to the session.

Parameters:: session – [out] A handle to the session that is allocated. Must not be NULL. The session must be freed by calling IQM_QDMI_device_session_free when it is no longer used.
Returns:: QDMI_SUCCESS if the session was allocated successfully.
Returns:: QDMI_ERROR_INVALIDARGUMENT if session is NULL.
Returns:: QDMI_ERROR_OUTOFMEM if memory space ran out.
Returns:: QDMI_ERROR_FATAL if an unexpected error occurred.

int IQM_QDMI_device_session_set_parameter(IQM_QDMI_Device_Session session, QDMI_Device_Session_Parameter param, size_t size, const void *value)¶

Set a parameter for a device session.

See also

IQM_QDMI_device_session_init

Note

By calling this function with value set to NULL, the function can be used to check if the device supports the specified parameter without setting a value.

For example, to check whether the device supports setting a token for authentication, the following code pattern can be used:

// Check if the device supports setting a token.
auto ret = IQM_QDMI_device_session_set_parameter(
  session, QDMI_DEVICE_SESSION_PARAMETER_TOKEN, 0, nullptr);
if (ret == QDMI_ERROR_NOTSUPPORTED) {
  // The device does not support setting a token.
  ...
}

// Set the token.
std::string token = "token";
ret = IQM_QDMI_device_session_set_parameter(
  session, QDMI_DEVICE_SESSION_PARAMETER_TOKEN, token.size() + 1,
  token.c_str());

Parameters:

session – [in] A handle to the session to set the parameter for. Must not be NULL.
param – [in] The parameter to set. Must be one of the values specified for QDMI_Device_Session_Parameter.
size – [in] The size of the data pointed by value in bytes. Must not be zero, except when value is NULL, in which case it is ignored.
value – [in] A pointer to the memory location that contains the value of the parameter to be set. The data pointed to by value is copied and can be safely reused after this function returns. If this is NULL, it is ignored.

Returns:

QDMI_SUCCESS if the device supports the specified QDMI_Device_Session_Parameter and, when value is not NULL, the value of the parameter was set successfully.

Returns:

QDMI_ERROR_NOTSUPPORTED if the device does not support the parameter or the value of the parameter.

Returns:

QDMI_ERROR_INVALIDARGUMENT if

session is NULL,
param is invalid, or
value is not NULL and size is zero or not the expected size for the parameter (if specified by the QDMI_Device_Session_Parameter documentation).

Returns:

QDMI_ERROR_BADSTATE if the parameter cannot be set in the current state of the session, for example, because the session is already initialized.

Returns:

QDMI_ERROR_FATAL if an unexpected error occurred.

int IQM_QDMI_device_session_init(IQM_QDMI_Device_Session session)¶

Initialize a device session.

This function initializes the device session and prepares it for use. The session must be initialized before it can be used as part of the device query interface or the device job interface. If a device requires authentication, the required authentication information must be set using IQM_QDMI_device_session_set_parameter before calling this function. A session may only be successfully initialized once.

Parameters:: session – [in] The session to initialize. Must not be NULL.
Returns:: QDMI_SUCCESS if the session was initialized successfully.
Returns:: QDMI_ERROR_PERMISSIONDENIED if the session could not be initialized due to missing permissions. This could be due to missing authentication information that should be set using IQM_QDMI_device_session_set_parameter.
Returns:: QDMI_ERROR_INVALIDARGUMENT if session is NULL.
Returns:: QDMI_ERROR_BADSTATE if the session is not in a state allowing initialization, for example, because the session is already initialized.
Returns:: QDMI_ERROR_FATAL if an unexpected error occurred.

void IQM_QDMI_device_session_free(IQM_QDMI_Device_Session session)¶

Free a QDMI device session.

This function frees the memory allocated for the session. Using a session handle after it was freed is undefined behavior.

Parameters:: session – [in] The session to free.

group QDMI Device Query Interface

Provides functions to query properties of a device.

The query interface enables to query static and dynamic properties of a device and its constituents in a unified fashion. It operates on IQM_QDMI_Device_Session handles created via the device session interface.

Functions

int IQM_QDMI_device_session_query_device_property(IQM_QDMI_Device_Session session, QDMI_Device_Property prop, size_t size, void *value, size_t *size_ret)¶

Query a device property.

Attention: May only be called after the session has been initialized with IQM_QDMI_device_session_init.

Note

By calling this function with value set to NULL, the function can be used to check if the device supports the specified property without retrieving the property and without the need to provide a buffer for it. Additionally, the size of the buffer needed to retrieve the property is returned in size_ret if size_ret is not NULL.

For example, to query the name of a device implementation, the following code pattern can be used:

// Query the size of the property.
size_t size;
IQM_QDMI_device_session_query_device_property(
  session, QDMI_DEVICE_PROPERTY_NAME, 0, nullptr, &size);

// Allocate memory for the property.
auto name = std::string(size - 1, '\0');

// Query the property.
IQM_QDMI_device_session_query_device_property(
  session, QDMI_DEVICE_PROPERTY_NAME, size, name.data(), nullptr);

Parameters:

session – [in] The session used for the query. Must not be NULL.
prop – [in] The property to query. Must be one of the values specified for QDMI_Device_Property.
size – [in] The size of the memory pointed to by value in bytes. Must be greater or equal to the size of the return type specified for prop, except when value is NULL, in which case it is ignored.
value – [out] A pointer to the memory location where the value of the property will be stored. If this is NULL, it is ignored.
size_ret – [out] The actual size of the data being queried in bytes. If this is NULL, it is ignored.

Returns:

QDMI_SUCCESS if the device supports the specified property and, when value is not NULL, the property was successfully retrieved.

Returns:

QDMI_ERROR_NOTSUPPORTED if the device does not support the property.

Returns:

QDMI_ERROR_INVALIDARGUMENT if

session is NULL,
prop is invalid, or
value is not NULL and size is less than the size of the data being queried.

Returns:

QDMI_ERROR_BADSTATE if the property cannot be queried in the current state of the session, for example, because the session is not initialized.

Returns:

QDMI_ERROR_FATAL if an unexpected error occurred.

int IQM_QDMI_device_session_query_site_property(IQM_QDMI_Device_Session session, IQM_QDMI_Site site, QDMI_Site_Property prop, size_t size, void *value, size_t *size_ret)¶

Query a site property.

Attention: May only be called after the session has been initialized with IQM_QDMI_device_session_init.

Note

For example, to query the T1 time of a site, the following code pattern can be used:

// Check if the device supports the property.
auto ret = IQM_QDMI_device_session_query_site_property(
  session, site, QDMI_SITE_PROPERTY_T1, 0, nullptr, nullptr);
if (ret == QDMI_ERROR_NOTSUPPORTED) {
  // The device does not support the property.
  ...
}

// Query the property.
uint64_t t1;
IQM_QDMI_device_session_query_site_property(
  session, site, QDMI_SITE_PROPERTY_T1, sizeof(uint64_t), &t1, nullptr);

Parameters:

session – [in] The session used for the query. Must not be NULL.
site – [in] The site to query. Must not be NULL.
prop – [in] The property to query. Must be one of the values specified for QDMI_Site_Property.
size – [in] The size of the memory pointed to by value in bytes. Must be greater or equal to the size of the return type specified for prop, except when value is NULL, in which case it is ignored.
value – [out] A pointer to the memory location where the value of the property will be stored. If this is NULL, it is ignored.
size_ret – [out] The actual size of the data being queried in bytes. If this is NULL, it is ignored.

Returns:

QDMI_SUCCESS if the device supports the specified property and, when value is not NULL, the property was successfully retrieved.

Returns:

QDMI_ERROR_NOTSUPPORTED if the device does not support the property.

Returns:

QDMI_ERROR_INVALIDARGUMENT if

session or site is NULL,
prop is invalid, or
value is not NULL and size is less than the size of the data being queried.

Returns:

QDMI_ERROR_BADSTATE if the property cannot be queried in the current state of the session, for example, because the session is not initialized.

Returns:

QDMI_ERROR_FATAL if an unexpected error occurred.

int IQM_QDMI_device_session_query_operation_property(IQM_QDMI_Device_Session session, IQM_QDMI_Operation operation, size_t num_sites, const IQM_QDMI_Site *sites, size_t num_params, const double *params, QDMI_Operation_Property prop, size_t size, void *value, size_t *size_ret)¶

Query an operation property.

Attention: May only be called after the session has been initialized with IQM_QDMI_device_session_init.

Note

By calling this function with sites set to NULL, the function can be used to query properties of the device that are independent of the sites. A device will return QDMI_ERROR_NOTSUPPORTED if the queried property is site-dependent and sites is NULL.

By calling this function with params set to NULL, the function can be used to query properties of the device that are independent of the values of the parameters. A device will return QDMI_ERROR_NOTSUPPORTED if the queried property is parameter-dependent and params is NULL.

For example, to query the site-independent fidelity of an operation without parameters, the following code snippet can be used:

// Check if the device supports the property.
auto ret = IQM_QDMI_device_session_query_operation_property(
  session, operation, 0, nullptr, 0, nullptr,
  QDMI_OPERATION_PROPERTY_FIDELITY, 0, nullptr, nullptr);
if (ret == QDMI_ERROR_NOTSUPPORTED) {
  // The device does not support the site-independent property.
  // Check if the device supports the site-dependent property.
  ...
}

// Query the property.
double fidelity;
IQM_QDMI_device_session_query_operation_property(
  session, operation, 0, nullptr, 0, nullptr,
  QDMI_OPERATION_PROPERTY_FIDELITY, sizeof(double), &fidelity, nullptr);

Parameters:

session – [in] The session used for the query. Must not be NULL.
operation – [in] The operation to query. Must not be NULL.
num_sites – [in] The number of sites that the operation is applied to.
sites – [in] A pointer to a list of handles where the sites that the operation is applied to are stored. If this is NULL, it is ignored.
num_params – [in] The number of parameters that the operation takes.
params – [in] A pointer to a list of parameters the operation takes. If this is NULL, it is ignored.
prop – [in] The property to query. Must be one of the values specified for QDMI_Operation_Property.
size – [in] The size of the memory pointed to by value in bytes. Must be greater or equal to the size of the return type specified for the QDMI_Operation_Property prop, except when value is NULL, in which case it is ignored.
value – [out] A pointer to the memory location where the value of the property will be stored. If this is NULL, it is ignored.
size_ret – [out] The actual size of the data being queried in bytes. If this is NULL, it is ignored.

Returns:

QDMI_SUCCESS if the device supports the specified property and, when value is not NULL, the property was successfully retrieved.

Returns:

QDMI_ERROR_NOTSUPPORTED if the property is not supported by the device or if the queried property cannot be provided for the given sites or parameters.

Returns:

QDMI_ERROR_INVALIDARGUMENT if

session or operation are NULL,
prop is invalid, or
value is not NULL and size is less than the size of the data being queried.

Returns:

QDMI_ERROR_BADSTATE if the property cannot be queried in the current state of the session, for example, because the session is not initialized.

Returns:

QDMI_ERROR_FATAL if an unexpected error occurred.

group QDMI Device Job Interface

Provides functions to manage jobs on a device.

A job is a task submitted to a device for execution. Most jobs are quantum circuits to be executed on a quantum device. However, jobs can also be a different type of task, such as calibration.

The typical workflow for a device job is as follows:

Create a job with IQM_QDMI_device_session_create_device_job.
Set parameters for the job with IQM_QDMI_device_job_set_parameter.
Submit the job with IQM_QDMI_device_job_submit.
Check the status of the job with IQM_QDMI_device_job_check.
Wait for the job to finish with IQM_QDMI_device_job_wait.
Retrieve the results of the job with IQM_QDMI_device_job_get_results.
Free the job with IQM_QDMI_device_job_free when it is no longer used.

Typedefs

typedef struct IQM_QDMI_Device_Job_impl_d *IQM_QDMI_Device_Job¶

A handle for a device job.

An opaque pointer to a type defined by the device that encapsulates all information about a job on a device.

Remark

Implementations of the underlying type will want to store the session handle used to create the job in the job handle to be able to access the session information when needed.

See also

QDMI_Job for the client-side job handle.

Functions

int IQM_QDMI_device_session_create_device_job(IQM_QDMI_Device_Session session, IQM_QDMI_Device_Job *job)¶

Create a job.

This is the main entry point for a driver to create a job for a device. The returned handle can be used throughout the device job interface to refer to the job.

Attention: May only be called after the session has been initialized with IQM_QDMI_device_session_init.

Parameters:

session – [in] The session to create the job on. Must not be NULL.
job – [out] A pointer to a handle that will store the created job. Must not be NULL. The job must be freed by calling IQM_QDMI_device_job_free when it is no longer used.

Returns:

QDMI_SUCCESS if the job was successfully created.

Returns:

QDMI_ERROR_INVALIDARGUMENT if session or job are NULL.

Returns:

QDMI_ERROR_BADSTATE if the session is not in a state allowing the creation of a job, for example, because the session is not initialized.

Returns:

QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.

Returns:

QDMI_ERROR_FATAL if job creation failed due to a fatal error.

int IQM_QDMI_device_job_set_parameter(IQM_QDMI_Device_Job job, QDMI_Device_Job_Parameter param, size_t size, const void *value)¶

Set a parameter for a job.

Note

By calling this function with value set to NULL, the function can be used to check if the device supports the specified parameter without setting the parameter and without the need to provide a value.

For example, to check whether the device supports setting the number of shots for a quantum circuit job, the following code pattern can be used:

// Check if the device supports setting the number of shots.
auto ret = IQM_QDMI_device_job_set_parameter(
  job, QDMI_DEVICE_JOB_PARAMETER_SHOTSNUM, 0, nullptr);
if (ret == QDMI_ERROR_NOTSUPPORTED) {
  // The device does not support setting the number of shots.
  ...
}

// Set the number of shots.
size_t shots = 8192;
IQM_QDMI_device_job_set_parameter(
  job, QDMI_DEVICE_JOB_PARAMETER_SHOTSNUM, sizeof(size_t), &shots);

Parameters:

job – [in] A handle to a job for which to set param. Must not be NULL.
param – [in] The parameter whose value will be set. Must be one of the values specified for QDMI_Device_Job_Parameter.
size – [in] The size of the data pointed to by value in bytes. Must not be zero, except when value is NULL, in which case it is ignored.
value – [in] A pointer to the memory location that contains the value of the parameter to be set. The data pointed to by value is copied and can be safely reused after this function returns. If this is NULL, it is ignored.

Returns:

QDMI_SUCCESS if the device supports the specified QDMI_Device_Job_Parameter param and, when value is not NULL, the parameter was successfully set.

Returns:

QDMI_ERROR_NOTSUPPORTED if the device does not support the parameter or the value of the parameter.

Returns:

QDMI_ERROR_INVALIDARGUMENT if

job is NULL,
param is invalid, or
value is not NULL and size is zero or not the expected size for the parameter (if specified by the QDMI_Device_Job_Parameter documentation).

Returns:

QDMI_ERROR_BADSTATE if the parameter cannot be set in the current state of the job, for example, because the job is already submitted.

Returns:

QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.

Returns:

QDMI_ERROR_FATAL if setting the parameter failed due to a fatal error.

int IQM_QDMI_device_job_query_property(IQM_QDMI_Device_Job job, QDMI_Device_Job_Property prop, size_t size, void *value, size_t *size_ret)¶

Query a job property.

Note

By calling this function with value set to NULL, the function can be used to check if the job supports the specified property without retrieving the property and without the need to provide a buffer for it. Additionally, the size of the buffer needed to retrieve the property is returned in size_ret if size_ret is not NULL.

For example, to query the ID of a job, the following code pattern can be used:

// Query the size of the property.
size_t size;
IQM_QDMI_device_job_query_property(
  job, QDMI_DEVICE_JOB_PROPERTY_ID, 0, nullptr, &size);

// Allocate memory for the property.
auto id = std::string(size - 1, '\0');

// Query the property.
IQM_QDMI_device_job_query_property(
  job, QDMI_DEVICE_JOB_PROPERTY_ID, size, id.data(), nullptr);

Parameters:

job – [in] A handle to a job for which to query prop. Must not be NULL.
prop – [in] The property to query. Must be one of the values specified for QDMI_Device_Job_Property.
size – [in] The size of the memory pointed to by value in bytes. Must be greater or equal to the size of the return type specified for prop, except when value is NULL, in which case it is ignored.
value – [out] A pointer to the memory location where the value of the property will be stored. If this is NULL, it is ignored.
size_ret – [out] The actual size of the data being queried in bytes. If this is NULL, it is ignored.

Returns:

QDMI_SUCCESS if the job supports the specified property and, when value is not NULL, the property was successfully retrieved.

Returns:

QDMI_ERROR_NOTSUPPORTED if the job does not support the property.

Returns:

QDMI_ERROR_INVALIDARGUMENT if

job is NULL,
prop is invalid, or
value is not NULL and size is less than the size of the data being queried.

Returns:

QDMI_ERROR_BADSTATE if the property cannot be queried in the current state of the job, for example, because the job failed or the property is not initialized because it has no default value and was not set.

Returns:

QDMI_ERROR_FATAL if an unexpected error occurred.

int IQM_QDMI_device_job_submit(IQM_QDMI_Device_Job job)¶

Submit a job to the device.

This function can either be blocking until the job is finished or non-blocking and return while the job is running. In the latter case, the functions IQM_QDMI_device_job_check and IQM_QDMI_device_job_wait can be used to check the status and wait for the job to finish.

Parameters:: job – [in] The job to submit. Must not be NULL.
Returns:: QDMI_SUCCESS if the job was successfully submitted.
Returns:: QDMI_ERROR_INVALIDARGUMENT if job is NULL.
Returns:: QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.
Returns:: QDMI_ERROR_FATAL if the job submission failed.

int IQM_QDMI_device_job_cancel(IQM_QDMI_Device_Job job)¶

Cancel an already submitted job.

Remove the job from the queue of waiting jobs. This changes the status of the job to QDMI_JOB_STATUS_CANCELED.

Parameters:: job – [in] The job to cancel. Must not be NULL.
Returns:: QDMI_SUCCESS if the job was successfully canceled.
Returns:: QDMI_ERROR_INVALIDARGUMENT if job is NULL or the job already has the status QDMI_JOB_STATUS_DONE.
Returns:: QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.
Returns:: QDMI_ERROR_FATAL if the job could not be canceled.

int IQM_QDMI_device_job_check(IQM_QDMI_Device_Job job, QDMI_Job_Status *status)¶

Check the status of a job.

This function is non-blocking and returns immediately with the job status. It is not required to call this function before calling IQM_QDMI_device_job_get_results.

Parameters:

job – [in] The job to check the status of. Must not be NULL.
status – [out] The status of the job. Must not be NULL.

Returns:

QDMI_SUCCESS if the job status was successfully checked.

Returns:

QDMI_ERROR_INVALIDARGUMENT if job or status is NULL.

Returns:

QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.

Returns:

QDMI_ERROR_FATAL if the job status could not be checked.

int IQM_QDMI_device_job_wait(IQM_QDMI_Device_Job job, size_t timeout)¶

Wait for a job to finish.

This function blocks until the job has either finished, has been canceled, or the timeout has been reached. If timeout is not zero, this function returns latest after the specified number of seconds.

Parameters:

job – [in] The job to wait for. Must not be NULL.
timeout – [in] The timeout in seconds. If this is zero, the function waits indefinitely until the job has finished.

Returns:

QDMI_SUCCESS if the job is finished or canceled.

Returns:

QDMI_ERROR_INVALIDARGUMENT if job is NULL.

Returns:

QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.

Returns:

QDMI_ERROR_TIMEOUT if timeout is not zero and the job did not finish within the specified time.

Returns:

QDMI_ERROR_FATAL if the job could not be waited for and this function returns before the job has finished or has been canceled.

int IQM_QDMI_device_job_get_results(IQM_QDMI_Device_Job job, QDMI_Job_Result result, size_t size, void *data, size_t *size_ret)¶

Retrieve the results of a job.

Note

By calling this function with data set to NULL, the function can be used to check if the device supports the specified result without retrieving the result and without the need to provide a buffer for the result. Additionally, the size of the buffer needed to retrieve the result is returned in size_ret if size_ret is not NULL.

For example, to query the measurement results of a quantum circuit job, the following code pattern can be used:

// Query the size of the result.
size_t size;
auto ret = IQM_QDMI_device_job_get_results(
  job, QDMI_JOB_RESULT_SHOTS, 0, nullptr, &size);

// Allocate memory for the result.
std::string shots(size - 1, '\0');

// Query the result.
IQM_QDMI_device_job_get_results(
  job, QDMI_JOB_RESULT_SHOTS, size, shots.data(), nullptr);

Parameters:

job – [in] The job to retrieve the results from. Must not be NULL.
result – [in] The result to retrieve. Must be one of the values specified for QDMI_Job_Result.
size – [in] The size of the buffer pointed to by data in bytes. Must be greater or equal to the size of the return type specified for the QDMI_Job_Result result, except when data is NULL, in which case it is ignored.
data – [out] A pointer to the memory location where the results will be stored. If this is NULL, it is ignored.
size_ret – [out] The actual size of the data being queried in bytes. If this is NULL, it is ignored.

Returns:

QDMI_SUCCESS if the device supports the specified result and, when data is not NULL, the results were successfully retrieved.

Returns:

QDMI_ERROR_INVALIDARGUMENT if

job is NULL,
job has not finished,
job was canceled,
result is invalid, or
data is not NULL and size is smaller than the size of the data being queried.

Returns:

QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.

Returns:

QDMI_ERROR_FATAL if an error occurred during the retrieval.

void IQM_QDMI_device_job_free(IQM_QDMI_Device_Job job)¶

Free a job.

Free the resources associated with a job. Using a job handle after it was freed is undefined behavior.

Parameters:: job – [in] The job to free.

device.h¶

`device.h`¶