Quantum Resource Management Interface (QRMI) C API
Loading...
Searching...
No Matches
Quantum Resource

Functions

QrmiQuantumResource * qrmi_resource_new (const char *resource_id, QrmiResourceType resource_type)
QrmiQuantumResource * qrmi_resource_new_from_config (const char *resource_id, QrmiResourceType resource_type, const QrmiConfigMap *config)
QrmiReturnCode qrmi_resource_free (QrmiQuantumResource *ptr)
QrmiReturnCode qrmi_resource_is_accessible (QrmiQuantumResource *qrmi, bool *outp)
QrmiReturnCode qrmi_resource_status (QrmiQuantumResource *qrmi, QrmiResourceStatus **outp)
QrmiReturnCode qrmi_resource_id (QrmiQuantumResource *qrmi, char **outp)
QrmiReturnCode qrmi_resource_type (QrmiQuantumResource *qrmi, QrmiResourceType *outp)
QrmiReturnCode qrmi_resource_acquire (QrmiQuantumResource *qrmi, char **acquisition_token)
QrmiReturnCode qrmi_resource_release (QrmiQuantumResource *qrmi, const char *acquisition_token)
QrmiReturnCode qrmi_resource_task_start (QrmiQuantumResource *qrmi, const QrmiPayload *payload, char **task_id)
QrmiReturnCode qrmi_resource_task_stop (QrmiQuantumResource *qrmi, const char *task_id)
QrmiReturnCode qrmi_resource_task_status (QrmiQuantumResource *qrmi, const char *task_id, QrmiTaskStatus *status)
QrmiReturnCode qrmi_resource_task_result (QrmiQuantumResource *qrmi, const char *task_id, char **outp)
QrmiReturnCode qrmi_resource_task_logs (QrmiQuantumResource *qrmi, const char *task_id, char **outp)
QrmiReturnCode qrmi_resource_target (QrmiQuantumResource *qrmi, char **outp)
QrmiReturnCode qrmi_resource_metadata (QrmiQuantumResource *qrmi, QrmiResourceMetadata **outp)

Detailed Description

Functions used when accessing Quantum resource from the QRMI C API.

Function Documentation

◆ qrmi_resource_acquire()

QrmiReturnCode qrmi_resource_acquire ( QrmiQuantumResource * qrmi,
char ** acquisition_token )

Acquires quantum resource.

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • outp must be non-null.

Example

char *acquisition_token;
QrmiReturnCode rc = qrmi_resource_acquire(qrmi, &acquisition_token);
printf("acquisition token = %s\n", acquisition_token);
}
else {
printf("qrmi_resource_acquire failed.");
}
QrmiReturnCode qrmi_resource_acquire(QrmiQuantumResource *qrmi, char **acquisition_token)
QrmiReturnCode
Definition qrmi.h:55
@ QRMI_RETURN_CODE_SUCCESS
Definition qrmi.h:59
Parameters
(qrmi)[in] A QrmiQuantumResource handle
(acquisition_token)[out] An acquisition token if succeeded. Must call qrmi_string_free() to free if no longer used.
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.6.0

◆ qrmi_resource_free()

QrmiReturnCode qrmi_resource_free ( QrmiQuantumResource * ptr)

Frees the memory space pointed to by ptr, which must have been returned by a previous call to qrmi_resource_new(). Otherwise, or if ptr has already been freed, segmentation fault occurs. If ptr is NULL, returns < 0.

Safety

Example

