QDMI Client Query Interface

Description

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

Function Documentation

QDMI_device_query_device_property()

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.

Parameters

[in]	device	The device to query. Must not be NULL.
[in]	prop	The property to query. Must be one of the values specified for QDMI_Device_Property.
[in]	size	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.
[out]	value	A pointer to the memory location where the value of the property will be stored. If this is NULL, it is ignored.
[out]	size_ret	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.

QDMI_ERROR_NOTSUPPORTED if the device does not support the property.

QDMI_ERROR_INVALIDARGUMENT if

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

QDMI_ERROR_FATAL if an unexpected error occurred.

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, 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);

QDMI_device_query_site_property()

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.

Parameters

[in]	device	The device to query. Must not be NULL.
[in]	site	The site to query. Must not be NULL.
[in]	prop	The property to query. Must be one of the values specified for QDMI_Site_Property.
[in]	size	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.
[out]	value	A pointer to the memory location where the value of the property will be stored. If this is NULL, it is ignored.
[out]	size_ret	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.

QDMI_ERROR_NOTSUPPORTED if the device does not support the property.

QDMI_ERROR_INVALIDARGUMENT if

• 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.

QDMI_ERROR_FATAL if an unexpected error occurred.

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 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);

Remarks

QDMI_Site handles may be queried via QDMI_device_query_device_property with QDMI_DEVICE_PROPERTY_SITES.

QDMI_device_query_operation_property()

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.

Parameters

[in]	device	The device to query. Must not be NULL.
[in]	operation	The operation to query. Must not be NULL.
[in]	num_sites	The number of sites that the operation is applied to.
[in]	sites	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.
[in]	num_params	The number of parameters that the operation takes.
[in]	params	A pointer to a list of parameters that the operation takes. If this is NULL, it is ignored.
[in]	prop	The property to query. Must be one of the values specified for QDMI_Operation_Property.
[in]	size	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.
[out]	value	A pointer to the memory location where the value of the property will be stored. If this is NULL, it is ignored.
[out]	size_ret	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.

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.

QDMI_ERROR_INVALIDARGUMENT if

• 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.

QDMI_ERROR_FATAL if an unexpected error occurred.

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.

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 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);

Remarks

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.

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.