Description

The QDMI Device implementation of the Qaptiva Device at Leibniz Supercomputing Centre.

Qaptiva enables enterprises and institutions to anticipate the availability of advanced quantum computers and implement real-world use cases by harnessing innovation through quantum computing technology. This device implementation allows a QDMI Client to submit quantum job, query the device information.

Note: We need to use Eviden's Python package named myQLM to submit job and connect to the device. Therefore, we obligated to use Python C API to call Python functions.

Classes
struct	QAPTIVA_QDMI_Device_Session_impl_t
	The implementation of the encapsulated type QDMI_Device_Session on the device-side. More...

struct	QAPTIVA_QDMI_Device_Job_impl_t
	Device-side implementation of the encapsulated type `QDMI_Device_Job`. More...

struct	QAPTIVA_QDMI_Site_impl_t
	The implementation of the encapsulated type QDMI_Site on the device-side. More...

Macros
#define	SCRIPT_LOCATION "QLM_AUXILIARY_SCRIPT_LOCATION"
	The definition for the auxiliary script's location.

#define	SCRIPT_NAME "QLM_AUXILIARY_SCRIPT_NAME"
	The file name of the auxiliary script.

#define	REMOTE_QPU_CREATE_FUNCTION_NAME "create_remote_qpu"
	The name of the function that used to create remote qpu.

#define	SUBMIT_JOB_FUNCTION_NAME "submit_job"
	The name of the function that used to submit quantum job.

#define	DEFAULT_NUM_SHOT 0
	The default number of the shot for a quantum job.

#define	ADD_STRING_PROPERTY(prop_name, prop_value, prop, size, value, size_ret)
	Adds a string property to the device.

#define	ADD_SINGLE_VALUE_PROPERTY(prop_name, prop_type, prop_value, prop, size, value, size_ret)
	Adds a primitive typed value property to the device.

#define	ADD_LIST_PROPERTY(prop_name, prop_type, prop_values, prop_length, prop, size, value, size_ret)
	Adds a list typed value property to the device.

#define	CHECK_PYTHON_ERROR(value, from_python)
	Checks if there is a Python related error.

#define	CHECK_QDMI_ERROR(value)
	Checks whether the `value` is `QDMI_SUCCESS`.

#define	GET_VALUE_DATA(type, multiplier)
	Writes and casts results to the `data_ptr`

Enumerations
enum	QAPTIVA_QDMI_DEVICE_SESSION_STATUS { ALLOCATED , INITIALIZED }
	Enum of the session status that can be set internally. More...

Functions
static QDMI_Device_Status *	QAPTIVA_QDMI_get_device_status (void)
	Static function to maintain the device status.

QDMI_Device_Status	QAPTIVA_QDMI_read_device_status (void)
	The local function to read the device status.

void	QAPTIVA_QDMI_set_device_status (QDMI_Device_Status status)
	The local function to set the device status.

static int *	isFromPython (void)
	Static function to check if the driver is written in Python.

static PyObject **	get_remote_qpu (void)
	Static function to get the `remote qpu`.

static PyObject **	get_custom_python_module (void)
	Static function to get the auxiliary Python Module.

int	QAPTIVA_QDMI_device_session_query_operation_property (QAPTIVA_QDMI_Device_Session session, QAPTIVA_QDMI_Operation operation, const size_t num_sites, const QAPTIVA_QDMI_Site sites, const size_t num_params, const double params, const QDMI_Operation_Property prop, const size_t size, void value, size_t size_ret)
	Queries a operation property.

int	QAPTIVA_QDMI_device_session_query_device_property (QAPTIVA_QDMI_Device_Session session, const QDMI_Device_Property prop, const size_t size, void value, size_t size_ret)
	Queries the device's properties.

int	QAPTIVA_QDMI_device_session_query_site_property (QAPTIVA_QDMI_Device_Session session, QAPTIVA_QDMI_Site site, const QDMI_Site_Property prop, const size_t size, void value, size_t size_ret)
	Query a site property.

int	QAPTIVA_QDMI_device_session_create_device_job (QAPTIVA_QDMI_Device_Session session, QAPTIVA_QDMI_Device_Job *job)
	Create a job.

int	QAPTIVA_QDMI_device_job_set_parameter (QAPTIVA_QDMI_Device_Job job, const QDMI_Device_Job_Parameter param, const size_t size, const void *value)
	Set a parameter for a job.