QrmiQuantumResource *qrmi = qrmi_resource_new("your_resource_name",
if (qrmi != NULL) {
}
QrmiQuantumResource * qrmi_resource_new(const char *resource_id, QrmiResourceType resource_type)
QrmiReturnCode qrmi_resource_free(QrmiQuantumResource *ptr)
@ QRMI_RESOURCE_TYPE_IBM_QUANTUM_SYSTEM
Definition qrmi.h:129
struct QrmiQuantumResource QrmiQuantumResource
Definition qrmi.h:227
Parameters
(ptr)[in] A QrmiQuantumResource handle to be free
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.6.0

◆ qrmi_resource_id()

QrmiReturnCode qrmi_resource_id ( QrmiQuantumResource * qrmi,
char ** outp )

Returns resource identifier.

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • outp must be non-null.

◆ qrmi_resource_is_accessible()

QrmiReturnCode qrmi_resource_is_accessible ( QrmiQuantumResource * qrmi,
bool * outp )

Returns true if device is accessible, otherwise false.

Deprecated
Use qrmi_resource_status() instead. This function will be removed in a future release.

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • The memory pointed to by outp must have enough room to store boolean value.

Example

bool is_accessible = false;
int rc = qrmi_resource_is_accessible(qrmi, &is_accessible);
if (is_accessible == false) {
printf("%s cannot be accessed.\n", argv[1]);
}
} else {
printf("qrmi_resource_is_accessible() failed.\n");
}
QrmiReturnCode qrmi_resource_is_accessible(QrmiQuantumResource *qrmi, bool *outp)
Parameters
(qrmi)[in] A QrmiQuantumResource handle
(outp)[out] accessible or not
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.6.0

◆ qrmi_resource_metadata()

QrmiReturnCode qrmi_resource_metadata ( QrmiQuantumResource * qrmi,
QrmiResourceMetadata ** outp )

Returns a resource metadata

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • outp must be non-null.

Example

QrmiResourceMetadata *metadata = NULL;
QrmiReturnCode rc = qrmi_resource_metadata(qrmi, &metadata);
QrmiReturnCode qrmi_resource_metadata(QrmiQuantumResource *qrmi, QrmiResourceMetadata **outp)
struct QrmiResourceMetadata QrmiResourceMetadata
Definition qrmi.h:232
Parameters
(qrmi)[in] A QrmiQuantumResource handle
(outp)[out] A QrmiResourceMetadata handle. Must call qrmi_resource_metadata_free() to free if no longer used.
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.6.0

◆ qrmi_resource_new()

QrmiQuantumResource * qrmi_resource_new ( const char * resource_id,
QrmiResourceType resource_type )

Returns a QrmiQuantumResource handle.

Created QrmiQuantumResource instance needs to be removed by qrmi_resource_free() call if no longer needed.

Safety

  • The memory pointed to by resource_id must contain a valid nul terminator.
  • The nul terminator must be within isize::MAX from resource_id

Example

Parameters
(resource_id)[in] A resource identifier, i.e. backend name
(resource_type)[in] QrmiResourceType variant
Returns
a QrmiQuantumResource handle if succeeded, otherwise NULL. Must call qrmi_resource_free() to free if no longer used.
Version
0.6.0

◆ qrmi_resource_new_from_config()

QrmiQuantumResource * qrmi_resource_new_from_config ( const char * resource_id,
QrmiResourceType resource_type,
const QrmiConfigMap * config )

Constructs a QrmiQuantumResource from a config map.

Created QrmiQuantumResource instance needs to be removed by qrmi_resource_free() call if no longer needed.

Safety

  • config must be a valid pointer to a QrmiConfigMap struct.
  • The memory pointed to by resource_id must contain a valid nul terminator.
  • The nul terminator must be within isize::MAX from resource_id

Example

QrmiKeyValue variables[] = {
{(char *)"qrmi_warden_url", (char *)"http://localhost:8006"},
{(char *)"qrmi_job_id", (char *)"1"},
{(char *)"qrmi_job_uid", (char *)"1000"},
};
config.variables = variables;
config.length = 3;
&config);
QrmiQuantumResource * qrmi_resource_new_from_config(const char *resource_id, QrmiResourceType resource_type, const QrmiConfigMap *config)
@ QRMI_RESOURCE_TYPE_PASQAL_LOCAL
Definition qrmi.h:142
QrmiEnvironmentVariables QrmiConfigMap
Definition qrmi.h:305
QrmiKeyValue * variables
Definition qrmi.h:273
size_t length
Definition qrmi.h:277
Definition qrmi.h:255
Parameters
(resource_id)[in] A resource identifier, i.e. backend name
(resource_type)[in] QrmiResourceType variant
(config)[in] Pointer to QrmiConfigMap holding the config map
Returns
a QrmiQuantumResource handle if succeeded, otherwise NULL. Must call qrmi_resource_free() to free if no longer used.
Version
0.25.0

