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

Functions

QrmiResourceProvider * qrmi_provider_new (QrmiResourceType resource_type, const QrmiEnvironmentVariables *environments)
QrmiReturnCode qrmi_provider_free (QrmiResourceProvider *ptr)
QrmiReturnCode qrmi_provider_resources (QrmiResourceProvider *provider, const char *filters, QrmiQuantumResources *resources_out)
QrmiReturnCode qrmi_provider_resources_free (QrmiQuantumResources *resources)
QrmiReturnCode qrmi_provider_least_busy (QrmiResourceProvider *provider, const char *filters, QrmiQuantumResource **resource_out)

Detailed Description

Functions used to dynamically discover quantum resources from a vendor endpoint via the QRMI C API.

Function Documentation

◆ qrmi_provider_free()

QrmiReturnCode qrmi_provider_free ( QrmiResourceProvider * ptr)

Frees the memory space pointed to by ptr, which must have been returned by a previous call to qrmi_provider_new(). If ptr is NULL, returns NullPointerError.

Safety

Example

QrmiConfig *config = qrmi_config_load("/path/to/qrmi_config.json");
QrmiResourceDef *def = qrmi_config_resource_def_get(config, "ibm_inst1");
if (provider != NULL) {
qrmi_provider_free(provider);
}
QrmiConfig * qrmi_config_load(const char *filename)
QrmiResourceDef * qrmi_config_resource_def_get(QrmiConfig *config, const char *resource_id)
QrmiReturnCode qrmi_provider_free(QrmiResourceProvider *ptr)
QrmiResourceProvider * qrmi_provider_new(QrmiResourceType resource_type, const QrmiEnvironmentVariables *environments)
struct QrmiResourceProvider QrmiResourceProvider
Definition qrmi.h:237
struct QrmiConfig QrmiConfig
Definition qrmi.h:222
Definition qrmi.h:283
QrmiEnvironmentVariables environments
Definition qrmi.h:299
QrmiResourceType type
Definition qrmi.h:291
Parameters
(ptr)[in] A QrmiResourceProvider handle to be freed
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.15.0

◆ qrmi_provider_least_busy()

QrmiReturnCode qrmi_provider_least_busy ( QrmiResourceProvider * provider,
const char * filters,
QrmiQuantumResource ** resource_out )

Returns the least busy available quantum resource, optionally filtered.

Equivalent to calling qrmi_provider_resources() and taking the first element. If no resources match the filter, *resource_out is set to NULL and the function returns QRMI_RETURN_CODE_SUCCESS.

The returned QrmiQuantumResource handle must be freed with qrmi_resource_free() when no longer needed.

Safety

  • provider must have been returned by a previous call to qrmi_provider_new().
  • filters may be NULL (no filtering) or a valid nul-terminated C string.
  • resource_out must be non-null.

Example

QrmiQuantumResource *resource = NULL;
QrmiReturnCode rc = qrmi_provider_least_busy(provider, NULL, &resource);
if (rc == QRMI_RETURN_CODE_SUCCESS && resource != NULL) {
char *id = NULL;
qrmi_resource_id(resource, &id);
printf("least busy: %s\n", id);
qrmi_resource_free(resource);
}
QrmiReturnCode qrmi_resource_free(QrmiQuantumResource *ptr)
QrmiReturnCode qrmi_resource_id(QrmiQuantumResource *qrmi, char **outp)
QrmiReturnCode qrmi_provider_least_busy(QrmiResourceProvider *provider, const char *filters, QrmiQuantumResource **resource_out)
QrmiReturnCode qrmi_string_free(char *ptr)
QrmiReturnCode
Definition qrmi.h:55
@ QRMI_RETURN_CODE_SUCCESS
Definition qrmi.h:59
struct QrmiQuantumResource QrmiQuantumResource
Definition qrmi.h:227
Parameters
(provider)[in] A QrmiResourceProvider handle
(filters)[in] Filter string, or NULL for no filtering
(resource_out)[out] Least busy QrmiQuantumResource handle, or NULL if none found
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.15.0

◆ qrmi_provider_new()

QrmiResourceProvider * qrmi_provider_new ( QrmiResourceType resource_type,
const QrmiEnvironmentVariables * environments )

Returns a QrmiResourceProvider handle for the specified resource type and environment.

Created handle must be released with qrmi_provider_free() when no longer needed.

Currently supported resource types:

Safety

Example

QrmiConfig *config = qrmi_config_load("/path/to/qrmi_config.json");
QrmiResourceDef *def = qrmi_config_resource_def_get(config, "ibm_inst1");
if (provider == NULL) {
char *err = qrmi_get_last_error();
printf("error: %s\n", err);
}
char * qrmi_get_last_error(void)
Parameters
(resource_type)[in] QrmiResourceType variant
(environments)[in] Pointer to QrmiEnvironmentVariables
Returns
A QrmiResourceProvider handle if succeeded, otherwise NULL. Must call qrmi_provider_free() to free if no longer used.
Version
0.15.0

◆ qrmi_provider_resources()

QrmiReturnCode qrmi_provider_resources ( QrmiResourceProvider * provider,
const char * filters,
QrmiQuantumResources * resources_out )

Returns a list of available quantum resources, optionally filtered.

Results are expected to be sorted in least-busy order.

The caller is responsible for freeing the returned struct with qrmi_provider_resources_free(). Individual handles inside the struct must NOT be freed separately.

Safety

  • provider must have been returned by a previous call to qrmi_provider_new().
  • filters may be NULL (no filtering) or a valid nul-terminated C string.
  • resources_out must be non-null and point to a zero-initialized QrmiQuantumResources.

Filter string format

key=value pairs joined by &. Supported filters(constraints) are defined by each resource provider's implementation.

Example

QrmiQuantumResources resources = {0};
QrmiReturnCode rc = qrmi_provider_resources(provider, "num_qubits=127", &resources);
for (size_t i = 0; i < resources.length; i++) {
char *id = NULL;
qrmi_resource_id(resources.resources[i], &id);
printf("resource: %s\n", id);
}
}
QrmiReturnCode qrmi_provider_resources_free(QrmiQuantumResources *resources)
QrmiReturnCode qrmi_provider_resources(QrmiResourceProvider *provider, const char *filters, QrmiQuantumResources *resources_out)
Definition qrmi.h:462
QrmiQuantumResource ** resources
Definition qrmi.h:466
size_t length
Definition qrmi.h:470
Parameters
(provider)[in] A QrmiResourceProvider handle
(filters)[in] Filter string, or NULL for no filtering
(resources_out)[out] Pointer to a QrmiQuantumResources struct to populate
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.15.0

◆ qrmi_provider_resources_free()

QrmiReturnCode qrmi_provider_resources_free ( QrmiQuantumResources * resources)

Frees a QrmiQuantumResources struct populated by qrmi_provider_resources().

This frees both the individual QrmiQuantumResource handles and the internal array. After calling this, the struct's fields are zeroed. Do NOT call qrmi_resource_free() on individual elements after calling this.

Safety

Example

Parameters
(resources)[in] Pointer to a QrmiQuantumResources struct to free
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.15.0