QDMI Device Query Interface

Description

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

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

Function Documentation

QDMI_device_session_query_device_property()

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.

Parameters

[in]	session	The session used for the 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

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

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

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

Attention

May only be called after the session has been initialized with QDMI_device_session_init.

QDMI_device_session_query_site_property()

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.

Parameters

[in]	session	The session used for the 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

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

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

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

Attention

May only be called after the session has been initialized with QDMI_device_session_init.

QDMI_device_session_query_operation_property()

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.

Parameters

[in]	session	The session used for the 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 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 property is not supported by the device or if the queried property cannot be provided for the given sites or parameters.

QDMI_ERROR_INVALIDARGUMENT if

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

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

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

Attention

May only be called after the session has been initialized with QDMI_device_session_init.