C/C++ API reference ¶

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 IBM_QDMI_device_session_init(IBM_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 IBM_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 IBM_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 IBM_QDMI_device_session_free(IBM_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.

int QDMI_device_session_alloc(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 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 QDMI_device_session_set_parameter(QDMI_Device_Session session, QDMI_Device_Session_Parameter param, size_t size, const void *value)¶

Set a parameter for a device session.

See also

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 = 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 = 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:

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 QDMI_device_session_init(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 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 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 QDMI_device_session_free(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.

Device queries¶

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 IBM_QDMI_Device_Session handles created via the device session interface.

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

Functions

int IBM_QDMI_device_session_query_device_property(IBM_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 IBM_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;
IBM_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.
IBM_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:

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 IBM_QDMI_device_session_query_site_property(IBM_QDMI_Device_Session session, IBM_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 IBM_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 = IBM_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;
IBM_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:

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 IBM_QDMI_device_session_query_operation_property(IBM_QDMI_Device_Session session, IBM_QDMI_Operation operation, size_t num_sites, const IBM_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 IBM_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 = IBM_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;
IBM_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:

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.

int QDMI_device_session_query_device_property(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 QDMI_device_session_init.

Note

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;
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.
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:

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 QDMI_device_session_query_site_property(QDMI_Device_Session session, 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 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 = 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;
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:

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 QDMI_device_session_query_operation_property(QDMI_Device_Session session, QDMI_Operation operation, size_t num_sites, const 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 QDMI_device_session_init.

Note

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 = 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;
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:

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.

Device jobs¶

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 IBM_QDMI_device_session_create_device_job.
Set parameters for the job with IBM_QDMI_device_job_set_parameter.
Submit the job with IBM_QDMI_device_job_submit.
Check the status of the job with IBM_QDMI_device_job_check.
Wait for the job to finish with IBM_QDMI_device_job_wait.
Retrieve the results of the job with IBM_QDMI_device_job_get_results.
Free the job with IBM_QDMI_device_job_free when it is no longer used.

Alternatively, a driver may retrieve a previously submitted job with IBM_QDMI_device_session_retrieve_device_job_by_id and continue managing it through the same interface.

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 QDMI_device_session_create_device_job.
Set parameters for the job with QDMI_device_job_set_parameter.
Submit the job with QDMI_device_job_submit.
Check the status of the job with QDMI_device_job_check.
Wait for the job to finish with QDMI_device_job_wait.
Retrieve the results of the job with QDMI_device_job_get_results.
Free the job with QDMI_device_job_free when it is no longer used.

Alternatively, a driver may retrieve a previously submitted job with QDMI_device_session_retrieve_device_job_by_id and continue managing it through the same interface.

Typedefs

typedef struct IBM_QDMI_Device_Job_impl_d *IBM_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.

typedef struct QDMI_Device_Job_impl_d *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 IBM_QDMI_device_session_create_device_job(IBM_QDMI_Device_Session session, IBM_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 IBM_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 IBM_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 IBM_QDMI_device_session_retrieve_device_job_by_id(IBM_QDMI_Device_Session session, const char *job_id, IBM_QDMI_Device_Job *job)¶

Retrieve an existing device job by its ID.

Creates a new local device-job handle for the existing remote job identified by job_id. Retrieving a job does not submit, clone, or otherwise modify the remote job. The returned handle can be used to query properties, check or wait for completion, cancel the job, and retrieve results.

The job is accessed with the credentials and configuration of session. The job ID is an identifier, not an authentication credential. Parameters cannot be set on a retrieved job, and a retrieved job cannot be submitted again.

Parameters:

session – [in] The initialized session with which to retrieve the job. Must not be NULL.
job_id – [in] The nonempty, null-terminated ID returned by QDMI_DEVICE_JOB_PROPERTY_ID. Must not be NULL.
job – [out] A pointer to a handle that will store the retrieved job. Must not be NULL. The handle must be freed by calling IBM_QDMI_device_job_free when it is no longer used.

Returns:

QDMI_SUCCESS if the job was successfully retrieved.

Returns:

QDMI_ERROR_INVALIDARGUMENT if session, job_id, or job is NULL, or if job_id is empty.

Returns:

QDMI_ERROR_NOTSUPPORTED if the device does not support retrieving existing jobs.

Returns:

QDMI_ERROR_NOTFOUND if no accessible job with job_id exists.

Returns:

QDMI_ERROR_BADSTATE if session is not initialized.

Returns:

QDMI_ERROR_PERMISSIONDENIED if session is not permitted to access the job.

Returns:

QDMI_ERROR_FATAL if retrieving the job failed due to a fatal error.

int IBM_QDMI_device_job_set_parameter(IBM_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 = IBM_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;
IBM_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:

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 IBM_QDMI_device_job_query_property(IBM_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;
IBM_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.
IBM_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:

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 IBM_QDMI_device_job_submit(IBM_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 IBM_QDMI_device_job_check and IBM_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_BADSTATE if the job was retrieved with IBM_QDMI_device_session_retrieve_device_job_by_id.
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 IBM_QDMI_device_job_cancel(IBM_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 IBM_QDMI_device_job_check(IBM_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 IBM_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 IBM_QDMI_device_job_wait(IBM_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 IBM_QDMI_device_job_get_results(IBM_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 = IBM_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.
IBM_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:

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 IBM_QDMI_device_job_free(IBM_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. Freeing a job handle does not necessarily cancel or delete the underlying job; this behavior is device-specific.

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

int QDMI_device_session_create_device_job(QDMI_Device_Session session, 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 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 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 QDMI_device_session_retrieve_device_job_by_id(QDMI_Device_Session session, const char *job_id, QDMI_Device_Job *job)¶

Retrieve an existing device job by its ID.

Parameters:

session – [in] The initialized session with which to retrieve the job. Must not be NULL.
job_id – [in] The nonempty, null-terminated ID returned by QDMI_DEVICE_JOB_PROPERTY_ID. Must not be NULL.
job – [out] A pointer to a handle that will store the retrieved job. Must not be NULL. The handle must be freed by calling QDMI_device_job_free when it is no longer used.

Returns:

QDMI_SUCCESS if the job was successfully retrieved.

Returns:

QDMI_ERROR_INVALIDARGUMENT if session, job_id, or job is NULL, or if job_id is empty.

Returns:

QDMI_ERROR_NOTSUPPORTED if the device does not support retrieving existing jobs.

Returns:

QDMI_ERROR_NOTFOUND if no accessible job with job_id exists.

Returns:

QDMI_ERROR_BADSTATE if session is not initialized.

Returns:

QDMI_ERROR_PERMISSIONDENIED if session is not permitted to access the job.

Returns:

QDMI_ERROR_FATAL if retrieving the job failed due to a fatal error.

int QDMI_device_job_set_parameter(QDMI_Device_Job job, QDMI_Device_Job_Parameter param, size_t size, const void *value)¶

Set a parameter for a job.

Note

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 = 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;
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:

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 QDMI_device_job_query_property(QDMI_Device_Job job, QDMI_Device_Job_Property prop, size_t size, void *value, size_t *size_ret)¶

Query a job property.

Note

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;
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.
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:

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_FATAL if an unexpected error occurred.

int QDMI_device_job_submit(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 QDMI_device_job_check and 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_BADSTATE if the job was retrieved with QDMI_device_session_retrieve_device_job_by_id.
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 QDMI_device_job_cancel(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 QDMI_device_job_check(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 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 QDMI_device_job_wait(QDMI_Device_Job job, size_t timeout)¶

Wait for a job to finish.

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 QDMI_device_job_get_results(QDMI_Device_Job job, QDMI_Job_Result result, size_t size, void *data, size_t *size_ret)¶

Retrieve the results of a job.

Note

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 = 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.
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:

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 QDMI_device_job_free(QDMI_Device_Job job)¶

Free a job.

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

Client lifecycle¶

group QDMI Client Interface

Describes the functions accessible to clients or users of QDMI.

This is an interface between the QDMI driver and the client. It includes functions to establish sessions between a QDMI driver and a client, as well as to interact with the devices managed by the driver.

The client interface is split into three parts:

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

Typedefs

typedef struct QDMI_Device_impl_d *QDMI_Device¶

A handle for a device implementing the QDMI Device Interface.

An opaque pointer to a type defined by the driver that encapsulates an implementation of the QDMI Device Interface.

Client sessions¶

group QDMI Client Session Interface

Provides functions to manage sessions between the client and driver.

A session is a connection between a client and a QDMI driver that allows the client to interact with the driver and the devices it manages.

The typical workflow for a client session is as follows:

Allocate a session with QDMI_session_alloc.
Set parameters for the session with QDMI_session_set_parameter.
Initialize the session with QDMI_session_init.
Query the available devices with QDMI_session_query_session_property.
Run client code to interact with the retrieved QDMI_Device handles using the client query interface and the client job interface.
Free the session with QDMI_session_free when it is no longer needed.

Typedefs

typedef struct QDMI_Session_impl_d *QDMI_Session¶

A handle for a session.

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

typedef enum QDMI_SESSION_PARAMETER_T QDMI_Session_Parameter¶: Session parameter type.

typedef enum QDMI_SESSION_PROPERTY_T QDMI_Session_Property¶: Session property type.

Enums

enum QDMI_SESSION_PARAMETER_T¶

Enum of the session parameters that can be set via QDMI_session_set_parameter.

If not noted otherwise, parameters are optional and drivers must not require them to be set.

Values:

enumerator QDMI_SESSION_PARAMETER_TOKEN¶

char* (string) The token to use for the session.

The token is used for authentication within the session. The driver documentation must document if the implementation requires this parameter to be set.

enumerator QDMI_SESSION_PARAMETER_AUTHFILE¶

char* (string) A file path to a file containing authentication information.

The file may contain a token or other authentication information required for the session. The driver documentation must document whether the implementation requires this parameter to be set and what kind of authentication information is expected in the file.

enumerator QDMI_SESSION_PARAMETER_AUTHURL¶

char* (string) The URL to an authentication server used as part of the authentication procedure.

This parameter might be used as part of an authentication scheme where an API token is received from an authentication server. This may, additionally, require a username and a password, which can be set via the QDMI_SESSION_PARAMETER_USERNAME and QDMI_SESSION_PARAMETER_PASSWORD parameters.

The driver documentation document when the implementation: requires this parameter to be set and which additional parameters need to be set in case this authentication method is used.

enumerator QDMI_SESSION_PARAMETER_USERNAME¶

char* (string) The username to use for the session.

The username is used for authentication within the session. The driver documentation must document when the implementation requires this parameter to be set.

enumerator QDMI_SESSION_PARAMETER_PASSWORD¶

char* (string) The password to use for the session.

The password is used for authentication within the session. The driver documentation must document when the implementation requires this parameter to be set.

enumerator QDMI_SESSION_PARAMETER_PROJECTID¶

char* (string) The project ID to use for the session.

Can be used to associate the session with a certain project, for example, for accounting purposes. The driver documentation must document when the implementation requires this parameter to be set.

enumerator QDMI_SESSION_PARAMETER_MAX¶

The maximum value of the enum.

It can be used by drivers for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_SESSION_PARAMETER_CUSTOM1¶

This enum value is reserved for a custom parameter.

The driver defines the meaning and the type of this parameter.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_SESSION_PARAMETER_CUSTOM2¶

See also

enumerator QDMI_SESSION_PARAMETER_CUSTOM3¶

See also

enumerator QDMI_SESSION_PARAMETER_CUSTOM4¶

See also

enumerator QDMI_SESSION_PARAMETER_CUSTOM5¶

See also

enum QDMI_SESSION_PROPERTY_T¶

Enum of the session properties that can be queried via QDMI_session_query_session_property.

If not noted otherwise, properties are optional and drivers must not require them to be set.

Values:

enumerator QDMI_SESSION_PROPERTY_DEVICES¶: QDMI_Device* (QDMI_Device list) The devices the client has access to.

enumerator QDMI_SESSION_PROPERTY_MAX¶

The maximum value of the enum.

It can be used by drivers for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_SESSION_PROPERTY_CUSTOM1¶

This enum value is reserved for a custom property.

The driver defines the meaning and the type of this property.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_SESSION_PROPERTY_CUSTOM2¶

See also

enumerator QDMI_SESSION_PROPERTY_CUSTOM3¶

See also

enumerator QDMI_SESSION_PROPERTY_CUSTOM4¶

See also

enumerator QDMI_SESSION_PROPERTY_CUSTOM5¶

See also

Functions

int QDMI_session_alloc(QDMI_Session *session)¶

Allocate a new session.

This is the main entry point for a client to establish a session with a QDMI driver. The returned handle can be used throughout the client 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 QDMI_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 QDMI_session_set_parameter(QDMI_Session session, QDMI_Session_Parameter param, size_t size, const void *value)¶

Set a parameter for a session.

See also

QDMI_session_init

Note

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

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

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

// Set the token.
std::string token = "token";
ret = QDMI_session_set_parameter(
  session, QDMI_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_Session_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 driver supports the specified param and, when value is not NULL, the value of the parameter was set successfully.

Returns:

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

Returns:

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_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 QDMI_session_init(QDMI_Session session)¶

Initialize a session.

This function initializes the session and prepares it for use. The session must be initialized before properties can be queried using QDMI_session_query_session_property. Some devices may require authentication information to be set using QDMI_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 QDMI_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.

int QDMI_session_query_session_property(QDMI_Session session, QDMI_Session_Property prop, size_t size, void *value, size_t *size_ret)¶

Query a property of a session.

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

Note

By calling this function with value set to NULL, the function can be used to check if the driver 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 will be returned in size_ret if size_ret is not NULL.

For example, to query the devices available in a session, the following code pattern can be used:

// Query the size of the property.
size_t size;
auto ret = QDMI_session_query_session_property(
  session, QDMI_SESSION_PROPERTY_DEVICES, 0, nullptr, &size);

// Allocate memory for the property.
auto devices = std::vector<QDMI_Device>(size / sizeof(QDMI_Device));

// Query the property.
ret = QDMI_session_query_session_property(
  session, prop, size, static_cast<void*>(devices.data()), nullptr);

Parameters:

session – [in] The session to query. Must not be NULL.
prop – [in] The property to query. Must be one of the values specified for QDMI_Session_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_Session_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 driver supports the specified property and, when value is not NULL, the property was successfully retrieved.

Returns:

QDMI_ERROR_NOTSUPPORTED if the driver does not support the property.

Returns:

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.

void QDMI_session_free(QDMI_Session session)¶

Free a session.

This function frees the memory allocated for the session. Accessing a (dangling) handle to a device that was attached to the session after the session was freed is undefined behavior.

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

Client queries¶

group QDMI Client Query Interface

Provides functions to query properties of devices.

The query interface enables to query static and dynamic properties of devices and their constituents in a unified fashion. It operates on QDMI_Device handles queried from a QDMI_Session via QDMI_session_query_session_property.

Functions

int QDMI_device_query_device_property(QDMI_Device device, QDMI_Device_Property prop, size_t size, void *value, size_t *size_ret)¶

Query a device property.

Note

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

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

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

// Query the property.
QDMI_device_query_device_property(
  device, QDMI_DEVICE_PROPERTY_NAME, size, name.data(), nullptr);

Parameters:

device – [in] The device to 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:

device 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_FATAL if an unexpected error occurred.

int QDMI_device_query_site_property(QDMI_Device device, QDMI_Site site, QDMI_Site_Property prop, size_t size, void *value, size_t *size_ret)¶

Query a site property.

Remark

QDMI_Site handles may be queried via QDMI_device_query_device_property with QDMI_DEVICE_PROPERTY_SITES.

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 = QDMI_device_query_site_property(
  device, 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;
QDMI_device_query_site_property(
  device, site, QDMI_SITE_PROPERTY_T1, sizeof(uint64_t), &t1, nullptr);

Parameters:

device – [in] The device to 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:

device 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_FATAL if an unexpected error occurred.

int QDMI_device_query_operation_property(QDMI_Device device, QDMI_Operation operation, size_t num_sites, const 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.

Remark

QDMI_Operation and QDMI_Site handles may be queried via QDMI_device_query_device_property with QDMI_DEVICE_PROPERTY_OPERATIONS and QDMI_DEVICE_PROPERTY_SITES, respectively.

Remark

The number of operands and parameters of an operation can be queried via QDMI_device_query_operation_property with QDMI_OPERATION_PROPERTY_QUBITSNUM and QDMI_OPERATION_PROPERTY_PARAMETERSNUM, respectively.

Note

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 = QDMI_device_query_operation_property(
  device, 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;
QDMI_device_query_operation_property(
  device, operation, 0, nullptr, 0, nullptr,
  QDMI_OPERATION_PROPERTY_FIDELITY, sizeof(double), &fidelity, nullptr);

Parameters:

device – [in] The device to 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 that 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 device does not support the property,
the queried property cannot be provided for the given sites, or
the queried property cannot be provided for the given parameters.

Returns:

device or operation are NULL,
prop is invalid,
num_sites is zero and sites is not NULL,
num_params is zero and params is not NULL, or
value is not NULL and size is less than the size of the data being queried.

Returns:

QDMI_ERROR_FATAL if an unexpected error occurred.

Client jobs¶

group QDMI Client Job Interface

Provides functions to manage client-side jobs.

A job is a task submitted by a client 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 client job is as follows:

Create a job with QDMI_device_create_job.
Set parameters for the job with QDMI_job_set_parameter.
Submit the job to the device with QDMI_job_submit.
Check the status of the job with QDMI_job_check.
Wait for the job to finish with QDMI_job_wait.
Retrieve the results of the job with QDMI_job_get_results.
Free the job with QDMI_job_free when it is no longer used.

Alternatively, a client may retrieve a previously submitted job with QDMI_session_retrieve_job_by_id and continue managing it through the same interface.

Typedefs

typedef struct QDMI_Job_impl_d *QDMI_Job¶

A handle for a client-side job.

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

Remark

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

See also

QDMI_Device_Job for the device-side job handle.

typedef enum QDMI_JOB_PARAMETER_T QDMI_Job_Parameter¶: Job parameter type.

typedef enum QDMI_JOB_PROPERTY_T QDMI_Job_Property¶: Job property type.

Enums

enum QDMI_JOB_PARAMETER_T¶

Enum of the job parameters that can be set.

If not noted otherwise, parameters are optional and drivers must not require them to be set.

Values:

enumerator QDMI_JOB_PARAMETER_PROGRAMFORMAT¶

QDMI_Program_Format The format of the program to be executed.

This parameter is required. If the device does not support the specified program format, it is up to the driver to decide whether to return QDMI_ERROR_NOTSUPPORTED from QDMI_job_set_parameter or to convert the program to a supported format.

enumerator QDMI_JOB_PARAMETER_PROGRAM¶

void* The program to be executed.

This parameter is required. The program must be in the format specified by the QDMI_JOB_PARAMETER_PROGRAMFORMAT parameter. If the program is invalid, the QDMI_job_set_parameter function must return QDMI_ERROR_INVALIDARGUMENT. If the program is valid, but the device cannot execute it, the QDMI_job_set_parameter function must return QDMI_ERROR_NOTSUPPORTED.

enumerator QDMI_JOB_PARAMETER_SHOTSNUM¶

size_t The number of shots to execute for a quantum circuit job.

If this parameter is not set, a device-specific default is used.

enumerator QDMI_JOB_PARAMETER_MAX¶

The maximum value of the enum.

It can be used by drivers for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_JOB_PARAMETER_CUSTOM1¶

This enum value is reserved for a custom parameter.

The driver defines the meaning and the type of this parameter.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_JOB_PARAMETER_CUSTOM2¶

See also

enumerator QDMI_JOB_PARAMETER_CUSTOM3¶

See also

enumerator QDMI_JOB_PARAMETER_CUSTOM4¶

See also

enumerator QDMI_JOB_PARAMETER_CUSTOM5¶

See also

enum QDMI_JOB_PROPERTY_T¶

Enum of the job properties that can be queried via QDMI_job_query_property as part of the client interface.

In particular, every parameter’s value that can be set via QDMI_job_set_parameter can be queried.

Values:

enumerator QDMI_JOB_PROPERTY_ID¶

char* (string) The job’s ID.

The ID must uniquely identify a job for the specific driver. It may be used with QDMI_session_retrieve_job_by_id to obtain a new QDMI_Job handle for an existing remote job. It may, for example, correspond to the job ID provided by the QDMI device implementation via QDMI_device_job_query_property as part of the device interface or may be generated by the driver.

enumerator QDMI_JOB_PROPERTY_PROGRAMFORMAT¶: QDMI_Program_Format The format of the program to be executed.

Note

This property returns the value of the QDMI_JOB_PARAMETER_PROGRAMFORMAT parameter.

enumerator QDMI_JOB_PROPERTY_PROGRAM¶: void* The program to be executed.

Note

This property returns the value of the QDMI_JOB_PARAMETER_PROGRAM parameter.

enumerator QDMI_JOB_PROPERTY_SHOTSNUM¶: size_t The number of shots to execute for a quantum circuit job.

Note

This property returns the value of the QDMI_JOB_PARAMETER_SHOTSNUM parameter.

enumerator QDMI_JOB_PROPERTY_QUEUEPOSITION¶

size_t The current number of jobs ahead of this job in its queue.

Querying this property must refresh the job’s status and queue position. The property can only be queried while the refreshed status is QDMI_JOB_STATUS_QUEUED; otherwise, the query must return QDMI_ERROR_BADSTATE.

: If the provider only exposes a lower bound, the implementation reports that lower bound. For example, a provider value of >50 is reported as 50.
: The property may yield QDMI_ERROR_NOTSUPPORTED if the implementation cannot obtain a trustworthy queue position.

enumerator QDMI_JOB_PROPERTY_MAX¶

The maximum value of the enum.

It can be used by devices for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_JOB_PROPERTY_CUSTOM1¶

This enum value is reserved for a custom parameter.

The driver defines the meaning and the type of this parameter.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_JOB_PROPERTY_CUSTOM2¶

See also

enumerator QDMI_JOB_PROPERTY_CUSTOM3¶

See also

enumerator QDMI_JOB_PROPERTY_CUSTOM4¶

See also

enumerator QDMI_JOB_PROPERTY_CUSTOM5¶

See also

Functions

int QDMI_device_create_job(QDMI_Device device, QDMI_Job *job)¶

Create a job.

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

Parameters:

device – [in] The device 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 QDMI_job_free when it is no longer used.

Returns:

QDMI_SUCCESS if the job was successfully created.

Returns:

QDMI_ERROR_INVALIDARGUMENT if device or job are NULL.

Returns:

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

Returns:

QDMI_ERROR_FATAL if job creation failed due to a fatal error.

int QDMI_session_retrieve_job_by_id(QDMI_Device device, const char *job_id, QDMI_Job *job)¶

Retrieve an existing job by its ID.

Creates a new local job handle for the existing remote job identified by job_id. Retrieving a job does not submit, clone, or otherwise modify the remote job. The returned handle can be used to query properties, check or wait for completion, cancel the job, and retrieve results.

The job is accessed with the credentials and configuration of the current session. The job ID is an identifier, not an authentication credential. Parameters cannot be set on a retrieved job, and a retrieved job cannot be submitted again.

Parameters:

device – [in] The device from which to retrieve the job. Must not be NULL.
job_id – [in] The nonempty, null-terminated ID returned by QDMI_JOB_PROPERTY_ID. Must not be NULL.
job – [out] A pointer to a handle that will store the retrieved job. Must not be NULL. The handle must be freed by calling QDMI_job_free when it is no longer used.

Returns:

QDMI_SUCCESS if the job was successfully retrieved.

Returns:

QDMI_ERROR_INVALIDARGUMENT if device, job_id, or job is NULL, or if job_id is empty.

Returns:

QDMI_ERROR_NOTSUPPORTED if the driver or device does not support retrieving existing jobs.

Returns:

QDMI_ERROR_NOTFOUND if no accessible job with job_id exists.

Returns:

QDMI_ERROR_PERMISSIONDENIED if the current session is not permitted to access the job.

Returns:

QDMI_ERROR_FATAL if retrieving the job failed due to a fatal error.

int QDMI_job_set_parameter(QDMI_Job job, QDMI_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 driver 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 = QDMI_job_set_parameter(
  job, QDMI_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;
QDMI_job_set_parameter(
  job, QDMI_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_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 driver supports the specified QDMI_Job_Parameter param and, when value is not NULL, the parameter was successfully set.

Returns:

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

Returns:

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_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 driver does not allow using the client job interface for the device in the current session.

Returns:

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

int QDMI_job_query_property(QDMI_Job job, QDMI_Job_Property prop, size_t size, void *value, size_t *size_ret)¶

Query a job property.

Note

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;
QDMI_job_query_property(
  job, QDMI_JOB_PROPERTY_ID, 0, nullptr, &size);

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

// Query the property.
QDMI_job_query_property(
  job, QDMI_JOB_PROPERTY_NAME, size, name.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_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:

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_FATAL if an unexpected error occurred.

int QDMI_job_submit(QDMI_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 QDMI_job_check and QDMI_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_BADSTATE if the job is in an invalid state.
Returns:: QDMI_ERROR_PERMISSIONDENIED if the driver does not allow using the client job interface for the device in the current session.
Returns:: QDMI_ERROR_FATAL if the job submission failed.

int QDMI_job_cancel(QDMI_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 driver does not allow using the client job interface for the device in the current session.
Returns:: QDMI_ERROR_FATAL if the job could not be canceled.

int QDMI_job_check(QDMI_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 QDMI_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 driver does not allow using the client job interface for the device in the current session.

Returns:

QDMI_ERROR_FATAL if the job status could not be checked.

int QDMI_job_wait(QDMI_Job job, size_t timeout)¶

Wait for a job to finish.

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 driver does not allow using the client job interface for the device in 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 QDMI_job_get_results(QDMI_Job job, QDMI_Job_Result result, size_t size, void *data, size_t *size_ret)¶

Retrieve the results of a job.

Note

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 = QDMI_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.
QDMI_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_DEVICE_PROPERTY_CHILDDEVICES

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 driver does not allow using the client job interface for the device in the current session.

Returns:

QDMI_ERROR_FATAL if an error occurred during the retrieval.

void QDMI_job_free(QDMI_Job job)¶

Free a job.

Free the resources associated with a job. Using a job handle after it has been freed is undefined behavior. Freeing a job handle does not necessarily cancel or delete the underlying job; this behavior is device-specific.

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

IBM handle types¶

Defines all types used within QDMI across the QDMI Client Interface and the QDMI Device Interface.

Typedefs

typedef struct IBM_QDMI_Site_impl_d *IBM_QDMI_Site¶

A handle for a site.

An opaque pointer to an implementation of the QDMI site concept. A site is a place that can potentially hold a qubit. In case of superconducting qubits, sites can be used synonymously with qubits. In case of neutral atoms, sites represent individual traps that can confine atoms. Those atoms are then used as qubits. To this end, sites are generalizations of qubits that denote locations where qubits can be placed on a device. Each implementation of the QDMI Device Interface defines the actual implementation of the concept.

A simple example of an implementation is a struct that merely contains the site ID, which can be used to identify the site.

struct IBM_QDMI_Site_impl_d {
  size_t id;
};

typedef struct IBM_QDMI_Operation_impl_d *IBM_QDMI_Operation¶

A handle for an operation.

An opaque pointer to an implementation of the QDMI operation concept. An operation generally represents any instruction that can be executed on a device. This includes gates, measurements, classical control flow elements, movement of qubits, pulse-level instructions, etc. Each implementation of the QDMI Device Interface defines the actual implementation of the concept.

A simple example of an implementation is a struct that merely contains the name of the operation, which can be used to identify the operation.

struct IBM_QDMI_Operation_impl_d {
  std::string name;
};

Client handle types¶

Defines all types used within QDMI across the QDMI Client Interface and the QDMI Device Interface.

Typedefs

typedef struct QDMI_Site_impl_d *QDMI_Site¶

A handle for a site.

A simple example of an implementation is a struct that merely contains the site ID, which can be used to identify the site.

struct QDMI_Site_impl_d {
  size_t id;
};

typedef struct QDMI_Operation_impl_d *QDMI_Operation¶

A handle for an operation.

A simple example of an implementation is a struct that merely contains the name of the operation, which can be used to identify the operation.

struct QDMI_Operation_impl_d {
  std::string name;
};

QDMI constants¶

Defines all enums used within QDMI across the QDMI Client Interface and the QDMI Device Interface.

Typedefs

typedef enum QDMI_DEVICE_SESSION_PARAMETER_T QDMI_Device_Session_Parameter¶: Device session parameter type.

typedef enum QDMI_DEVICE_JOB_PARAMETER_T QDMI_Device_Job_Parameter¶: Device job parameter type.

typedef enum QDMI_DEVICE_JOB_PROPERTY_T QDMI_Device_Job_Property¶: Device job property type.

typedef enum QDMI_DEVICE_PROPERTY_T QDMI_Device_Property¶: Device property type.

typedef enum QDMI_DEVICE_STATUS_T QDMI_Device_Status¶: Device status type.

typedef enum QDMI_SITE_PROPERTY_T QDMI_Site_Property¶: Site property type.

typedef enum QDMI_OPERATION_PROPERTY_T QDMI_Operation_Property¶: Operation property type.

typedef enum QDMI_JOB_STATUS_T QDMI_Job_Status¶: Job status type.

typedef enum QDMI_PROGRAM_FORMAT_T QDMI_Program_Format¶: Program format type.

typedef enum QDMI_JOB_RESULT_T QDMI_Job_Result¶: Job result type.

typedef enum QDMI_DEVICE_PULSE_SUPPORT_LEVEL_T QDMI_Device_Pulse_Support_Level¶: Pulse support level type.

Enums

enum QDMI_STATUS¶

Status codes returned by the API.

Values:

enumerator QDMI_WARN_GENERAL¶: A general warning.

enumerator QDMI_SUCCESS¶: The operation was successful.

enumerator QDMI_ERROR_FATAL¶: A fatal error.

enumerator QDMI_ERROR_OUTOFMEM¶: Out of memory.

enumerator QDMI_ERROR_NOTIMPLEMENTED¶: Not implemented.

enumerator QDMI_ERROR_LIBNOTFOUND¶: Library not found.

enumerator QDMI_ERROR_NOTFOUND¶: Element not found.

enumerator QDMI_ERROR_OUTOFRANGE¶: Out of range.

enumerator QDMI_ERROR_INVALIDARGUMENT¶: Invalid argument.

enumerator QDMI_ERROR_PERMISSIONDENIED¶: Permission denied.

enumerator QDMI_ERROR_NOTSUPPORTED¶: Operation is not supported.

enumerator QDMI_ERROR_BADSTATE¶: Resource is in the wrong state for the operation.

enumerator QDMI_ERROR_TIMEOUT¶: Operation timed out.

enum QDMI_DEVICE_SESSION_PARAMETER_T¶

Enum of the device session parameters that can be set via QDMI_device_session_set_parameter.

If not noted otherwise, parameters are optional and devices must not require them to be set.

Values:

enumerator QDMI_DEVICE_SESSION_PARAMETER_BASEURL¶

char* (string) The baseURL or API endpoint to be used for accessing the device within the session.

If this parameter is set and the device supports it, the device must use the specified baseURL or API endpoint for the session. Devices may use this parameter to switch between different versions of the API or different endpoints for testing or production environments.

enumerator QDMI_DEVICE_SESSION_PARAMETER_TOKEN¶

char* (string) A token to be used in the session initialization for authenticating with the device.

A token could be an API key. The device documentation must document what kind of token is required and how it is used. If the device requires authentication via a token, this parameter must be set before calling QDMI_device_session_init.

enumerator QDMI_DEVICE_SESSION_PARAMETER_AUTHFILE¶

char* (string) A file path to a file containing authentication information.

The file may contain a token or other authentication information required for the session. The device documentation must document whether the implementation requires this parameter to be set and what kind of authentication information is expected in the file.

enumerator QDMI_DEVICE_SESSION_PARAMETER_AUTHURL¶

char* (string) The URL to an authentication server used as part of the authentication procedure.

This parameter might be used as part of an authentication scheme where an API token is received from an authentication server. This may, additionally, require a username and a password, which can be set via the QDMI_DEVICE_SESSION_PARAMETER_USERNAME and QDMI_DEVICE_SESSION_PARAMETER_PASSWORD parameters.

The device documentation document if the implementation: requires this parameter to be set and which additional parameters need to be set in case this authentication method is used.

enumerator QDMI_DEVICE_SESSION_PARAMETER_USERNAME¶

char* (string) The username to use for the device session.

The username is used for authentication within the session. The device documentation must document when the implementation requires this parameter to be set.

enumerator QDMI_DEVICE_SESSION_PARAMETER_PASSWORD¶

char* (string) The password to use for the session.

The password is used for authentication within the session. The device documentation must document if the implementation requires this parameter to be set.

enumerator QDMI_DEVICE_SESSION_PARAMETER_CHILDDEVICE¶

QDMI_Child_Device The child device to establish the session with.

If the device manages child devices, a QDMI driver can establish a session with those child devices by setting this session parameter to the respective QDMI_Child_Device handle.

See also

: After initialization of this session, the device will forward any function call on this session to the job or query interface of the child device.

Note

This parameter can be unset by setting this parameter to NULL.

enumerator QDMI_DEVICE_SESSION_PARAMETER_MAX¶

The maximum value of the enum.

It can be used by devices for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_DEVICE_SESSION_PARAMETER_CUSTOM1¶

This enum value is reserved for a custom parameter.

The device defines the meaning and the type of this parameter.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_DEVICE_SESSION_PARAMETER_CUSTOM2¶

See also

enumerator QDMI_DEVICE_SESSION_PARAMETER_CUSTOM3¶

See also

enumerator QDMI_DEVICE_SESSION_PARAMETER_CUSTOM4¶

See also

enumerator QDMI_DEVICE_SESSION_PARAMETER_CUSTOM5¶

See also

enum QDMI_DEVICE_JOB_PARAMETER_T¶

Enum of the device job parameters that can be set via QDMI_device_job_set_parameter.

If not noted otherwise, parameters are optional and devices must not require them to be set.

Values:

enumerator QDMI_DEVICE_JOB_PARAMETER_PROGRAMFORMAT¶

QDMI_Program_Format The format of the program to be executed.

This parameter is required. The device must support the specified program format. If the device does not support the specified program format, the QDMI_device_job_set_parameter function must return QDMI_ERROR_NOTSUPPORTED.

enumerator QDMI_DEVICE_JOB_PARAMETER_PROGRAM¶

void* The program to be executed.

This parameter is required. The program must be in the format specified by the QDMI_DEVICE_JOB_PARAMETER_PROGRAMFORMAT parameter. If the program is invalid, the QDMI_device_job_set_parameter function must return QDMI_ERROR_INVALIDARGUMENT. If the program is valid, but the device cannot execute it, the QDMI_device_job_set_parameter function must return QDMI_ERROR_NOTSUPPORTED.

enumerator QDMI_DEVICE_JOB_PARAMETER_SHOTSNUM¶

size_t The number of shots to execute for a quantum circuit job.

If this parameter is not set, a device-specific default is used.

enumerator QDMI_DEVICE_JOB_PARAMETER_MAX¶

The maximum value of the enum.

It can be used by devices for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_DEVICE_JOB_PARAMETER_CUSTOM1¶

This enum value is reserved for a custom parameter.

The device defines the meaning and the type of this parameter.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_DEVICE_JOB_PARAMETER_CUSTOM2¶

See also

enumerator QDMI_DEVICE_JOB_PARAMETER_CUSTOM3¶

See also

enumerator QDMI_DEVICE_JOB_PARAMETER_CUSTOM4¶

See also

enumerator QDMI_DEVICE_JOB_PARAMETER_CUSTOM5¶

See also

enum QDMI_DEVICE_JOB_PROPERTY_T¶

Enum of the device job properties that can be queried via QDMI_device_job_query_property as part of the device interface.

In particular, every parameter’s value that can be set via QDMI_device_job_set_parameter can be queried.

Values:

enumerator QDMI_DEVICE_JOB_PROPERTY_ID¶

char* (string) The job’s ID.

The ID must uniquely identify a job for the specific device. It should generally be universally unique (such as a UUID), to avoid conflicts with other devices’ job IDs. It may be used with QDMI_device_session_retrieve_device_job_by_id to obtain a new QDMI_Device_Job handle for an existing remote job. It may, for example, correspond to the job ID provided by the device’s API or may be generated by the QDMI Device implementation.

enumerator QDMI_DEVICE_JOB_PROPERTY_PROGRAMFORMAT¶: QDMI_Program_Format The format of the program to be executed.

Note

This property returns the value of the QDMI_DEVICE_JOB_PARAMETER_PROGRAMFORMAT parameter.

enumerator QDMI_DEVICE_JOB_PROPERTY_PROGRAM¶: void* The program to be executed.

Note

This property returns the value of the QDMI_DEVICE_JOB_PARAMETER_PROGRAM parameter.

enumerator QDMI_DEVICE_JOB_PROPERTY_SHOTSNUM¶: size_t The number of shots to execute for a quantum circuit job.

Note

This property returns the value of the QDMI_DEVICE_JOB_PARAMETER_SHOTSNUM parameter.

enumerator QDMI_DEVICE_JOB_PROPERTY_QUEUEPOSITION¶

size_t The current number of jobs ahead of this job in its queue.

: If the provider only exposes a lower bound, the implementation reports that lower bound. For example, a provider value of >50 is reported as 50.
: The property may yield QDMI_ERROR_NOTSUPPORTED if the implementation cannot obtain a trustworthy queue position.

enumerator QDMI_DEVICE_JOB_PROPERTY_MAX¶

The maximum value of the enum.

It can be used by devices for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_DEVICE_JOB_PROPERTY_CUSTOM1¶

This enum value is reserved for a custom parameter.

The device defines the meaning and the type of this parameter.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_DEVICE_JOB_PROPERTY_CUSTOM2¶

See also

enumerator QDMI_DEVICE_JOB_PROPERTY_CUSTOM3¶

See also

enumerator QDMI_DEVICE_JOB_PROPERTY_CUSTOM4¶

See also

enumerator QDMI_DEVICE_JOB_PROPERTY_CUSTOM5¶

See also

enum QDMI_DEVICE_PROPERTY_T¶

Enum of the device properties that can be queried via QDMI_device_session_query_device_property as part of the device interface and via QDMI_device_query_device_property as part of the client interface.

Values:

enumerator QDMI_DEVICE_PROPERTY_NAME¶: char* (string) The name of the device.

enumerator QDMI_DEVICE_PROPERTY_VERSION¶: char* (string) The version of the device.

enumerator QDMI_DEVICE_PROPERTY_STATUS¶: QDMI_Device_Status The status of the device.

enumerator QDMI_DEVICE_PROPERTY_LIBRARYVERSION¶: char* (string) The implemented version of QDMI.

enumerator QDMI_DEVICE_PROPERTY_QUBITSNUM¶: size_t The number of qubits in the device.

enumerator QDMI_DEVICE_PROPERTY_SITES¶

QDMI_Site* (QDMI_Site list) The sites of the device.

The returned QDMI_Site handles may be used to query site and operation properties. The list need not be sorted based on the QDMI_SITE_PROPERTY_INDEX.

: The list returned by this property contains all sites of the device, i.e., regular and zone sites (see QDMI_SITE_PROPERTY_ISZONE). To filter out regular or zone sites, use the function QDMI_device_query_site_property.

enumerator QDMI_DEVICE_PROPERTY_OPERATIONS¶

QDMI_Operation* (QDMI_Operation list) The operations supported by the device.

The returned QDMI_Operation handles may be used to query operation properties.

enumerator QDMI_DEVICE_PROPERTY_COUPLINGMAP¶

QDMI_Site* (QDMI_Site list) The coupling map of the device.

The returned list contains pairs of sites that are coupled. The pairs in the list are flattened such that the first site of the pair is at index 2n and the second site is at index 2n+1.

The sites returned in that list are represented as QDMI_Site handles. For example, consider a 3-site device with a coupling map (0, 1), (1, 2). Additionally, assume site_i is the handle for the i-th site. Then, {site_0, site_1, site_1, site_2} would be returned.

enumerator QDMI_DEVICE_PROPERTY_NEEDSCALIBRATION¶

size_t Whether the device needs calibration.

This flag indicates whether the device needs calibration. A value of zero indicates that the device does not need calibration, while any non-zero value indicates that the device needs calibration. It is up to the device to assign a specific meaning to the non-zero value.

If a device reports that it needs calibration, a calibration run can be triggered by submitting a job with the QDMI_Program_Format set to QDMI_PROGRAM_FORMAT_CALIBRATION.

enumerator QDMI_DEVICE_PROPERTY_PULSESUPPORT¶

QDMI_Device_Pulse_Support_Level Whether the device supports pulse-level control.

This property indicates the level of pulse-level control. If a device supports pulse-level control, it may provide additional functionality for pulse-level programming and execution.

enumerator QDMI_DEVICE_PROPERTY_LENGTHUNIT¶

char* (string) The length unit reported by the device.

The device implementation must report a known SI unit (e.g., “mm”, “um”, or “nm”) for this property. A client querying a length value must first scale it using QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR. The resulting value is then interpreted in the unit specified by this property.

Note

If the device reports any length values, this property must be set.

enumerator QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR¶

double A scale factor for all length values.

The device implementation reports this scale factor. A client must multiply any raw length value received from the device by this factor to obtain the physical length. The unit of the physical length is given by QDMI_DEVICE_PROPERTY_LENGTHUNIT.

Note

If querying this property returns QDMI_ERROR_NOTSUPPORTED, a client should assume a default value of 1.0.

enumerator QDMI_DEVICE_PROPERTY_DURATIONUNIT¶

char* (string) The duration unit reported by the device.

The device implementation must report a known SI unit (e.g., “ms”, “us”, or “ns”) for this property. A client querying a duration value must first scale it using QDMI_DEVICE_PROPERTY_DURATIONSCALEFACTOR. The resulting value is then interpreted in the unit specified by this property.

Note

If the device reports any duration values, this property must be set.

enumerator QDMI_DEVICE_PROPERTY_DURATIONSCALEFACTOR¶

double A scale factor for all duration values.

The device implementation reports this scale factor. A client must multiply any raw duration value received from the device by this factor to obtain the physical duration. The unit of the physical duration is given by QDMI_DEVICE_PROPERTY_DURATIONUNIT.

Note

If querying this property returns QDMI_ERROR_NOTSUPPORTED, a client should assume a default value of 1.0.

enumerator QDMI_DEVICE_PROPERTY_MINATOMDISTANCE¶

uint64_t The raw, unscaled minimum required distance between qubits during quantum computation.

For neutral atom-based devices, qubits (atoms) can be repositioned dynamically. However, a minimum separation must be maintained to prevent collisions and loss of atoms. This property specifies the minimum atom distance.

See also

QDMI_DEVICE_PROPERTY_LENGTHUNIT QDMI_DEVICE_PROPERTY_LENGTSCALEFACTOR

: To obtain the physical minimum atom distance, a client must scale the raw value of this property. The physical minimum atom distance is calculated as: raw_value * scale_factor, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_LENGTHUNIT.

Note

Primarily relevant for neutral atom devices supporting dynamic atom arrangement.

enumerator QDMI_DEVICE_PROPERTY_SUPPORTEDPROGRAMFORMATS¶

QDMI_Program_Format* (QDMI_Program_Format list) The program formats supported by the device.

The returned list contains all program formats that the device supports for execution. A client can use this information to determine which program formats can be used when submitting jobs to the device.

enumerator QDMI_DEVICE_PROPERTY_CHILDDEVICES¶

QDMI_Child_Device* (QDMI_Child_Device list) A list of device handles corresponding to the device’s child devices managed by this device.

Some devices may manage multiple child devices, e.g., a multi-device system or a device with multiple processing units. This property provides access to the child devices as separate QDMI_Child_Device handles.

: The property may yield QDMI_ERROR_NOTSUPPORTED if the device does not have any child devices.

Note

Devices with child devices may have special job submission handling. Check the concrete device’s job interface documentation.

enumerator QDMI_DEVICE_PROPERTY_QUEUELENGTH¶

size_t The current number of jobs waiting to access the device.

This property is a snapshot of the device’s queue length and does not include jobs that are currently executing. If a provider exposes multiple queues for the device, the implementation reports the sum of the waiting jobs across those queues.

: If the provider only exposes a lower bound, the implementation reports that lower bound. For example, a provider value of >50 is reported as 50.
: The property may yield QDMI_ERROR_NOTSUPPORTED if the implementation cannot obtain a trustworthy queue length.

enumerator QDMI_DEVICE_PROPERTY_MAX¶

The maximum value of the enum.

It can be used by devices for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_DEVICE_PROPERTY_CUSTOM1¶

This enum value is reserved for a custom property.

The device defines the meaning and the type of this property.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_DEVICE_PROPERTY_CUSTOM2¶

See also

enumerator QDMI_DEVICE_PROPERTY_CUSTOM3¶

See also

enumerator QDMI_DEVICE_PROPERTY_CUSTOM4¶

See also

enumerator QDMI_DEVICE_PROPERTY_CUSTOM5¶

See also

enum QDMI_DEVICE_STATUS_T¶

Enum of different status the device can be in.

Values:

enumerator QDMI_DEVICE_STATUS_OFFLINE¶: The device is offline.

enumerator QDMI_DEVICE_STATUS_IDLE¶: The device is idle.

enumerator QDMI_DEVICE_STATUS_BUSY¶: The device is busy.

enumerator QDMI_DEVICE_STATUS_ERROR¶: The device is in an error state.

enumerator QDMI_DEVICE_STATUS_MAINTENANCE¶: The device is in maintenance.

enumerator QDMI_DEVICE_STATUS_CALIBRATION¶: The device is in calibration.

enumerator QDMI_DEVICE_STATUS_MAX¶

The maximum value of the enum.

It can be used by devices for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enum QDMI_SITE_PROPERTY_T¶

Enum of the site properties that can be queried via QDMI_device_session_query_site_property as part of the device interface and via QDMI_device_query_site_property as part of the client interface.

Values:

enumerator QDMI_SITE_PROPERTY_INDEX¶

size_t The unique index (or ID) to identify the site in a program.

The index of a site is used to link the qubits used in a quantum program to the physical sites of the device that can be queried via this interface. Indices may be non-consecutive and need not start at 0. See QDMI_Program_Format for more information on how the site indices map to the qubits in a program.

This property must be available for all sites since it is used to: address the sites in a program.

enumerator QDMI_SITE_PROPERTY_T1¶

uint64_t The raw, unscaled T1 time of a site.

To obtain the physical T1 time, a client must scale the raw value of this property. The physical T1 time is calculated as: raw_value * scale_factor, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_DURATIONSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_DURATIONUNIT.

enumerator QDMI_SITE_PROPERTY_T2¶

uint64_t The raw, unscaled T2 time of a site.

To obtain the physical T2 time, a client must scale the raw value of this property. The physical T2 time is calculated as: raw_value * scale_factor, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_DURATIONSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_DURATIONUNIT.

enumerator QDMI_SITE_PROPERTY_NAME¶: char* (string) The name of a site, e.g., another identifier of the site given by the device.

enumerator QDMI_SITE_PROPERTY_XCOORDINATE¶

int64_t The raw, unscaled X-coordinate of the site.

The X-coordinate is measured relative to some unique origin of the device, i.e., the triple of X-, Y-, and Z-coordinate must be unique to the site.

: To obtain the physical X-coordinate of the site, a client must scale the raw value of this property. The physical X-coordinate of the site is calculated as: raw_value * scale_factor, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_LENGTHUNIT.

Note

This property is mainly required for neutral atom devices to report the location of sites.

enumerator QDMI_SITE_PROPERTY_YCOORDINATE¶

int64_t The raw, unscaled Y-coordinate of the site.

The Y-coordinate is measured relative to some unique origin of the device, i.e., the triple of X-, Y-, and Z-coordinate must be unique to the site.

: To obtain the physical Y-coordinate of the site, a client must scale the raw value of this property. The physical Y-coordinate of the site is calculated as: raw_value * scale_factor, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_LENGTHUNIT.

Note

This property is mainly required for neutral atom devices to report the location of sites.

enumerator QDMI_SITE_PROPERTY_ZCOORDINATE¶

int64_t The raw, unscaled Z-coordinate of the site.

The Z-coordinate is measured relative to some unique origin of the device, i.e., the triple of X-, Y-, and Z-coordinate must be unique to the site.

: To obtain the physical Z-coordinate of the site, a client must scale the raw value of this property. The physical Z-coordinate of the site is calculated as: raw_value * scale_factor, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_LENGTHUNIT.

Note

This property is mainly required for neutral atom devices to report the location of sites.

enumerator QDMI_SITE_PROPERTY_ISZONE¶

bool Whether the site is a zone.

A zone is a site that has a spatial extent, i.e., it is not just a point in space as a regular site. These kind of sites, namely zones, are required to adequately represent global operations that act on all qubits within a certain area, i.e., a zone.

Note

Zones are typically used in neutral atom devices, where the atoms are arranged in a 2D or 3D lattice, and operations can be applied to all atoms within a certain zone. This property defaults to false, i.e., if a device reports QDMI_ERROR_NOTSUPPORTED for this property, it is assumed that the site is a regular site and not a zone.

enumerator QDMI_SITE_PROPERTY_XEXTENT¶

uint64_t The raw, unscaled extent of a zone along the X-axis.

To obtain the physical extent of a zone along the X-axis, a client must scale the raw value of this property. The physical extent of a zone along the X-axis is calculated as: raw_value * scale_factor, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_LENGTHUNIT.

See also

QDMI_DEVICE_PROPERTY_LENGTHUNIT QDMI_DEVICE_PROPERTY_LENGTSCALEFACTOR

Note

This property is mainly required for neutral atom devices to report the extent of zones, see QDMI_SITE_PROPERTY_ISZONE. If the site is not a zone, this property must return QDMI_ERROR_NOTSUPPORTED.

enumerator QDMI_SITE_PROPERTY_YEXTENT¶

uint64_t The raw, unscaled extent of a zone along the Y-axis.

To obtain the physical extent of a zone along the Y-axis, a client must scale the raw value of this property. The physical extent of a zone along the Y-axis is calculated as: raw_value * scale_factor, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_LENGTHUNIT.

See also

QDMI_DEVICE_PROPERTY_LENGTHUNIT QDMI_DEVICE_PROPERTY_LENGTSCALEFACTOR

Note

This property is mainly required for neutral atom devices to report the extent of zones, see QDMI_SITE_PROPERTY_ISZONE. If the site is not a zone, this property must return QDMI_ERROR_NOTSUPPORTED.

enumerator QDMI_SITE_PROPERTY_ZEXTENT¶

uint64_t The raw, unscaled extent of a zone along the Z-axis.

To obtain the physical extent of a zone along the Z-axis, a client must scale the raw value of this property. The physical extent of a zone along the Z-axis is calculated as: raw_value * scale_factor, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_LENGTHUNIT.

See also

QDMI_DEVICE_PROPERTY_LENGTHUNIT QDMI_DEVICE_PROPERTY_LENGTSCALEFACTOR

Note

This property is mainly required for neutral atom devices to report the extent of zones, see QDMI_SITE_PROPERTY_ISZONE. If the site is not a zone, this property must return QDMI_ERROR_NOTSUPPORTED.

enumerator QDMI_SITE_PROPERTY_MODULEINDEX¶

uint64_t an unsigned integer that uniquely identifies the module.

A module is a logical grouping of sites, e.g., one part on a superconducting chip or an array of sites in a neutral atom-based device.

enumerator QDMI_SITE_PROPERTY_SUBMODULEINDEX¶

uint64_t an unsigned integer uniquely identifying the submodule within a module.

A submodule is a repetitive substructure of sites within a module. E.g., for a module (QDMI_SITE_PROPERTY_MODULEINDEX), where the sites are arranged in pairs and the pairs are arranged in a grid, the submodule index would be the index of the pair within the module.

enumerator QDMI_SITE_PROPERTY_MAX¶

The maximum value of the enum.

It can be used by devices for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_SITE_PROPERTY_CUSTOM1¶

This enum value is reserved for a custom property.

The device defines the meaning and the type of this property.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_SITE_PROPERTY_CUSTOM2¶

See also

enumerator QDMI_SITE_PROPERTY_CUSTOM3¶

See also

enumerator QDMI_SITE_PROPERTY_CUSTOM4¶

See also

enumerator QDMI_SITE_PROPERTY_CUSTOM5¶

See also

enum QDMI_OPERATION_PROPERTY_T¶

Enum of the operation properties that can be queried via QDMI_device_session_query_operation_property as part of the device interface and via QDMI_device_query_operation_property as part of the client interface.

Values:

enumerator QDMI_OPERATION_PROPERTY_NAME¶: char* (string) The string identifier of the operation.

enumerator QDMI_OPERATION_PROPERTY_QUBITSNUM¶: size_t The number of qubits involved in the operation.

enumerator QDMI_OPERATION_PROPERTY_PARAMETERSNUM¶: size_t The number of floating point parameters the operation takes.

enumerator QDMI_OPERATION_PROPERTY_DURATION¶

uint64_t The raw, unscaled duration of an operation.

To obtain the physical duration, a client must scale the raw value of this property. The physical duration is calculated as: raw_value * scale_factor, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_DURATIONSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_DURATIONUNIT.

enumerator QDMI_OPERATION_PROPERTY_FIDELITY¶: double The fidelity of an operation.

enumerator QDMI_OPERATION_PROPERTY_INTERACTIONRADIUS¶

uint64_t The raw, unscaled interaction radius of the operation.

The interaction radius is the maximum distance between two qubits that can be involved in the operation. It only applies to multi-qubit gates.

See also

QDMI_DEVICE_PROPERTY_LENGTHUNIT QDMI_DEVICE_PROPERTY_LENGTSCALEFACTOR

: To obtain the physical interaction radius, a client must scale the raw value of this property. The physical interaction radius is calculated as: raw_value * scale_factor, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_LENGTHUNIT.

Note

This property is mainly required for neutral atom devices where atoms representing qubits can be at arbitrary locations. Hence, it is infeasible to define a coupling map. Instead, the coupling of atoms is defined by the interaction radius of the operation.

enumerator QDMI_OPERATION_PROPERTY_BLOCKINGRADIUS¶

uint64_t The raw, unscaled blocking radius of the operation.

The blocking radius is the minimum distance between two qubits that should not be involved in the operation to avoid crosstalk. It only applies to multi-qubit gates.

: To obtain the physical blocking radius, a client must scale the raw value of this property. The physical blocking radius is calculated as: raw_value, where scale_factor is the value of the QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR property. The resulting value is in units of QDMI_DEVICE_PROPERTY_LENGTHUNIT.

Note

This property is mainly required for neutral atom devices where atoms representing qubits can be at arbitrary locations. To avoid crosstalk, the blocking radius of the operation must be respected when scheduling operations.

enumerator QDMI_OPERATION_PROPERTY_IDLINGFIDELITY¶

double Fidelity of qubits idling during a global operation.

This property measures the fidelity of qubits that are within the affected area of a global multi-qubit operation but do not actively participate (i.e., they lack an interaction partner within their radius). Even though these qubits undergo an identity operation, errors may still occur, resulting in lower fidelity compared to qubits that are simply idling and not exposed to the operation.

Note

This is especially relevant for neutral atom devices, where global operations (e.g., laser pulses) can impact all atoms in the array, including those not interacting.

enumerator QDMI_OPERATION_PROPERTY_ISZONED¶

bool Whether the operation is a zoned (global) operation.

A zoned (or global) operation is an operation that can be applied simultaneously to all qubits within a specific zone. If this property is true, the operation is considered zoned. If it is false or returns QDMI_ERROR_NOTSUPPORTED, the operation is considered local. The applicability of a zoned operation to specific zones is detailed in QDMI_OPERATION_PROPERTY_SITES.

Note

This property is primarily relevant for neutral atom devices, where a laser can illuminate an entire array of atoms representing qubits.

enumerator QDMI_OPERATION_PROPERTY_SITES¶

QDMI_Site* (list) The sites to which the operation is applicable.

For local operations (see QDMI_OPERATION_PROPERTY_ISZONED), this property returns a list of tuples. Each tuple contains sites from the list provided by QDMI_DEVICE_PROPERTY_SITES and represents a valid combination for the operation. The number of sites in each tuple matches the value of QDMI_OPERATION_PROPERTY_QUBITSNUM.
For global operations (see QDMI_OPERATION_PROPERTY_ISZONED), this property returns a list of zone sites, i.e., zones where the operation can be applied.

enumerator QDMI_OPERATION_PROPERTY_MEANSHUTTLINGSPEED¶

uint64_t The raw, unscaled mean shuttling speed of an operation.

To obtain the physical speed, a client must scale the raw value of this property. The physical speed is calculated as: raw_value * length_scale_factor / duration_scale_factor. The length_scale_factor is the value of QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR and the duration_scale_factor is the value of QDMI_DEVICE_PROPERTY_DURATIONSCALEFACTOR. The resulting value is in units of QDMI_DEVICE_PROPERTY_LENGTHUNIT per QDMI_DEVICE_PROPERTY_DURATIONUNIT.

Note

This property is mainly required for neutral atom devices where atoms representing qubits can be moved to different sites.

enumerator QDMI_OPERATION_PROPERTY_MAX¶

The maximum value of the enum.

It can be used by devices for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_OPERATION_PROPERTY_CUSTOM1¶

This enum value is reserved for a custom property.

The device defines the meaning and the type of this property.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_OPERATION_PROPERTY_CUSTOM2¶

See also

enumerator QDMI_OPERATION_PROPERTY_CUSTOM3¶

See also

enumerator QDMI_OPERATION_PROPERTY_CUSTOM4¶

See also

enumerator QDMI_OPERATION_PROPERTY_CUSTOM5¶

See also

enum QDMI_JOB_STATUS_T¶

Enum of the status a job can have.

See also QDMI Client Job Interface for a description of the job’s lifecycle.

Values:

enumerator QDMI_JOB_STATUS_CREATED¶: The job was created and can be configured via QDMI_job_set_parameter.

enumerator QDMI_JOB_STATUS_SUBMITTED¶: The job was submitted.

enumerator QDMI_JOB_STATUS_QUEUED¶: The job was received, and is waiting to be executed.

enumerator QDMI_JOB_STATUS_RUNNING¶: The job is running, and the result is not yet available.

enumerator QDMI_JOB_STATUS_DONE¶: The job is done, and the result can be retrieved.

enumerator QDMI_JOB_STATUS_CANCELED¶: The job was canceled, and the result is not available.

enumerator QDMI_JOB_STATUS_FAILED¶: An error occurred in the job’s lifecycle.

enum QDMI_PROGRAM_FORMAT_T¶

Enum of formats that can be submitted to the device.

Values:

enumerator QDMI_PROGRAM_FORMAT_QASM2¶

char* (string) An OpenQASM 2.0 program.

A text-based representation of a quantum circuit in the OpenQASM 2.0 language. Devices that claim to support this format must accept programs conforming to the following rules:

The program contains exactly one quantum register named q.
The number of qubits in the quantum register q matches the number of sites in the device.
The program only contains gate identifiers that are reported by the QDMI_OPERATION_PROPERTY_NAME property of the device’s operations.

: Given a program following these rules, the operations in the program are expected to be performed on the physical sites of the device as queried via QDMI_DEVICE_PROPERTY_SITES. Specifically, an operation on q[i] is performed on the i-th site in the list of sites returned by the device.

Note

Devices may decide to support more general OpenQASM 2.0 programs that do not follow these rules, for example, using multiple qubit registers or arbitrary gates. However, in that case, no guarantees can be made about the mapping of qubits in the program to the physical sites of the device.

enumerator QDMI_PROGRAM_FORMAT_QASM3¶

char* (string) An OpenQASM 3 program.

A text-based representation of a quantum circuit in the OpenQASM 3 language. Devices that claim to support this format must accept programs conforming to the same rules as for QDMI_PROGRAM_FORMAT_QASM2.

: Besides the rules for OpenQASM 2.0 programs, OpenQASM 3 programs may be written using physical qubits, which are denoted by $[NUM], with [NUM] being a non-negative integer denoting the physical qubit’s index. If a program uses physical qubits, the operations in the program must be performed on the sites with indices corresponding to the physical qubits in the program.

Note

Devices may decide to support more general OpenQASM 3 programs that do not follow these rules, for example, using multiple qubit registers or arbitrary gates. However, in that case, no guarantees can be made about the mapping of qubits in the program to the physical sites of the device.

enumerator QDMI_PROGRAM_FORMAT_QIRBASESTRING¶

char* (string) A text-based QIR program complying to the QIR base profile.

A text-based representation of a quantum circuit in the Quantum Intermediate Representation (QIR) format; specifically, the QIR base profile. Devices that claim to support this format must accept programs that follow the rules for the QIR base profile and that only contain operations that are reported by the QDMI_OPERATION_PROPERTY_NAME property of the device’s operations (for example, @__quantum__qis__[NAME]__body, where [NAME] is the name of the operation).

: QIR has a similar distinction between dynamically allocated and static hardware qubits as QDMI_PROGRAM_FORMAT_QASM3. The same rules apply for the mapping of qubits in the program to the physical sites of the device. Specifically, if the program only allocates a single register named q with as many qubits as there are sites in the device, the operations in the program are expected to be performed on the physical sites of the device as queried via QDMI_DEVICE_PROPERTY_SITES. If the program uses static qubit addresses (for example, ptr inttoptr (i64 1 to ptr)), the operations in the program must be performed on the sites with indices corresponding to the static qubit addresses in the program.

Note

Devices may decide to support more general QIR programs that do not follow these rules, for example, using multiple qubit registers or arbitrary gates. However, in that case, no guarantees can be made about the mapping of qubits in the program to the physical sites of the device.

enumerator QDMI_PROGRAM_FORMAT_QIRBASEMODULE¶

void* A QIR binary complying to the QIR base profile.

A binary representation of a quantum circuit in the Quantum Intermediate Representation (QIR) format; specifically, the QIR base profile.

See also

QDMI_PROGRAM_FORMAT_QIRBASESTRING for more information on the QIR base profile and the expected behavior of devices supporting this format.

enumerator QDMI_PROGRAM_FORMAT_QIRADAPTIVESTRING¶

char* (string) A text-based QIR program complying to the QIR adaptive profile.

A text-based representation of a quantum circuit in the Quantum Intermediate Representation (QIR) format; specifically, the QIR adaptive profile.

See also

QDMI_PROGRAM_FORMAT_QIRBASESTRING for more information on the QIR base profile and the expected behavior of devices supporting this format.

enumerator QDMI_PROGRAM_FORMAT_QIRADAPTIVEMODULE¶

void* A QIR binary complying to the QIR adaptive profile.

A binary representation of a quantum circuit in the Quantum Intermediate Representation (QIR) format; specifically, the QIR adaptive profile.

See also

QDMI_PROGRAM_FORMAT_QIRBASESTRING for more information on the QIR base profile and the expected behavior of devices supporting this format.

enumerator QDMI_PROGRAM_FORMAT_CALIBRATION¶

void* A calibration program.

This program format is used to request the device to perform a calibration run. Triggering a calibration run does not require a program to be set via QDMI_DEVICE_JOB_PARAMETER_PROGRAM.

enumerator QDMI_PROGRAM_FORMAT_QPY¶

void* A QPY program.

A binary representation of a Qiskit QuantumCircuit in the QPY format.

See also

QDMI_PROGRAM_FORMAT_QASM3 for more information on the expected behavior of devices supporting this format.

enumerator QDMI_PROGRAM_FORMAT_IQMJSON¶

char* (string) A program in the IQM data transfer format.

A text-based, proprietary representation of a quantum circuit in the IQM data transfer format, encoded as a JSON string.

enumerator QDMI_PROGRAM_FORMAT_BATCHJOB¶

QDMI_Job*/QDMI_Device_Job* (QDMI_Job list / QDMI_Device_Job list) A list of jobs within a batch job.

This program format is used to submit a batch job, i.e., a job that consists of multiple sub-jobs. The program must be a list of jobs created via QDMI_device_create_job or QDMI_device_session_create_device_job. These jobs must be configured completely but not submitted. If a batch job contains already submitted jobs, QDMI_job_submit or QDMI_device_job_submit on the batch job will return QDMI_ERROR_BADSTATE.

: Querying results from a batch job directly is not possible and will result in QDMI_ERROR_NOTSUPPORTED Instead, the results must be queried from the individual jobs after they finished. If the device supports it, each job in the batch can be queried for its status or waited for. However, in any case, individual jobs in a batch cannot be canceled and this will result in QDMI_ERROR_NOTSUPPORTED.

enumerator QDMI_PROGRAM_FORMAT_MAX¶

The maximum value of the enum.

It can be used by devices for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_PROGRAM_FORMAT_CUSTOM1¶

This enum value is reserved for a custom program format.

The device defines the meaning and the type of this value.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_PROGRAM_FORMAT_CUSTOM2¶

See also

enumerator QDMI_PROGRAM_FORMAT_CUSTOM3¶

See also

enumerator QDMI_PROGRAM_FORMAT_CUSTOM4¶

See also

enumerator QDMI_PROGRAM_FORMAT_CUSTOM5¶

See also

enum QDMI_JOB_RESULT_T¶

Enum of the formats the results can be returned in.

Values:

enumerator QDMI_JOB_RESULT_SHOTS¶: char* (string) The results of the individual shots as a comma-separated list, for example, “0010,1101,0101,1100,1001,1100” for four qubits and six shots.

enumerator QDMI_JOB_RESULT_HIST_KEYS¶

char* (string) The keys for the histogram of the results.

The histogram of the measurement results is represented as a key-value mapping. This mapping is returned as a list of keys and an equal-length list of values. The corresponding partners of keys and values can be found at the same index in the lists.

This constant denotes the list of keys, QDMI_JOB_RESULT_HIST_VALUES denotes the list of values.

enumerator QDMI_JOB_RESULT_HIST_VALUES¶

size_t* (size_t list) The values for the histogram of the results.

See also

QDMI_JOB_RESULT_HIST_KEY

enumerator QDMI_JOB_RESULT_STATEVECTOR_DENSE¶

double* (double list) The state vector of the result.

The complex amplitudes are stored as a list of real and imaginary parts. The real part of the amplitude is at index 2n and the imaginary part is at index 2n+1. For example, the state vector of a 2-qubit system with amplitudes (0.5, 0.5), (0.5, -0.5), (-0.5, 0.5), (-0.5, -0.5) would be represented as {0.5, 0.5, 0.5, -0.5, -0.5, 0.5, -0.5, -0.5}.

enumerator QDMI_JOB_RESULT_PROBABILITIES_DENSE¶

double* (double list) The probabilities of the result.

The probabilities are stored as a list of real numbers. The probability of the state with index n is at index n in the list. For example, the probabilities of a 2-qubit system with states 00, 01, 10, 11 would be represented as {0.25, 0.25, 0.25, 0.25}.

enumerator QDMI_JOB_RESULT_STATEVECTOR_SPARSE_KEYS¶

char* (string) The keys for the sparse state vector of the result.

The sparse state vector is represented as a key-value mapping. This mapping is returned as a list of keys and an equal-length list of values. The corresponding partners of keys and values can be found at the same index in the lists.

enumerator QDMI_JOB_RESULT_STATEVECTOR_SPARSE_VALUES¶

double* (double list) The values for the sparse state vector of the result.

The complex amplitudes are stored in the same way as the dense state vector, but only for the non-zero amplitudes.

enumerator QDMI_JOB_RESULT_PROBABILITIES_SPARSE_KEYS¶

char* (string) The keys for the sparse probabilities of the result.

The sparse probabilities are represented as a key-value mapping. This mapping is returned as a list of keys and an equal-length list of values. The corresponding partners of keys and values can be found at the same index in the lists.

enumerator QDMI_JOB_RESULT_PROBABILITIES_SPARSE_VALUES¶

double* (double list) The values for the sparse probabilities of the result.

The probabilities are stored in the same way as the dense probabilities, but only for the non-zero probabilities.

enumerator QDMI_JOB_RESULT_MAX¶

The maximum value of the enum.

It can be used by devices for bounds checking and validation of function parameters.

Attention: This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.

enumerator QDMI_JOB_RESULT_CUSTOM1¶

This enum value is reserved for a custom result.

The device defines the meaning and the type of this result.

Attention: The value of this enum member must not be changed to maintain binary compatibility.

enumerator QDMI_JOB_RESULT_CUSTOM2¶

See also

enumerator QDMI_JOB_RESULT_CUSTOM3¶

See also

enumerator QDMI_JOB_RESULT_CUSTOM4¶

See also

enumerator QDMI_JOB_RESULT_CUSTOM5¶

See also