◆ qrmi_resource_release()

QrmiReturnCode qrmi_resource_release ( QrmiQuantumResource * qrmi,
const char * acquisition_token )

Releases quantum resource.

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • acquisition_token must contain the nul terminator.
  • The nul terminator must be within isize::MAX from acquisition_token

Example

char *acquisition_token = NULL;
QrmiReturnCode rc = qrmi_resource_acquire(qrmi, &acquisition_token);
rc = qrmi_resource_release(qrmi, acquisition_token);
printf("Failed to release a quantum resource\n");
}
}
QrmiReturnCode qrmi_resource_release(QrmiQuantumResource *qrmi, const char *acquisition_token)
Parameters
(qrmi)[in] A QrmiQuantumResource handle
(acquisition_token)[in] An acquisition token returned by qrmi_resource_acquire() call.
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.6.0

◆ qrmi_resource_status()

QrmiReturnCode qrmi_resource_status ( QrmiQuantumResource * qrmi,
QrmiResourceStatus ** outp )

Returns the status of the specified resource.

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • outp must be non-null.
QrmiResourceStatus *status = NULL;
}
QrmiReturnCode qrmi_resource_status(QrmiQuantumResource *qrmi, QrmiResourceStatus **outp)
struct QrmiResourceStatus QrmiResourceStatus
Definition qrmi.h:242
QrmiReturnCode qrmi_resource_status_free(QrmiResourceStatus *ptr)
Parameters
(qrmi)[in] A QrmiQuantumResource handle
(outp)[out] Resource status if succeeded. Must call qrmi_resource_status_free() to free if no longer used.
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.25.0

◆ qrmi_resource_target()

QrmiReturnCode qrmi_resource_target ( QrmiQuantumResource * qrmi,
char ** outp )

Returns a Target for the specified device. Vendor specific serialized data. This might contain the constraints(instructions, properties and timing information etc.) of a particular device to allow compilers to compile an input circuit to something that works and is optimized for a device. In IBM implementation, it contains JSON representations of BackendConfiguration and BackendProperties so that we are able to create a Target object by calling qiskit_ibm_runtime.utils.backend_converter.convert_to_target or uquivalent functions.

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • outp must be non-null.

Example

char *target = NULL;
rc = qrmi_resource_target(qrmi, &target);
printf("target = %s\n", target);
}
QrmiReturnCode qrmi_resource_target(QrmiQuantumResource *qrmi, char **outp)
QrmiReturnCode qrmi_string_free(char *ptr)
Parameters
(qrmi)[in] A QrmiQuantumResource handle
(outp)[out] A serialized target data if succeeded. Must call qrmi_string_free() to free if no longer used.
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.1.0

◆ qrmi_resource_task_logs()

QrmiReturnCode qrmi_resource_task_logs ( QrmiQuantumResource * qrmi,
const char * task_id,
char ** outp )

Returns the log messages of a task.

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • outp must be non-null.
  • The memory pointed to by task_id must contain a valid nul terminator.
  • The nul terminator must be within isize::MAX from task_id

Example

QrmiReturnCode rc = qrmi_resource_task_status(qrmi, job_id, &status);
char *logs = NULL;
qrmi_resource_task_logs(qrmi, job_id, &logs);
printf("%s\n", logs);
qrmi_string_free((char *)logs);
}
QrmiReturnCode qrmi_resource_task_logs(QrmiQuantumResource *qrmi, const char *task_id, char **outp)
QrmiReturnCode qrmi_resource_task_status(QrmiQuantumResource *qrmi, const char *task_id, QrmiTaskStatus *status)
@ QRMI_TASK_STATUS_COMPLETED
Definition qrmi.h:189
Parameters
(qrmi)[in] A QrmiQuantumResource handle
(task_id)[in] A task identifier
(outp)[out] Task log messages if succeeded. Must call qrmi_string_free() to free if no longer used.
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.1.0

◆ qrmi_resource_task_result()

QrmiReturnCode qrmi_resource_task_result ( QrmiQuantumResource * qrmi,
const char * task_id,
char ** outp )

Returns the result of a task.

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • outp must be non-null.
  • The memory pointed to by task_id must contain a valid nul terminator.
  • The nul terminator must be within isize::MAX from task_id