int	submit_job (QAPTIVA_QDMI_Device_Job job)
	An auxiliary function for submitting job.

int	QAPTIVA_QDMI_device_job_submit (QAPTIVA_QDMI_Device_Job job)
	Submit a job to the device.

int	QAPTIVA_QDMI_device_job_cancel (QAPTIVA_QDMI_Device_Job job)
	Cancel an already created job.

int	QAPTIVA_QDMI_device_job_check (QAPTIVA_QDMI_Device_Job job, QDMI_Job_Status *status)
	Check the status of a job.

int	QAPTIVA_QDMI_device_job_wait (QAPTIVA_QDMI_Device_Job job, size_t timeout)
	Wait for a job to finish.

int	QAPTIVA_QDMI_device_job_get_results (QAPTIVA_QDMI_Device_Job job, QDMI_Job_Result result, size_t size, void data, size_t size_ret)
	Retrieve the results of a job.

void	QAPTIVA_QDMI_device_job_free (QAPTIVA_QDMI_Device_Job job)
	Free a job.

int	QAPTIVA_QDMI_device_job_query_property (QAPTIVA_QDMI_Device_Job job, QDMI_Device_Job_Property prop, size_t size, void value, size_t size_ret)
	Query a job property.

int	initialize_python (void)
	Initializes the Python interpreter.

int	create_remote_qpu (const char *hostname)
	Connects to the remote qpu.

int	check_env_variable (void)
	Checks if the required environment variables are set.

int	QAPTIVA_QDMI_device_initialize (void)
	Initializes the device.

int	QAPTIVA_QDMI_device_finalize (void)
	Finalizes the device.

int	QAPTIVA_QDMI_device_session_alloc (QAPTIVA_QDMI_Device_Session *session)
	Allocates a new device session.

int	QAPTIVA_QDMI_device_session_init (QAPTIVA_QDMI_Device_Session session)
	Initializes a device session.

void	QAPTIVA_QDMI_device_session_free (QAPTIVA_QDMI_Device_Session session)
	Free a QDMI device session.

int	QAPTIVA_QDMI_device_session_set_parameter (QAPTIVA_QDMI_Device_Session session, const QDMI_Device_Session_Parameter param, const size_t size, const void *value)
	Set a parameter for a device session.

Variables
const QAPTIVA_QDMI_Site	DEVICE_SITES []
	The array of the sites.

Macro Definition Documentation

◆ SCRIPT_LOCATION

#define SCRIPT_LOCATION "QLM_AUXILIARY_SCRIPT_LOCATION"

The definition for the auxiliary script's location.

QLM_AUXILIARY_SCRIPT_LOCATION is an environment variable that corresponse to location of the qlm_auxiliary.py. In this project, it should be {PROJECT_SOURCE_DIR}/src/eviden/

◆ SCRIPT_NAME

#define SCRIPT_NAME "QLM_AUXILIARY_SCRIPT_NAME"

The file name of the auxiliary script.

QLM_AUXILIARY_SCRIPT_NAME is an environment variable that corresponse to the file name of the auxiliary script. In this project, it should be qlm_auxiliary

◆ ADD_STRING_PROPERTY

#define ADD_STRING_PROPERTY	(	prop_name,
		prop_value,
		prop,
		size,
		value,
		size_ret )

Value:

  {                                                                            \
    if ((prop) == (prop_name)) {                                               \
      if ((value) != NULL) {                                                   \
        if ((size) < strlen(prop_value) + 1) {                                 \
          return QDMI_ERROR_INVALIDARGUMENT;                                   \
        }                                                                      \
        strncpy((char *)(value), prop_value, (size) - 1);                      \
        ((char *)(value))[(size) - 1] = '\0';                                  \
      }                                                                        \
      if ((size_ret) != NULL) {                                                \
        *(size_ret) = strlen(prop_value) + 1;                                  \
      }                                                                        \
      return QDMI_SUCCESS;                                                     \
    }                                                                          \
  }

Adds a string property to the device.

This macro copies the value of the prop_value to the value if prop_name and the prop matches. If specified, the required size is written in size_ret.

Parameters

prop_name	The name of the property
prop_value	The string value of the property (`char*`)
prop	The property name passed as input
size	The size of the memory pointed to by `value`.
value	Pointer to the memory location where `prop_value` will be copied.
size_ret	If specified, the required size is written.

Returns: If successful, QDMI_SUCCESS. If the size is not sufficient, QDMI_ERROR_INVALIDARGUMENT

