QDMI Device Job Interface

Description

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 QDMI_device_session_create_device_job.
• Set programs with QDMI_device_job_set_programs and other parameters 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 each program's results 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 QDMI_Device_Job_impl_d *	QDMI_Device_Job
	A handle for a device job.

Functions
int	QDMI_device_session_create_device_job (QDMI_Device_Session session, QDMI_Device_Job *job)
	Create a job.
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.
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.
int	QDMI_device_job_set_programs (QDMI_Device_Job job, QDMI_Program_Format format, size_t count, const size_t *sizes, const void *const *programs)
	Set one or more programs for a job.
int	QDMI_device_job_get_program (QDMI_Device_Job job, size_t program_index, size_t size, void *data, size_t *size_ret)
	Retrieve one program in input order.
int	QDMI_device_job_get_program_status (QDMI_Device_Job job, size_t program_index, QDMI_Job_Status *status)
	Query the current status of one program in a device job.
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.
int	QDMI_device_job_submit (QDMI_Device_Job job)
	Submit a job to the device.
int	QDMI_device_job_cancel (QDMI_Device_Job job)
	Cancel an already submitted job.
int	QDMI_device_job_check (QDMI_Device_Job job, QDMI_Job_Status *status)
	Check the status of a job.
int	QDMI_device_job_wait (QDMI_Device_Job job, size_t timeout)
	Wait for a job to finish.
int	QDMI_device_job_get_results (QDMI_Device_Job job, size_t program_index, QDMI_Job_Result result, size_t size, void *data, size_t *size_ret)
	Retrieve one program's results from a job.
void	QDMI_device_job_free (QDMI_Device_Job job)
	Free a job.

Typedef Documentation

QDMI_Device_Job

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.

Remarks

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.

Function Documentation

QDMI_device_session_create_device_job()

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.

Parameters

[in]	session	The session 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_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.

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.

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

QDMI_ERROR_FATAL if job creation failed due to a fatal error.

Attention

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

QDMI_device_session_retrieve_device_job_by_id()

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.

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. The device must reconstruct the program count and input-to-result mapping. If historical input metadata is unavailable, queries for the original format or program bytes may return QDMI_ERROR_NOTSUPPORTED without preventing retrieval.

Parameters

[in]	session	The initialized session with which to retrieve the job. Must not be NULL.
[in]	job_id	The nonempty, null-terminated ID returned by QDMI_DEVICE_JOB_PROPERTY_ID. Must not be NULL.
[out]	job	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.

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

QDMI_ERROR_NOTSUPPORTED if the device does not support retrieving existing jobs or cannot reconstruct the program count and result-index mapping.

QDMI_ERROR_NOTFOUND if no accessible job with job_id exists.

QDMI_ERROR_BADSTATE if session is not initialized.

QDMI_ERROR_PERMISSIONDENIED if session is not permitted to access the job.

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

QDMI_device_job_set_parameter()

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.

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.

QDMI_ERROR_OUTOFMEM if a parameter value cannot be copied.

QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for 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 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 = 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);

QDMI_device_job_set_programs()

int QDMI_device_job_set_programs	(	QDMI_Device_Job	job,
		QDMI_Program_Format	format,
		size_t	count,
		const size_t *	sizes,
		const void *const *	programs )

Set one or more programs for a job.

All programs use the same format and the same job parameters, including the shot count. On success, the device replaces the complete program list with a deep copy of sizes and the program bytes. If validation or copying fails, the existing program list remains unchanged. A device that accepts a list must report its size through QDMI_DEVICE_JOB_PROPERTY_PROGRAMSNUM and expose each result through QDMI_device_job_get_results. A result's index equals its input program's index; execution order is unspecified. The list has one ID, status, wait operation, and cancellation operation. The job reaches QDMI_JOB_STATUS_DONE only after all programs succeed. Failed or canceled jobs become terminal only after all programs have stopped. Optional per-program outcomes are available through QDMI_device_job_get_program_status; results of successful programs remain accessible when other programs fail or are canceled.

Parameters

[in]	job	A handle to the job. Must not be NULL.
[in]	format	The exact format of every program. Must be a valid QDMI_Program_Format, including for a single program.
[in]	count	The number of programs. Must be greater than zero. A support check succeeds only if the device supports this exact cardinality with the configured job parameters.
[in]	sizes	An array of count program sizes in bytes. Must not be NULL and each size must be greater than zero when programs is not NULL. A text program contains exactly one '\0' as its final byte. Binary programs are arbitrary nonempty byte sequences. When programs is NULL, sizes is ignored.
[in]	programs	An array of count program pointers. When the array is not NULL, each pointer must not be NULL. The device copies all input data before returning. If the array is NULL, the function checks support for the format and cardinality without changing the job.

Returns

QDMI_SUCCESS if the device supports the count in format and, when programs is not NULL, set the complete list.

QDMI_ERROR_INVALIDARGUMENT if

• job is NULL, count is zero, or format is not valid, or
• the device supports program lists, programs is not NULL, and sizes is NULL, an element of programs is NULL, an element of sizes is zero, or a text program does not contain exactly one trailing '\0'.

QDMI_ERROR_NOTSUPPORTED if the arguments are valid but the device cannot accept the format, count, or programs with the configured job parameters. Reserved numeric values of removed formats also return QDMI_ERROR_NOTSUPPORTED.

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

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

QDMI_ERROR_OUTOFMEM if the device cannot copy the program list.

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

QDMI_device_job_get_program()

int QDMI_device_job_get_program	(	QDMI_Device_Job	job,
		size_t	program_index,
		size_t	size,
		void *	data,
		size_t *	size_ret )

Retrieve one program in input order.

