QDMI Client Job Interface

Description

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.

Typedefs
typedef struct QDMI_Job_impl_d *	QDMI_Job
	A handle for a client-side job.
typedef enum QDMI_JOB_PARAMETER_T	QDMI_Job_Parameter
	Job parameter type.

Enumerations
enum	QDMI_JOB_PARAMETER_T {   QDMI_JOB_PARAMETER_PROGRAMFORMAT = 0 , QDMI_JOB_PARAMETER_PROGRAM = 1 , QDMI_JOB_PARAMETER_SHOTSNUM = 2 , QDMI_JOB_PARAMETER_MAX = 3 ,   QDMI_JOB_PARAMETER_CUSTOM1 = 999999995 , QDMI_JOB_PARAMETER_CUSTOM2 = 999999996 , QDMI_JOB_PARAMETER_CUSTOM3 = 999999997 , QDMI_JOB_PARAMETER_CUSTOM4 = 999999998 ,   QDMI_JOB_PARAMETER_CUSTOM5 = 999999999 }
	Enum of the job parameters that can be set. More...

Functions
int	QDMI_device_create_job (QDMI_Device device, QDMI_Job *job)
	Create a job.
int	QDMI_job_set_parameter (QDMI_Job job, QDMI_Job_Parameter param, size_t size, const void *value)
	Set a parameter for a job.
int	QDMI_job_submit (QDMI_Job job)
	Submit a job to the device.
int	QDMI_job_cancel (QDMI_Job job)
	Cancel an already submitted job.
int	QDMI_job_check (QDMI_Job job, QDMI_Job_Status *status)
	Check the status of a job.
int	QDMI_job_wait (QDMI_Job job)
	Wait for a job to finish.
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.
void	QDMI_job_free (QDMI_Job job)
	Free a job.

Typedef Documentation

QDMI_Job

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.

Remarks

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.

Enumeration Type Documentation

QDMI_JOB_PARAMETER_T

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.

Enumerator
QDMI_JOB_PARAMETER_PROGRAMFORMAT	0	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.
QDMI_JOB_PARAMETER_PROGRAM	1	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.
QDMI_JOB_PARAMETER_SHOTSNUM	2	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.
QDMI_JOB_PARAMETER_MAX	3	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.
QDMI_JOB_PARAMETER_CUSTOM1	999999995	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.
QDMI_JOB_PARAMETER_CUSTOM2	999999996	See also QDMI_JOB_PARAMETER_CUSTOM1
QDMI_JOB_PARAMETER_CUSTOM3	999999997	See also QDMI_JOB_PARAMETER_CUSTOM1
QDMI_JOB_PARAMETER_CUSTOM4	999999998	See also QDMI_JOB_PARAMETER_CUSTOM1
QDMI_JOB_PARAMETER_CUSTOM5	999999999	See also QDMI_JOB_PARAMETER_CUSTOM1

Function Documentation

QDMI_device_create_job()

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

[in]	device	The device to create the job on. Must not be NULL.
[out]	job	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.

QDMI_ERROR_INVALIDARGUMENT if device or job are NULL.

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

QDMI_ERROR_FATAL if job creation failed due to a fatal error.

QDMI_job_set_parameter()

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

QDMI_ERROR_NOTSUPPORTED if the driver 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_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.

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

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

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

QDMI_job_submit()

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

[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_BADSTATE if the job is in an invalid state.

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

QDMI_ERROR_FATAL if the job submission failed.

QDMI_job_cancel()

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

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

QDMI_ERROR_FATAL if the job could not be canceled.

QDMI_job_check()

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

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

QDMI_ERROR_FATAL if the job status could not be checked.

QDMI_job_wait()

int QDMI_job_wait

(

QDMI_Job

job

)

Wait for a job to finish.

This function blocks until the job has either finished or has been canceled.

Parameters

[in]

job

The job to wait for. Must not be NULL.

Returns

QDMI_SUCCESS if the job is finished or canceled.

QDMI_ERROR_INVALIDARGUMENT if job is NULL.

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

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

QDMI_job_get_results()

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.

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 specified 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 finished,
• job was canceled,
• result is invalid, or
• data is not NULL and size is smaller than the size of the data being queried.

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

QDMI_ERROR_FATAL if an error occurred during the retrieval.

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

QDMI_job_free()

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.

Parameters

[in]

job

The job to free.