Note: This value is taken adapted from the example C device in the QDMI repository.

◆ ADD_SINGLE_VALUE_PROPERTY

#define ADD_SINGLE_VALUE_PROPERTY	(	prop_name,
		prop_type,
		prop_value,
		prop,
		size,
		value,
		size_ret )

Value:

  {                                                                            \
    if ((prop) == (prop_name)) {                                               \
      if ((value) != NULL) {                                                   \
        if ((size) < sizeof(prop_type)) {                                      \
          return QDMI_ERROR_INVALIDARGUMENT;                                   \
        }                                                                      \
        *(prop_type *)(value) = prop_value;                                    \
      }                                                                        \
      if ((size_ret) != NULL) {                                                \
        *(size_ret) = sizeof(prop_type);                                       \
      }                                                                        \
      return QDMI_SUCCESS;                                                     \
    }                                                                          \
  }

Adds a primitive typed value property to the device.

This macro copies the value of the prop_value to the value if prop_name and the prop matches. If specified, the required size is written in size_ret.

Parameters

prop_name	The name of the property
prop_type	The type of the property, i.e, `char`, `ìnt`.
prop_value	The value of the property.
prop	The property name passed as input
size	The size of the memory pointed to by `value`.
value	Pointer to the memory location where `prop_value` will be copied.
size_ret	If specified, the required size is written.

Returns: If successful, QDMI_SUCCESS. If the size is not sufficient, QDMI_ERROR_INVALIDARGUMENT

Note: This value is taken adapted from the example C device in the QDMI repository.

◆ ADD_LIST_PROPERTY

#define ADD_LIST_PROPERTY	(	prop_name,
		prop_type,
		prop_values,
		prop_length,
		prop,
		size,
		value,
		size_ret )

Value:

  {                                                                            \
    if ((prop) == (prop_name)) {                                               \
      if ((value) != NULL) {                                                   \
        if ((size) < (prop_length) * sizeof(prop_type)) {                      \
          return QDMI_ERROR_INVALIDARGUMENT;                                   \
        }                                                                      \
        memcpy((void *)(value), (const void *)(prop_values),                   \
               (prop_length) * sizeof(prop_type));                             \
      }                                                                        \
      if ((size_ret) != NULL) {                                                \
        *(size_ret) = (prop_length) * sizeof(prop_type);                       \
      }                                                                        \
      return QDMI_SUCCESS;                                                     \
    }                                                                          \
  }

Adds a list typed value property to the device.

This macro copies the value of the prop_value to the value if prop_name and the prop matches. If specified, the required size is written in size_ret.

Parameters

prop_name	The name of the property
prop_type	The type of the property, i.e, `double`, `ìnt`.
prop_values	The values of the property.
prop	The property name passed as input
size	The size of the memory pointed to by `value`.
value	Pointer to the memory location where `prop_value` will be copied.
size_ret	If specified, the required size is written.

Returns: If successful, QDMI_SUCCESS. If the size is not sufficient, QDMI_ERROR_INVALIDARGUMENT

Note: This value is taken adapted from the example C device in the QDMI repository.

◆ CHECK_PYTHON_ERROR

#define CHECK_PYTHON_ERROR	(		value,
			from_python )

Value:

  {                                                                            \
    if (value == Py_None || value == NULL) {                                   \
                                                                               \
      PyErr_Print();                                                           \
      if (!from_python) {                                                      \
        PyGILState_Release(gstate);                                            \
      }                                                                        \
      QAPTIVA_QDMI_set_device_status(QDMI_DEVICE_STATUS_IDLE);                     \
      return QDMI_ERROR_FATAL;                                                 \
    }                                                                          \
  }

Checks if there is a Python related error.

This macro checks whether the valueis NULL or Py_None. If it is, it returns the ret_val.

Parameters

value	The value to be checked
from_python	True means that the `QDMI_Driver` that initiate the device is written in Python. Therefore, we don't need to release the GIL.

Returns: if the valueis NULL or Py_None, it returns the ret_val

◆ CHECK_QDMI_ERROR

#define CHECK_QDMI_ERROR ( value )

Value:

  {                                                                            \
    if (value != QDMI_SUCCESS) {                                               \
      return value;                                                            \
    }                                                                          \
  }

Checks whether the value is QDMI_SUCCESS.

Parameters

value The value to be checked

Returns: value if it is not QDMI_SUCCESS