The returned bytes include the terminating NUL for text formats. A retrieved job may return QDMI_ERROR_NOTSUPPORTED when its original program bytes are unavailable. The program count is reported by QDMI_DEVICE_JOB_PROPERTY_PROGRAMSNUM.

Parameters

[in]	job	The job to query. Must not be NULL.
[in]	program_index	The zero-based program index.
[in]	size	The size of data in bytes. Ignored if data is NULL.
[out]	data	The buffer for the program bytes, or NULL for a size query.
[out]	size_ret	The required buffer size, or NULL.

Returns

QDMI_SUCCESS if the program bytes were copied, or their size was returned when data is NULL.

QDMI_ERROR_NOTSUPPORTED if the original program is unavailable.

QDMI_ERROR_BADSTATE if no program list has been set.

QDMI_ERROR_OUTOFRANGE if program_index is out of range.

QDMI_ERROR_INVALIDARGUMENT if job is NULL or data is non-NULL and size is too small.

QDMI_ERROR_PERMISSIONDENIED if the session cannot access jobs.

QDMI_ERROR_FATAL if an unexpected error occurred.

QDMI_device_job_get_program_status()

int QDMI_device_job_get_program_status	(	QDMI_Device_Job	job,
		size_t	program_index,
		QDMI_Job_Status *	status )

Query the current status of one program in a device job.

Individual outcomes are optional. Once reached, a program's terminal status cannot change. An out-of-range index returns QDMI_ERROR_OUTOFRANGE even if individual outcomes are unsupported; results of successful programs remain available when siblings fail or are canceled. A temporary retrieval failure is an error, not QDMI_ERROR_NOTSUPPORTED.

Parameters

[in]	job	The job to query. Must not be NULL.
[in]	program_index	The zero-based input program index.
[out]	status	The program status. Must not be NULL when individual outcomes are supported. An implementation that always returns QDMI_ERROR_NOTSUPPORTED need not inspect this pointer.

Returns

QDMI_SUCCESS if the status was retrieved.

QDMI_ERROR_NOTSUPPORTED if individual outcomes are unavailable.

QDMI_ERROR_BADSTATE if no program list has been set or supported outcomes are not yet ready.

QDMI_ERROR_OUTOFRANGE if program_index is out of range.

QDMI_ERROR_INVALIDARGUMENT if job is NULL, or if individual outcomes are supported and status is NULL.

QDMI_ERROR_FATAL if an unexpected error occurred.

QDMI_device_job_query_property()

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.

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

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

QDMI_device_job_submit()

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

[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 a required program or format is missing, the job was retrieved with QDMI_device_session_retrieve_device_job_by_id.

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

QDMI_ERROR_OUTOFMEM if the device cannot allocate job results.

QDMI_ERROR_FATAL if the job submission failed.

QDMI_device_job_cancel()

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

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

QDMI_ERROR_FATAL if the job could not be canceled.

QDMI_device_job_check()

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

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

QDMI_ERROR_FATAL if the job status could not be checked.

QDMI_device_job_wait()

int QDMI_device_job_wait	(	QDMI_Device_Job	job,
		size_t	timeout )

Wait for a job to finish.

This function blocks until the job reaches QDMI_JOB_STATUS_DONE, QDMI_JOB_STATUS_CANCELED, or QDMI_JOB_STATUS_FAILED, or until the timeout is reached. Call QDMI_device_job_check after a successful wait to distinguish terminal states. If timeout is not zero, this function returns latest after the specified number of seconds.

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 for a terminal state.

Returns

QDMI_SUCCESS if the job reached any terminal state.

QDMI_ERROR_INVALIDARGUMENT if job is NULL.

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

QDMI_ERROR_TIMEOUT if timeout is not zero and the job did not reach a terminal state within the specified time.

QDMI_ERROR_FATAL if the job could not be waited for and this function returns before the job reached a terminal state.

QDMI_device_job_get_results()

int QDMI_device_job_get_results	(	QDMI_Device_Job	job,
		size_t	program_index,
		QDMI_Job_Result	result,
		size_t	size,
		void *	data,
		size_t *	size_ret )

Retrieve one program's results from a job.

Results are available when the selected program has succeeded, even if other programs are still running, failed, or canceled. Devices exposing only aggregate outcomes provide results after the job reaches QDMI_JOB_STATUS_DONE.

Parameters

[in]	job	The job to retrieve the results from. Must not be NULL.
[in]	program_index	The zero-based program index. Must be less than QDMI_DEVICE_JOB_PROPERTY_PROGRAMSNUM.
[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 than or equal to the size of the requested result, except when data is NULL, in which case it is ignored.
[out]	data	The buffer in which to store the result. If this is NULL, it is ignored.
[out]	size_ret	The required buffer size 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, retrieved it successfully.

QDMI_ERROR_NOTSUPPORTED if the device does not support the specified result.

QDMI_ERROR_BADSTATE if the selected program has not succeeded.

QDMI_ERROR_OUTOFRANGE if program_index is greater than or equal to the number of programs in the job.

QDMI_ERROR_INVALIDARGUMENT if

• job is NULL,
• result is invalid, or
• data is not NULL and size is too small.

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

QDMI_ERROR_FATAL if an error occurred during retrieval.

Note

Calling this function with data set to NULL checks support and returns the required buffer size in size_ret when it is not NULL.

For example, to query the first program's measurement results:

size_t size;
auto ret = QDMI_device_job_get_results(
  job, 0, QDMI_JOB_RESULT_SHOTS, 0, nullptr, &size);
std::string shots(size, '\0');
QDMI_device_job_get_results(
  job, 0, QDMI_JOB_RESULT_SHOTS, size, shots.data(), nullptr);
shots.pop_back();

QDMI_device_job_free()

void QDMI_device_job_free

(

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

[in]

job

The job to free.