Example

QrmiReturnCode rc = qrmi_resource_task_status(qrmi, job_id, &status);
char *result = NULL;
qrmi_resource_task_result(qrmi, job_id, &result);
printf("%s\n", result);
qrmi_string_free((char *)result);
}
QrmiReturnCode qrmi_resource_task_result(QrmiQuantumResource *qrmi, const char *task_id, char **outp)
Parameters
(qrmi)[in] A QrmiQuantumResource handle
(task_id)[in] A task identifier
(outp)[out] Task result if succeeded. Must call qrmi_string_free() to free if no longer used.
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.1.0

◆ qrmi_resource_task_start()

QrmiReturnCode qrmi_resource_task_start ( QrmiQuantumResource * qrmi,
const QrmiPayload * payload,
char ** task_id )

Starts a task.

Safety

Example

QrmiPayload payload;
char *job_id = NULL;
const char* input = "your Qiskit estimator primitive input";
payload.QISKIT_PRIMITIVE.input = (char *)input;
payload.QISKIT_PRIMITIVE.program_id = "estimator";
rc = qrmi_resource_task_start(qrmi, &payload, &job_id);
printf("Job ID: %s\n", job_id);
}
else {
printf("failed to start a task.\n");
}
QrmiReturnCode qrmi_resource_task_start(QrmiQuantumResource *qrmi, const QrmiPayload *payload, char **task_id)
@ QRMI_PAYLOAD_QISKIT_PRIMITIVE
Definition qrmi.h:325
char * program_id
Definition qrmi.h:353
char * input
Definition qrmi.h:349
Definition qrmi.h:445
QrmiPayload_Tag tag
Definition qrmi.h:446
QrmiPayload_QiskitPrimitive_Body QISKIT_PRIMITIVE
Definition qrmi.h:448

Any failure code other than QrmiReturnCode::QRMI_RETURN_CODE_ERROR means that no task was created: QRMI or the vendor's API refused the request. QrmiReturnCode::QRMI_RETURN_CODE_ERROR leaves that unknown (e.g. a lost response), so the task may exist.

Parameters
(qrmi)[in] A QrmiQuantumResource handle
(payload)[in] payload
(task_id)[out] A task identifier if succeeded. Must call qrmi_string_free() to free if no longer used.
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.6.0

◆ qrmi_resource_task_status()

QrmiReturnCode qrmi_resource_task_status ( QrmiQuantumResource * qrmi,
const char * task_id,
QrmiTaskStatus * status )

Returns the status of the specified task.

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • The memory pointed to by task_id must contain a valid nul terminator.
  • The memory pointed to by status must have enough room to store QrmiTaskStatus value.
  • The nul terminator must be within isize::MAX from task_id

Example

while (1) {
rc = qrmi_resource_task_status(qrmi, job_id, &status);
break;
}
sleep(1);
}
QrmiTaskStatus
Definition qrmi.h:177
@ QRMI_TASK_STATUS_RUNNING
Definition qrmi.h:185
Parameters
(qrmi)[in] A QrmiQuantumResource handle
(task_id)[in] A task identifier
(status)[out] A pointer to the memory to store QrmiTaskStatus value
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.6.0

◆ qrmi_resource_task_stop()

QrmiReturnCode qrmi_resource_task_stop ( QrmiQuantumResource * qrmi,
const char * task_id )

Stops a task.

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • The memory pointed to by task_id must contain a valid nul terminator at the end of the string.
  • The nul terminator must be within isize::MAX from task_id

Example

printf("Failed to stop a task\n");
}
QrmiReturnCode qrmi_resource_task_stop(QrmiQuantumResource *qrmi, const char *task_id)
Parameters
(qrmi)[in] A QrmiQuantumResource handle
(task_id)[in] A task ID, returned by a previous call to qrmi_resource_task_start()
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.6.0

◆ qrmi_resource_type()

QrmiReturnCode qrmi_resource_type ( QrmiQuantumResource * qrmi,
QrmiResourceType * outp )

Returns resource type.

Safety

  • qrmi must have been returned by a previous call to qrmi_resource_new().
  • outp must be non-null.