◆ GET_VALUE_DATA

#define GET_VALUE_DATA	(		type,
			multiplier )

Value:

  {                                                                            \
    required_size = job->results_size * sizeof(type);                          \
    if (data) {                                                                \
      if (size < required_size)                                                \
        return QDMI_ERROR_INVALIDARGUMENT;                                     \
      type *data_ptr = data;                                                   \
      int max_index = (int)(size / sizeof(type));                              \
      for (int index = 0; index < max_index; index++) {                        \
        *data_ptr++ = (type)(job->probability_values[index] * multiplier);     \
      }                                                                        \
    }                                                                          \
    if (size_ret)                                                              \
      *size_ret = required_size;                                               \
    return QDMI_SUCCESS;                                                       \
  }

Writes and casts results to the data_ptr

Parameters

type	The type to results will be cast.
multiplier	The value that results will be multiplied by

Returns: QDMI_SUCCESS

Enumeration Type Documentation

◆ QAPTIVA_QDMI_DEVICE_SESSION_STATUS

enum QAPTIVA_QDMI_DEVICE_SESSION_STATUS

Enum of the session status that can be set internally.

See also: QAPTIVA_QDMI_device_session_alloc; QAPTIVA_QDMI_device_session_init

Enumerator
ALLOCATED	The session is allocated but not yet initialized.
INITIALIZED	The session is successfully initialized.

Function Documentation

◆ QAPTIVA_QDMI_get_device_status()

static QDMI_Device_Status * QAPTIVA_QDMI_get_device_status ( void )

static

Static function to maintain the device status.

Returns: A pointer to the device status.

Note: This function should not be used outside of this file. Therefore, it is not part of any header file.

◆ QAPTIVA_QDMI_read_device_status()

QDMI_Device_Status QAPTIVA_QDMI_read_device_status ( void )

The local function to read the device status.

Returns: The current device status.

Note: This function should not be used outside of this file. Therefore, it is not part of any header file.

◆ QAPTIVA_QDMI_set_device_status()

void QAPTIVA_QDMI_set_device_status ( QDMI_Device_Status status )

The local function to set the device status.

Parameters

status the new device status.

Note: This function should not be used outside of this file. Therefore, it is not part of any header file.

◆ isFromPython()

static int * isFromPython ( void )

static

Static function to check if the driver is written in Python.

Returns: A pointer to the value. 1 if written in Python. Otherwise, 0

Note: This function should not be used outside of this file. Therefore, it is not part of any header file.

◆ get_remote_qpu()

static PyObject ** get_remote_qpu ( void )

static

Static function to get the remote qpu.

The remote qpu is created while initialting the session and re-used while submitting jobs.

Returns: The remote qpu pointer if it is created. Otherwise, NULL;

See also: submit_job; create_remote_qpu

◆ get_custom_python_module()

static PyObject ** get_custom_python_module ( void )

static

Static function to get the auxiliary Python Module.

The auxiliary Python Module is frequintly used thoughtout the backend after it is imported while initialting the session.

Returns: The custom python module pointer if it is created. Otherwise, NULL;

See also: create_remote_qpu; submit_job; initialize_python

◆ QAPTIVA_QDMI_device_session_query_operation_property()

int QAPTIVA_QDMI_device_session_query_operation_property	(	QAPTIVA_QDMI_Device_Session	session,
		QAPTIVA_QDMI_Operation	operation,
		const size_t	num_sites,
		const QAPTIVA_QDMI_Site *	sites,
		const size_t	num_params,
		const double *	params,
		const QDMI_Operation_Property	prop,
		const size_t	size,
		void *	value,
		size_t *	size_ret )

Queries a operation property.

Since it is a emulator, there is no native gate set.

Parameters

