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.

The typical workflow for a device job is as follows:

Create a job with QDMI_device_session_create_device_job.
Set one program and other parameters with QDMI_device_job_set_parameter, or set a program list with QDMI_device_job_set_programs.
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, const 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_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. Retrieval is all-or-nothing: the device must reconstruct the exact historical format descriptor, program count, status, and mapping from each input index to its results. This also applies when the historical descriptor is no longer advertised. The device must return QDMI_ERROR_NOTSUPPORTED if it cannot reconstruct all of this information.

The retrieved job's properties describe the historical execution. Its exact program descriptor may no longer appear in the device's current supported-format list. A device that cannot reconstruct the historical descriptor losslessly returns QDMI_ERROR_NOTSUPPORTED.

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 all required job metadata and result-index mappings.; 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 program 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,
		const 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 exact format descriptor and the same job parameters, including the shot count. On success, the device replaces the complete program list with a deep copy of format, 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. One program failure sets the aggregate status to QDMI_JOB_STATUS_FAILED. Cancellation sets it to QDMI_JOB_STATUS_CANCELED. Results are available only for a job with status QDMI_JOB_STATUS_DONE; QDMI exposes no partial results.

Parameters

[in]	job	A handle to the job. Must not be `NULL`.
[in]	format	The exact format of every program. Must point to a valid QDMI_Program_Format when the device supports program lists. It must not be `NULL`, including for a support check.
[in]	count	The number of programs. Must be greater than zero. A support check succeeds only if the device supports this exact cardinality.
[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 NUL, 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. Each pointer must not be `NULL`. The device copies all input data before returning. If this is `NULL`, the function checks support for the exact descriptor and cardinality and does not change the job.

Returns

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

QDMI_ERROR_INVALIDARGUMENT if

job or format is NULL, or count is zero,
the device supports program lists and format is not a valid descriptor, 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 NUL.

QDMI_ERROR_NOTSUPPORTED if the arguments are valid but the device does not support program lists, format, or one of the programs.

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

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_OUTOFRANGE if program_index is greater than or equal to the number of programs in the job.

QDMI_ERROR_INVALIDARGUMENT if

job is NULL,
job does not have status QDMI_JOB_STATUS_DONE,
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.

Description

Typedefs

Functions

Typedef Documentation

◆ QDMI_Device_Job

Function Documentation

◆ QDMI_device_session_create_device_job()

◆ QDMI_device_session_retrieve_device_job_by_id()

◆ QDMI_device_job_set_parameter()

◆ QDMI_device_job_set_programs()

◆ QDMI_device_job_query_property()

◆ QDMI_device_job_submit()

◆ QDMI_device_job_cancel()

◆ QDMI_device_job_check()

◆ QDMI_device_job_wait()

◆ QDMI_device_job_get_results()

◆ QDMI_device_job_free()