[in]	session	The session used for the query.
[in]	operation	The operation to query.
[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.
[in]	num_params	The number of parameters that the operation takes.
[in]	params	A pointer to a list of parameters the operation takes.
[in]	prop	The property to query.
[in]	size	The size of the memory pointed to by `value` in bytes.
[out]	value	A pointer to the memory location where the value of the property will be stored.
[out]	size_ret	The actual size of the data being queried in bytes.

Returns: QDMI_ERROR_NOTSUPPORTED.

◆ QAPTIVA_QDMI_device_session_query_device_property()

int QAPTIVA_QDMI_device_session_query_device_property	(	QAPTIVA_QDMI_Device_Session	session,
		const QDMI_Device_Property	prop,
		const size_t	size,
		void *	value,
		size_t *	size_ret )

Queries the device's properties.

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 is 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 the value is not NULL, the property was successfully retrieved.

QDMI_ERROR_NOTSUPPORTED if the device does not support the property.

QDMI_ERROR_INVALIDARGUMENT if

the session is NULL,
the prop is invalid, or
the value is not NULL and the 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.

See also: ADD_STRING_PROPERTY; ADD_SINGLE_VALUE_PROPERTY; ADD_LIST_PROPERTY

◆ QAPTIVA_QDMI_device_session_query_site_property()

int QAPTIVA_QDMI_device_session_query_site_property	(	QAPTIVA_QDMI_Device_Session	session,
		QAPTIVA_QDMI_Site	site,
		const QDMI_Site_Property	prop,
		const size_t	size,
		void *	value,
		size_t *	size_ret )

Query a site property.

The Qaptiva device's QDMI_Sites only has indexes. Therefore, only their indexes can be queried.

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.

◆ QAPTIVA_QDMI_device_session_create_device_job()

int QAPTIVA_QDMI_device_session_create_device_job	(	QAPTIVA_QDMI_Device_Session	session,
		QAPTIVA_QDMI_Device_Job *	job )

Create a job.

This is the main entry point for a driver to create a job for a device. After the required memory is allocated, the job is initiaited

Parameters

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

Returns: QDMI_SUCCESS if the job was successfully created.; QDMI_ERROR_INVALIDARGUMENT if session or job are NULL.

See also: QAPTIVA_QDMI_device_job_submit; QAPTIVA_QDMI_device_job_set_parameter; QAPTIVA_QDMI_device_job_cancel; QAPTIVA_QDMI_device_job_check; QAPTIVA_QDMI_device_job_wait; QAPTIVA_QDMI_device_job_get_results; QAPTIVA_QDMI_device_job_free

◆ QAPTIVA_QDMI_device_job_set_parameter()

int QAPTIVA_QDMI_device_job_set_parameter	(	QAPTIVA_QDMI_Device_Job	job,
		const QDMI_Device_Job_Parameter	param,
		const size_t	size,
		const void *	value )

Set a parameter for a job.

Parameters

[in]	job	A handle to a job for which to set `param`. Must not be `NULL`.
[in]	param	The parameter whose value will be set. Must be one of the values specified for QDMI_Device_Job_Parameter.
[in]	size	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.
[in]	value	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.

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

QDMI_ERROR_INVALIDARGUMENT if

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

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

See also: QAPTIVA_QDMI_device_job_submit; QAPTIVA_QDMI_device_job_set_parameter; QAPTIVA_QDMI_device_job_cancel; QAPTIVA_QDMI_device_job_check; QAPTIVA_QDMI_device_job_wait; QAPTIVA_QDMI_device_job_get_results; QAPTIVA_QDMI_device_job_free

◆ submit_job()

int submit_job ( QAPTIVA_QDMI_Device_Job job )

An auxiliary function for submitting job.

Parameters

[in] job A handle to a job to be submitted

To submit a job this device, we need to use Qaptiva's Python Package named myQLM. Therefore, this function calls the submit_job from the qlm_auxiliary to submit the given job.

See also: QAPTIVA_QDMI_device_job_submit

Returns: QDMI_SUCCESS if the job submitted successfully; QDMI_ERROR_FATAL if an error occur

◆ QAPTIVA_QDMI_device_job_submit()

int QAPTIVA_QDMI_device_job_submit ( QAPTIVA_QDMI_Device_Job job )

Submit a job to the device.

To submit a job this device, we need to use Qaptiva's Python Package named myQLM. The out-of-the box job submission function is a blocking-function that waits

Parameters

[in] job The job to submit. Must not be NULL.

Returns: QDMI_SUCCESS if the job was successfully submitted.; QDMI_ERROR_INVALIDARGUMENT if job is NULL.; QDMI_ERROR_FATAL if the job submission failed.

See also: submit_job; QAPTIVA_QDMI_device_session_create_device_job; QAPTIVA_QDMI_device_job_set_parameter; QAPTIVA_QDMI_device_job_cancel; QAPTIVA_QDMI_device_job_check; QAPTIVA_QDMI_device_job_wait; QAPTIVA_QDMI_device_job_get_results; QAPTIVA_QDMI_device_job_free

◆ QAPTIVA_QDMI_device_job_cancel()

int QAPTIVA_QDMI_device_job_cancel ( QAPTIVA_QDMI_Device_Job job )

Cancel an already created job.

The submitted jobs cannot be canceled due to nature of the device. Therefore, we can only cancel the created jobs.

Parameters

[in] job The job to cancel. Must not be NULL.

Returns: QDMI_SUCCESS if the job was successfully canceled.; QDMI_ERROR_INVALIDARGUMENT if job is NULL or the job already has the status QDMI_JOB_STATUS_DONE.; QDMI_ERROR_FATAL if the job could not be canceled.

See also: QAPTIVA_QDMI_device_session_create_device_job; QAPTIVA_QDMI_device_job_submit; QAPTIVA_QDMI_device_job_set_parameter; QAPTIVA_QDMI_device_job_check; QAPTIVA_QDMI_device_job_wait; QAPTIVA_QDMI_device_job_get_results; QAPTIVA_QDMI_device_job_free

◆ QAPTIVA_QDMI_device_job_check()

int QAPTIVA_QDMI_device_job_check	(	QAPTIVA_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.

Parameters

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

Returns: QDMI_SUCCESS if the job status was successfully checked.; QDMI_ERROR_INVALIDARGUMENT if job or status is NULL.; QDMI_ERROR_FATAL if the job status could not be checked.

◆ QAPTIVA_QDMI_device_job_wait()

int QAPTIVA_QDMI_device_job_wait	(	QAPTIVA_QDMI_Device_Job	job,
		size_t	timeout )

Wait for a job to finish.

Since QAPTIVA_QDMI_device_job_submit is a blocking function, this function makes sure that status is set to QDMI_JOB_STATUS_DONE.

Parameters

[in]	job	The job to wait for. Must not be `NULL`.
[in]	timeout	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.; QDMI_ERROR_INVALIDARGUMENT if job is NULL.; QDMI_ERROR_FATAL if the job could not be waited for and this function returns before the job has finished or has been canceled.

◆ QAPTIVA_QDMI_device_job_get_results()

int QAPTIVA_QDMI_device_job_get_results	(	QAPTIVA_QDMI_Device_Job	job,
		QDMI_Job_Result	result,
		size_t	size,
		void *	data,
		size_t *	size_ret )

Retrieve the results of a job.

The QLM device returns the results as a state-probability pair. Therefore, this function provides the probability values, keys, and density, as well as the histogram keys and values, which are calculated by multiplying the probability values by the number of shots.

Parameters

[in]	job	The job to retrieve the results from. Must not be `NULL`.
[in]	result	The result to retrieve. Must be one of the values specifie for QDMI_Job_Result
[in]	size	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.
[out]	data	A pointer to the memory location where the results 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 result and, when data is not NULL, the results were successfully retrieved.

QDMI_ERROR_INVALIDARGUMENT if

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

◆ QAPTIVA_QDMI_device_job_free()

void QAPTIVA_QDMI_device_job_free ( QAPTIVA_QDMI_Device_Job job )

Free a job.

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

Parameters

[in] job The job to free.

◆ QAPTIVA_QDMI_device_job_query_property()

int QAPTIVA_QDMI_device_job_query_property	(	QAPTIVA_QDMI_Device_Job	job,
		QDMI_Device_Job_Property	prop,
		size_t	size,
		void *	value,
		size_t *	size_ret )

Query a job property.

Parameters

[in]	job	A handle to a job for which to query `prop`. Must not be `NULL`.
[in]	prop	The property to query. Must be one of the values specified for a href="https://munich-quantum-software-stack.github.io/QDMI/constants_8h.html#a6e4d18c7fa5d383bbcc1498abe090d4f">QDMI_Device_Job_Property `result`, except when `data` is `NULL`, in which case it is ignored..
[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 job supports the specified property and, when value is not NULL, the property was successfully retrieved.

QDMI_ERROR_NOTSUPPORTED. if the job does not support the property.

QDMI_ERROR_INVALIDARGUMENT if

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

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.

QDMI_ERROR_FATAL if an unexpected error occurred.

◆ initialize_python()

int initialize_python ( void )

Initializes the Python interpreter.

Since we are obligated to use myQLM Python package, we need to initialize the interpreter. However, if the library is used by a Python based client, the interpreter does not need to be initialized.

This function initializes the Python interpreter and imports the custom auxiliary module which is named qlm_auxiliary.py by default. The module is used in create_remote_qpu and submit_job.

Returns: QDMI_ERROR_FATAL if the python interpreter cannot be initialized .; QDMI_SUCCESS if the python interpreter is successfully initialized.

◆ create_remote_qpu()

int create_remote_qpu ( const char * hostname )

Connects to the remote qpu.

This function is connects to the remote qpu by using the create_remote_qpu function from the qlm_auxiliary.

Parameters

[in] hostname The name of the host where the device is located. Must be in the form "host:port".

Returns: QDMI_ERROR_FATAL if the connection faills.; QDMI_SUCCESS if the connection success.

◆ check_env_variable()

int check_env_variable ( void )

Checks if the required environment variables are set.

Two environment variables needs to be set to locate the custom auxiliary module: SCRIPT_LOCATION indicates the location of the file and SCRIPT_NAME indicates the name of the file.

Returns: returns QDMI_ERROR_FATAL if either one is NULL.; returns QDMI_SUCCESS if both is set.

◆ QAPTIVA_QDMI_device_initialize()

int QAPTIVA_QDMI_device_initialize ( void )

Initializes the device.

This function check if the required environment variables are set and the Python interpreter can be initialized.

Returns: QDMI_ERROR_FATAL if the environment variables are null or Python interpreter cannot be initialized.; QDMI_SUCCESS if the device succuessly is initialized.

◆ QAPTIVA_QDMI_device_finalize()

int QAPTIVA_QDMI_device_finalize ( void )

Finalizes the device.

This function finalizes the device by freeing the custom module, and finalizesthe Python interpreter.

Returns: QDMI_SUCCESS if the device succuessly is finalized.

◆ QAPTIVA_QDMI_device_session_alloc()

int QAPTIVA_QDMI_device_session_alloc ( QAPTIVA_QDMI_Device_Session * session )

Allocates a new device session.

Parameters

[out] session A handle to the session that is allocated. Must not be NULL.

Returns: QDMI_SUCCESS if the session was allocated successfully.; QDMI_ERROR_INVALIDARGUMENT if session is NULL.

See also: QDMI_device_session_set_parameter; QDMI_device_session_init

◆ QAPTIVA_QDMI_device_session_init()

int QAPTIVA_QDMI_device_session_init ( QAPTIVA_QDMI_Device_Session session )

Initializes a device session.

This function initializes the device session and prepares it for use based on the set parameters.

Parameters

[out] session A handle to the session that is allocated.

Returns: QDMI_SUCCESS if the session was allocated successfully.; QDMI_ERROR_INVALIDARGUMENT if session is NULL.; QDMI_ERROR_FATAL if the device's status is QDMI_DEVICE_STATUS_ERROR or QDMI_DEVICE_STATUS_OFFLINE or QDMI_DEVICE_STATUS_MAINTENANCE

See also: QAPTIVA_QDMI_device_session_alloc; QDMI_device_session_set_parameter

◆ QAPTIVA_QDMI_device_session_free()

void QAPTIVA_QDMI_device_session_free ( QAPTIVA_QDMI_Device_Session session )

Free a QDMI device session.

Parameters

[in] session The session to free.

◆ QAPTIVA_QDMI_device_session_set_parameter()

int QAPTIVA_QDMI_device_session_set_parameter	(	QAPTIVA_QDMI_Device_Session	session,
		const QDMI_Device_Session_Parameter	param,
		const size_t	size,
		const void *	value )

Set a parameter for a device session.

Parameters

[in]	session	A handle to the session to set the parameter for.
[in]	param	The parameter to set. Must be one of the values specified for QDMI_Device_Session_Parameter.
[in]	size	The size of the data pointed by `value` in bytes.
[in]	value	A pointer to the memory location that contains the value of the parameter to be set.

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.

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

QDMI_ERROR_INVALIDARGUMENT if

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

QDMI_ERROR_BADSTATE if the parameter cannot be set in the current state of the session.

See also: QAPTIVA_QDMI_device_session_alloc; QDMI_device_session_init

Variable Documentation

◆ DEVICE_SITES

const QAPTIVA_QDMI_Site DEVICE_SITES[]

Initial value:

= {
    &(QAPTIVA_QDMI_Site_impl_t){0},  &(QAPTIVA_QDMI_Site_impl_t){1},
    &(QAPTIVA_QDMI_Site_impl_t){2},  &(QAPTIVA_QDMI_Site_impl_t){3},
    &(QAPTIVA_QDMI_Site_impl_t){4},  &(QAPTIVA_QDMI_Site_impl_t){5},
    &(QAPTIVA_QDMI_Site_impl_t){6},  &(QAPTIVA_QDMI_Site_impl_t){7},
    &(QAPTIVA_QDMI_Site_impl_t){8},  &(QAPTIVA_QDMI_Site_impl_t){9},
    &(QAPTIVA_QDMI_Site_impl_t){10}, &(QAPTIVA_QDMI_Site_impl_t){11},
    &(QAPTIVA_QDMI_Site_impl_t){12}, &(QAPTIVA_QDMI_Site_impl_t){13},
    &(QAPTIVA_QDMI_Site_impl_t){14}, &(QAPTIVA_QDMI_Site_impl_t){15},
    &(QAPTIVA_QDMI_Site_impl_t){16}, &(QAPTIVA_QDMI_Site_impl_t){17},
    &(QAPTIVA_QDMI_Site_impl_t){18}, &(QAPTIVA_QDMI_Site_impl_t){19},
    &(QAPTIVA_QDMI_Site_impl_t){20}, &(QAPTIVA_QDMI_Site_impl_t){21},
    &(QAPTIVA_QDMI_Site_impl_t){22}, &(QAPTIVA_QDMI_Site_impl_t){23},
    &(QAPTIVA_QDMI_Site_impl_t){24}, &(QAPTIVA_QDMI_Site_impl_t){25},
    &(QAPTIVA_QDMI_Site_impl_t){26}, &(QAPTIVA_QDMI_Site_impl_t){27},
    &(QAPTIVA_QDMI_Site_impl_t){28}, &(QAPTIVA_QDMI_Site_impl_t){29},
    &(QAPTIVA_QDMI_Site_impl_t){30}, &(QAPTIVA_QDMI_Site_impl_t){31},
    &(QAPTIVA_QDMI_Site_impl_t){32}, &(QAPTIVA_QDMI_Site_impl_t){33},
    &(QAPTIVA_QDMI_Site_impl_t){34}, &(QAPTIVA_QDMI_Site_impl_t){35},
    &(QAPTIVA_QDMI_Site_impl_t){36}, &(QAPTIVA_QDMI_Site_impl_t){37},
 
}

The array of the sites.

Description

Classes

Macros

Enumerations

Functions

Variables

Macro Definition Documentation

◆ SCRIPT_LOCATION

◆ SCRIPT_NAME

◆ ADD_STRING_PROPERTY

◆ ADD_SINGLE_VALUE_PROPERTY

◆ ADD_LIST_PROPERTY

◆ CHECK_PYTHON_ERROR

◆ CHECK_QDMI_ERROR

◆ GET_VALUE_DATA

Enumeration Type Documentation

◆ QAPTIVA_QDMI_DEVICE_SESSION_STATUS

Function Documentation

◆ QAPTIVA_QDMI_get_device_status()

◆ QAPTIVA_QDMI_read_device_status()

◆ QAPTIVA_QDMI_set_device_status()

◆ isFromPython()

◆ get_remote_qpu()

◆ get_custom_python_module()

◆ QAPTIVA_QDMI_device_session_query_operation_property()

◆ QAPTIVA_QDMI_device_session_query_device_property()

◆ QAPTIVA_QDMI_device_session_query_site_property()

◆ QAPTIVA_QDMI_device_session_create_device_job()

◆ QAPTIVA_QDMI_device_job_set_parameter()

◆ submit_job()

◆ QAPTIVA_QDMI_device_job_submit()

◆ QAPTIVA_QDMI_device_job_cancel()

◆ QAPTIVA_QDMI_device_job_check()

◆ QAPTIVA_QDMI_device_job_wait()

◆ QAPTIVA_QDMI_device_job_get_results()

◆ QAPTIVA_QDMI_device_job_free()

◆ QAPTIVA_QDMI_device_job_query_property()

◆ initialize_python()

◆ create_remote_qpu()

◆ check_env_variable()

◆ QAPTIVA_QDMI_device_initialize()

◆ QAPTIVA_QDMI_device_finalize()

◆ QAPTIVA_QDMI_device_session_alloc()

◆ QAPTIVA_QDMI_device_session_init()

◆ QAPTIVA_QDMI_device_session_free()

◆ QAPTIVA_QDMI_device_session_set_parameter()

Variable Documentation

◆ DEVICE_SITES