Quantum Resource Management Interface (QRMI) C API
Loading...
Searching...
No Matches
qrmi.h
Go to the documentation of this file.
1#ifndef QRMI_H
2#define QRMI_H
3
4#pragma once
5
6/* Generated with cbindgen:0.29.2 */
7
8/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */
9
10#include <stdarg.h>
11#include <stdbool.h>
12#include <stddef.h>
13#include <stdint.h>
14#include <stdlib.h>
15
16#define QRMI_VERSION_MAJOR 0
17#define QRMI_VERSION_MINOR 27
18#define QRMI_VERSION_PATCH 1
19
20#define QRMI_VERSION_NUMERIC(M,m,p) ((M)<<16|(m)<<8|(p))
21#define QRMI_VERSION (QRMI_VERSION_MAJOR<<16 | QRMI_VERSION_MINOR<<8 | QRMI_VERSION_PATCH)
22
23/**
24 * @defgroup Qrmi Common
25 *
26 * Commonly used when using the QRMI C API
27 *
28 * @defgroup QrmiConfig QRMI Configuration
29 *
30 * Functions used when accessing configuration file data from the QRMI C API.
31 *
32 * @defgroup QrmiQuantumResource Quantum Resource
33 *
34 * Functions used when accessing Quantum resource from the QRMI C API.
35 *
36 * @defgroup QrmiResourceMetadata Quantum Resource Metadata
37 *
38 * Functions used when accessing Quantum resource metadata from the QRMI C API.
39 *
40 * @defgroup QrmiResourceProvider Resource Provider
41 *
42 * Functions used to dynamically discover quantum resources from a vendor
43 * endpoint via the QRMI C API.
44 *
45 * @defgroup QrmiService QRMI Service
46 *
47 * Functions used to discover the QPU resources assigned to the current job
48 * from the QRMI C API.
49 */
50
51
52/**
53 * Integer return codes returned to C.
54 */
55typedef enum {
56 /**
57 * Success.
58 */
60 /**
61 * Error. Generic/uncategorized failure -- see `qrmi_get_last_error()`
62 * for the message and `qrmi_get_last_error_kind()` for a more specific
63 * machine-readable reason when available.
64 */
66 /**
67 * Unexpected null pointer.
68 */
70 /**
71 * A required environment variable was not set.
72 */
74 /**
75 * A configuration value could not be parsed.
76 */
78 /**
79 * Dynamic discovery was requested for an unsupported resource type.
80 */
82 /**
83 * The requested operation is not supported by this resource.
84 */
86 /**
87 * The payload variant is not supported by this backend.
88 */
90 /**
91 * The task is not in a state that allows the requested operation.
92 */
94 /**
95 * A required key was missing from a provider's environment variable map.
96 */
98 /**
99 * A value was invalid, whether QRMI itself rejected it locally or a
100 * vendor's API rejected the resulting request after receiving it.
101 */
103 /**
104 * The named resource (e.g. a backend) does not exist.
105 */
107 /**
108 * The named task (e.g. a job) does not exist, or has already been
109 * removed.
110 */
112 /**
113 * The request's credentials were missing or rejected.
114 */
116 /**
117 * A configuration value (or combination of values) was invalid.
118 */
121
122/**
123 * QRMI resource types
124 */
125typedef enum {
126 /**
127 * IBM Quantum System
128 */
130 /**
131 * Qiskit Runtime Service(deprecated)
132 */
134 /**
135 * IBM Quantum Compute Service
136 */
138 /**
139 * Pasqal Cloud
140 */
143 /**
144 * Alice Bob Felis
145 */
149 /**
150 * Maestro Local
151 */
154
155/**
156 * Resource statuses.
157 */
158typedef enum {
159 /**
160 * Online and available.
161 */
163 /**
164 * Offline and unavailable.
165 */
167 /**
168 * Online but not currently accepting/running jobs due to a
169 * maintenance-type event (e.g. calibration),
170 */
173
174/**
175 * Task statuses.
176 */
177typedef enum {
178 /**
179 * Task is queued
180 */
182 /**
183 * Task is running
184 */
186 /**
187 * Task was completed
188 */
190 /**
191 * Task was failed
192 */
194 /**
195 * Task was cancelled
196 */
199
200/**
201 * QRMI configuration file
202 *
203 * # Example
204 *
205 * ```no_run
206 * use qrmi::models::Config;
207 *
208 * # fn main() -> Result<(), Box<dyn std::error::Error>> {
209 * let config = Config::load("./qrmi_example_config.json")?;
210 *
211 * if let Some(resource) = config.resource_map.get("ibm_osaka") {
212 * println!("Found resource: {}", resource.name);
213 * println!("Type: {:?}", resource.r#type);
214 * for (key, value) in &resource.environment {
215 * println!("Environment variable: {}={}", key, value);
216 * }
217 * }
218 * # Ok(())
219 * # }
220 * ```
221 */
222typedef struct QrmiConfig QrmiConfig;
223
224/**
225 * Quantum resource handle
226 */
228
229/**
230 * Quantum resource metadata
231 */
233
234/**
235 * Resource provider handle.
236 */
238
239/**
240 * Quantum resource status
241 */
243
244/**
245 * C ABI type for `qrmi_log_callback_set`. This is a C-facing detail: it
246 * does not appear anywhere in `common.rs`, which only knows about plain
247 * Rust closures (see `common::LogSink`). `qrmi_log_callback_set` below
248 * adapts one of these into a `LogSink` at registration time.
249 */
250typedef void (*QrmiLogCallback)(const char *level, const char *target, const char *message);
251
252/**
253 * A key-value pair
254 */
255typedef struct {
256 /**
257 * key
258 */
259 char *key;
260 /**
261 * value
262 */
263 char *value;
265
266/**
267 * A set of environment variables
268 */
269typedef struct {
270 /**
271 * Ptr to the first key-value pair in the list
272 */
274 /**
275 * Number of key-value pairs included in the list
276 */
277 size_t length;
279
280/**
281 * Resource definition in QRMI configuration file
282 */
283typedef struct {
284 /**
285 * resource identifier, e.g. `ibm_kingston`
286 */
287 char *name;
288 /**
289 * Resource Type
290 */
292 /**
293 * Whether this is a dynamic resource (used with ResourceProvider)
294 */
296 /**
297 * environment variables for this resource
298 */
301
302/**
303 * Type alias for key-value map
304 */
306
307/**
308 * Resource capacity.
309 */
310typedef struct {
311 /**
312 * Number of slots currently available to be acquired.
313 */
315 /**
316 * Maximum number of slots the resource supports.
317 */
318 uint64_t max_slots;
320
321typedef enum {
322 /**
323 * Payload that contains Qiskit Primitive input.
324 */
326 /**
327 * Payload for Pasqal Cloud and Pasqal Local resources
328 */
331 /**
332 * Payload for IQM Server
333 */
335 /**
336 * Payload for OQTOPUS Cloud
337 */
339 /**
340 * Payload for Maestro Local Server
341 */
344
345typedef struct {
346 /**
347 * Primitive input
348 */
349 char *input;
350 /**
351 * "estimator" or "sampler"
352 */
355
356typedef struct {
357 /**
358 * Pulser sequence
359 */
360 char *sequence;
361 /**
362 * Number of job runs
363 */
364 int32_t job_runs;
366
367typedef struct {
368 /**
369 * Human-readable QIR input
370 */
372 /**
373 * Input parameters in JSON format
374 */
377
378typedef struct {
379 /**
380 * IQM JSON request body
381 */
382 char *iqmjson;
383 /**
384 * Job type(circuit, run, sweep)
385 */
386 char *job_type;
387 /**
388 * submit the job to the timeslot queue instead of the default FIFO queue.
389 * 0 = false, 1 = true
390 */
392 /**
393 * Optional user-defined tag associated with the job
394 */
395 char *tag;
397
398typedef struct {
399 /**
400 * Job spec, as a JSON object string matching the keyword
401 * arguments of Python's `OqtopusJobSpec` dataclass, minus
402 * `device_id` (QRMI fills that in automatically). Required
403 * keys: `job_type` (one of "sampling", "estimation",
404 * "multi_manual", "sse") and `program` (array of strings; a
405 * single program is a single-element array; `sse` jobs require
406 * exactly one). Optional keys: `shots` (integer; omit the key
407 * entirely to use OQTOPUS's default of 1000 — sending `null`
408 * fails), `name`, `description`, `transpiler_info`,
409 * `simulator_info`, `mitigation_info`, and `operator`.
410 */
411 char *job_spec;
413
414typedef struct {
415 /**
416 * Input payload (QASM string, or schema version 2 JSON if job_type == "request")
417 */
418 char *input;
419 /**
420 * Job type (execute, estimate, request)
421 */
422 char *job_type;
423 /**
424 * qubits count
425 */
426 uint32_t qubits;
427 /**
428 * simulator type
429 */
431 /**
432 * simulation method
433 */
435 /**
436 * observables, if needed, pauli strings separated by ";"
437 */
439 /**
440 * Configuration in json format
441 */
442 char *config;
444
456
457/**
458 * A list of [`QuantumResource`] handles returned by [`qrmi_provider_resources`].
459 *
460 * Must be freed with [`qrmi_provider_resources_free`] when no longer needed.
461 */
462typedef struct {
463 /**
464 * Pointer to the first element in the contiguous array of `QrmiQuantumResource` handles.
465 */
467 /**
468 * Number of handles in the array.
469 */
470 size_t length;
472
473#ifdef __cplusplus
474extern "C" {
475#endif // __cplusplus
476
477/**
478 * @ingroup Qrmi
479 * Registers a QRMI log callback for C hosts.
480 *
481 * Once registered, all log records produced by this library (subject to
482 * the active `RUST_LOG` filter, default level `warn`) are routed to
483 * `callback` instead of stderr.
484 *
485 * Pass NULL to clear the current callback and revert to the default stderr writer.
486 *
487 * # Safety
488 *
489 * * If `callback` is non-null, it must remain a valid, callable function
490 * pointer for as long as it might still be invoked. Because a
491 * currently-executing log call may have already captured the previous
492 * callback pointer, do not unload code backing a callback immediately
493 * after replacing or clearing it — a small number of in-flight calls
494 * may still land on the old pointer.
495 *
496 * # Example
497 *
498 * @code
499 * void my_log_cb(const char *level, const char *target, const char *message) {
500 * fprintf(stderr, "[%s] %s: %s\n", level, target, message);
501 * }
502 * QrmiReturnCode rc = qrmi_log_callback_set(my_log_cb);
503 * @endcode
504 *
505 * @param (callback) [in] Callback function, or NULL to clear.
506 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
507 * @version 0.20.0
508 */
510
511/**
512 * @ingroup Qrmi
513 * Free a string allocated by C API
514 *
515 * # Safety
516 *
517 * * `ptr` must be one returned by the related C API such as `qrmi_resource_target()`.
518 *
519 * # Example
520 *
521 * @code
522 * char *target = NULL;
523 * QrmiReturnCode rc;
524 * rc = qrmi_resource_target(qrmi, &target);
525 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
526 * printf("target = %s\n", target);
527 * qrmi_string_free(target);
528 * }
529 * @endcode
530 *
531 * @param (ptr) [in] pointer to the memory to be free
532 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
533 * @version 0.6.0
534 */
536
537/**
538 * @ingroup Qrmi
539 * Free a string array allocated by C API
540 *
541 * # Safety
542 *
543 * * `size` and `array` must be ones returned by the related C API such as `qrmi_config_resource_names_get()`.
544 *
545 * * Specifying an incorrect `size` value must lead to memory leaks or memory corruption.
546 *
547 * # Example
548 *
549 * @code
550 * size_t num_names = 0;
551 * char **names = NULL;
552 * QrmiReturnCode rc = qrmi_config_resource_names_get(cnf, &num_names, &names);
553 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
554 * for (int i = 0; i < num_names; i++) {
555 * printf("[%s]\n", names[i]);
556 * }
557 * qrmi_string_array_free(num_names, names);
558 * }
559 * @endcode
560 *
561 * @param (size) [in] number of strings in a string array
562 * @param (array) [in] a pointer to a string array to be free
563 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
564 * @version 0.6.0
565 */
567 char *array[]);
568
569/**
570 * @ingroup QrmiConfig
571 * Loads qrmi_config.json and returns it as Config.
572 *
573 * # Safety
574 *
575 * * The memory pointed to by `filename` must contain a valid nul terminator.
576 *
577 * * The nul terminator must be within `isize::MAX` from `filename`
578 *
579 * # Example
580 *
581 * @code
582 * QrmiConfig *cnf = qrmi_config_load("/etc/slurm/qrmi_config.json");
583 * @endcode
584 *
585 * @param (filename) [in] qrmi_config.json file path
586 * @return A QrmiConfig if succeeded, otherwise NULL. Must call qrmi_config_free() to free if no longer used.
587 * @version 0.6.0
588 */
589QrmiConfig *qrmi_config_load(const char *filename);
590
591/**
592 * @ingroup QrmiConfig
593 * Frees the memory space pointed to by `ptr`, which must have been returned by a previous call to qrmi_config_load() or related functions. Otherwise, or if `ptr` has already been freed, segmentation fault occurs. If `ptr` is NULL, no operation is performed.
594 *
595 * # Safety
596 *
597 * * `ptr` must have been returned by a previous call to qrmi_config_load().
598 *
599 * # Example
600 *
601 * @code
602 * QrmiConfig *cnf = qrmi_config_load("/etc/slurm/qrmi_config.json");
603 * qrmi_config_free(cnf);
604 * @endcode
605 *
606 * @param (ptr) a pointer to Config to be free
607 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
608 * @version 0.6.0
609 */
611
612/**
613 * @ingroup QrmiConfig
614 * Returns the resource definition for the specified resource.
615 *
616 * # Safety
617 *
618 * * The memory pointed to by `resource_id` must contain a valid nul terminator.
619 *
620 * * The nul terminator must be within `isize::MAX` from `resource_id`
621 *
622 * # Example
623 *
624 * @code
625 * QrmiConfig *cnf = qrmi_config_load(argv[1]);
626 * if (!cnf) {
627 * QrmiResourceDef* res = qrmi_config_resource_def_get(cnf, "your_resource_id");
628 * if (res != NULL) {
629 * printf("%s %d\n", res->name, res->type);
630 * QrmiEnvironmentVariables envvars = res->environments;
631 * for (int j = 0; j < envvars.length; j++) {
632 * QrmiKeyValue envvar = envvars.variables[j];
633 * printf("%s = %s\n", envvar.key, envvar.value);
634 * }
635 * }
636 * }
637 * @endcode
638 *
639 * @param (config) [in] a Config handle
640 * @param (resource_id) [in] resource identifier
641 * @return A QrmiResourceDef if succeeded, otherwise NULL. Must call qrmi_config_resource_def_free() to free if no longer used.
642 * @version 0.6.0
643 */
645 const char *resource_id);
646
647/**
648 * @ingroup QrmiConfig
649 * Converts ResourceType to string representation used in qrmi_config.json, e.g.
650 * @ref QrmiResourceType::QRMI_RESOURCE_TYPE_IBM_QUANTUM_COMPUTE_SERVICE to `ibm-quantum-compute-service`.
651 *
652 * # Safety
653 *
654 * * `type` must be QrmiResourceType value.
655 *
656 * # Example
657 *
658 * @code
659 * char *type_as_str = qrmi_config_resource_type_to_str(QRMI_RESOURCE_TYPE_IBM_QUANTUM_COMPUTE_SERVICE);
660 * printf("%s\n", type_as_str);
661 * qrmi_string_free(type_as_str);
662 * @endcode
663 *
664 * @param type (QrmiResourceType) ResourceType variant
665 * @return string representation of ResourceType.
666 * @version 0.6.0
667 */
669
670/**
671 * @ingroup QrmiConfig
672 * Parses the string representation used in qrmi_config.json and
673 * `QRMI_JOB_QPU_TYPES`, e.g. `pasqal-local` to
674 * @ref QrmiResourceType::QRMI_RESOURCE_TYPE_PASQAL_LOCAL.
675 *
676 * # Safety
677 *
678 * * The memory pointed to by `type_str` must contain a valid nul terminator.
679 *
680 * * `outp` must be non-null.
681 *
682 * # Example
683 *
684 * @code
685 * QrmiResourceType type;
686 * if (qrmi_config_resource_type_from_str("pasqal-local", &type) == QRMI_RETURN_CODE_SUCCESS) {
687 * QrmiQuantumResource *qrmi = qrmi_resource_new("your_resource_name", type);
688 * }
689 * @endcode
690 *
691 * @param (type_str) [in] string representation of ResourceType
692 * @param (outp) [out] ResourceType variant if succeeded
693 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded, @ref QrmiReturnCode::QRMI_RETURN_CODE_INVALID_INPUT_ERROR for an unknown string.
694 * @version 0.27.0
695 */
697 QrmiResourceType *outp);
698
699/**
700 * @ingroup QrmiConfig
701 * Frees the memory space pointed to by `ptr`, which must have been returned by a previous call to qrmi_config_get_resource_def() or related functions. Otherwise, or if ptr has already been freed, segmentation fault occurs. If `ptr` is NULL, no operation is performed.
702 *
703 * # Safety
704 *
705 * * `ptr` must have been returned by a previous call to qrmi_config_resource_def_get().
706 *
707 * # Example
708 *
709 * @code
710 * QrmiConfig *cnf = qrmi_config_load(argv[1]);
711 * if (!cnf) {
712 * QrmiResourceDef* res = qrmi_config_resource_def_get(cnf, "your_resource_id");
713 * if (res != NULL) {
714 * printf("%s %d\n", res->name, res->type);
715 * }
716 * qrmi_config_resource_def_free(res);
717 * }
718 * @endcode
719 *
720 * @param (ptr) a pointer to ResourceDef to be free
721 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
722 * @version 0.6.0
723 */
725
726/**
727 * @ingroup QrmiConfig
728 * Returns a list of the resource names
729 *
730 * # Safety
731 *
732 * * `config` must have been returned by a previous call to qrmi_config_load().
733 *
734 * * The memory pointed to by `outlen` must have enough room to store size_t value.
735 *
736 * * `names` must be non-null.
737 *
738 * # Example
739 *
740 * @code
741 * size_t num_names = 0;
742 * char **names = NULL;
743 * QrmiReturnCode rc = qrmi_config_resource_names_get(cnf, &num_names, &names);
744 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
745 * for (int i = 0; i < num_names; i++) {
746 * printf("[%s]\n", names[i]);
747 * }
748 * qrmi_string_array_free(num_names, names);
749 * }
750 * @endcode
751 *
752 * @param (config) [in] A Config handle
753 * @param (num_names) [out] number of resource names in the list
754 * @param (names) [out] A list of the resource names if succeeded. Must call qrmi_string_array_free() to free if no longer used.
755 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
756 * @version 0.6.0
757 */
759 size_t *num_names,
760 char **names[]);
761
762/**
763 * @ingroup Qrmi
764 * Returns the last error message that occurred during an FFI call from C to Rust.
765 * This function is designed to be thread-safe by using thread-local storage, ensuring that
766 * each thread retrieves its own error message independently.etrieves the most recent error
767 * encountered during API call.
768 *
769 * # Behavior
770 * * If an error was previously set in the current thread via set_last_error(), this function returns a pointer to a null-terminated C string (const char*) containing the error message.
771 * * If no error was set, it returns a null pointer (NULL).
772 * * After returning the error message, the internal error state is cleared for the current thread. Subsequent calls will return NULL until a new error is set.
773 *
774 * # Thread Safety
775 * This function uses Rust's thread_local! macro and RefCell to store error messages per thread.
776 * This design mirrors the behavior of errno in POSIX and GetLastError() in Windows, ensuring compatibility with multithreaded C environments.
777 *
778 * # Example
779 *
780 * @code
781 * char * last_error = qrmi_get_last_error();
782 * if (last_error != NULL) {
783 * printf("last error = %s\n", last_error);
784 * qrmi_string_free(last_error);
785 * }
786 * @endcode
787 *
788 * @return message text of the most recent error. The caller takes
789 * ownership of the returned string and must release it with
790 * `qrmi_string_free()` once done with it (or it will leak). Returns NULL
791 * if no error has been recorded yet.
792 * @version 0.8.0
793 */
795
796/**
797 * @ingroup QrmiCore
798 * Returns a machine-readable classification of the most recent error
799 * encountered during an API call, complementing `qrmi_get_last_error()`'s
800 * human-readable message. Unlike `qrmi_get_last_error()`, this value is
801 * NOT cleared after being read, since callers typically check it before
802 * (or without) reading the message.
803 *
804 * If no QRMI-specific error has been recorded (e.g. the failure came from
805 * an unrelated source, or no error has occurred yet), this returns
806 * `QRMI_RETURN_CODE_ERROR` -- the generic code -- as a safe default.
807 *
808 * @return A `ReturnCode` describing the kind of the most recent error.
809 * @version 0.16.0
810 */
812
813/**
814 * @ingroup QrmiQuantumResource
815 * Returns a QrmiQuantumResource handle.
816 *
817 * Created QrmiQuantumResource instance needs to be removed by qrmi_resource_free() call if
818 * no longer needed.
819 *
820 * # Safety
821 *
822 * * The memory pointed to by `resource_id` must contain a valid nul terminator.
823 *
824 * * The nul terminator must be within `isize::MAX` from `resource_id`
825 *
826 * # Example
827 *
828 * @code
829 * QrmiQuantumResource *qrmi = qrmi_resource_new("your_resource_name",
830 * QRMI_RESOURCE_TYPE_IBM_QUANTUM_SYSTEM);
831 * @endcode
832 *
833 * @param (resource_id) [in] A resource identifier, i.e. backend name
834 * @param (resource_type) [in] QrmiResourceType variant
835 * @return a QrmiQuantumResource handle if succeeded, otherwise NULL. Must call qrmi_resource_free() to free if no longer used.
836 * @version 0.6.0
837 */
838QrmiQuantumResource *qrmi_resource_new(const char *resource_id,
839 QrmiResourceType resource_type);
840
841/**
842 * @ingroup QrmiQuantumResource
843 * Constructs a QrmiQuantumResource from a config map.
844 *
845 * Created QrmiQuantumResource instance needs to be removed by qrmi_resource_free() call if
846 * no longer needed.
847 *
848 * # Safety
849 *
850 * * `config` must be a valid pointer to a QrmiConfigMap struct.
851 *
852 * * The memory pointed to by `resource_id` must contain a valid nul terminator.
853 *
854 * * The nul terminator must be within `isize::MAX` from `resource_id`
855 *
856 * # Example
857 *
858 * @code
859 * QrmiConfigMap config;
860 *
861 * QrmiKeyValue variables[] = {
862 * {(char *)"qrmi_warden_url", (char *)"http://localhost:8006"},
863 * {(char *)"qrmi_job_id", (char *)"1"},
864 * {(char *)"qrmi_job_uid", (char *)"1000"},
865 * };
866 * config.variables = variables;
867 * config.length = 3;
868 * QrmiQuantumResource *qrmi = qrmi_resource_new_from_config("your_resource_name",
869 * QRMI_RESOURCE_TYPE_PASQAL_LOCAL,
870 * &config);
871 * @endcode
872 *
873 * @param (resource_id) [in] A resource identifier, i.e. backend name
874 * @param (resource_type) [in] QrmiResourceType variant
875 * @param (config) [in] Pointer to QrmiConfigMap holding the config map
876 * @return a QrmiQuantumResource handle if succeeded, otherwise NULL. Must call qrmi_resource_free() to free if no longer used.
877 * @version 0.25.0
878 */
880 QrmiResourceType resource_type,
881 const QrmiConfigMap *config);
882
883/**
884 * @ingroup QrmiQuantumResource
885 * 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.
886 * # Safety
887 *
888 * * `ptr` must have been returned by a previous call to qrmi_resource_new().
889 *
890 * # Example
891 *
892 * @code
893 * QrmiQuantumResource *qrmi = qrmi_resource_new("your_resource_name",
894 * QRMI_RESOURCE_TYPE_IBM_QUANTUM_SYSTEM);
895 * if (qrmi != NULL) {
896 * qrmi_resource_free(qrmi);
897 * }
898 * @endcode
899 *
900 * @param (ptr) [in] A QrmiQuantumResource handle to be free
901 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
902 * @version 0.6.0
903 */
905
906/**
907 * @ingroup QrmiQuantumResource
908 * Returns true if device is accessible, otherwise false.
909 *
910 * @deprecated Use qrmi_resource_status() instead. This function will be
911 * removed in a future release.
912 *
913 * # Safety
914 *
915 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
916 *
917 * * The memory pointed to by `outp` must have enough room to store boolean value.
918 *
919 * # Example
920 *
921 * @code
922 * bool is_accessible = false;
923 * int rc = qrmi_resource_is_accessible(qrmi, &is_accessible);
924 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
925 * if (is_accessible == false) {
926 * printf("%s cannot be accessed.\n", argv[1]);
927 * }
928 * } else {
929 * printf("qrmi_resource_is_accessible() failed.\n");
930 * }
931 * @endcode
932 *
933 * @param (qrmi) [in] A QrmiQuantumResource handle
934 * @param (outp) [out] accessible or not
935 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
936 * @version 0.6.0
937 */
939
940/**
941 * @ingroup QrmiQuantumResource
942 * Returns the status of the specified resource.
943 *
944 * # Safety
945 *
946 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
947 *
948 * * `outp` must be non-null.
949 *
950 * @code
951 * QrmiResourceStatus *status = NULL;
952 * QrmiReturnCode rc = qrmi_resource_status(qrmi, &status);
953 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
954 * qrmi_resource_status_free(status);
955 * }
956 * @endcode
957 *
958 * @param (qrmi) [in] A QrmiQuantumResource handle
959 * @param (outp) [out] Resource status if succeeded. Must call qrmi_resource_status_free() to free if no longer used.
960 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
961 * @version 0.25.0
962 */
964 QrmiResourceStatus **outp);
965
966/**
967 * @ingroup QrmiResourceStatus
968 * Frees the memory space pointed to by `ptr`, which must have been
969 * returned by a previous call to qrmi_resource_status(). Otherwise, or
970 * if `ptr` has already been freed, segmentation fault occurs. If `ptr`
971 * is NULL, returns < 0.
972 *
973 * # Safety
974 *
975 * * `ptr` must have been returned by a previous call to qrmi_resource_status().
976 *
977 * # Example
978 *
979 * @code
980 * QrmiResourceStatus *status = NULL;
981 * QrmiReturnCode rc = qrmi_resource_status(qrmi, &status);
982 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
983 * qrmi_resource_status_free(status);
984 * }
985 * @endcode
986 *
987 * @param (ptr) [in] A QrmiResourceStatus handle to be free
988 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
989 * @version 0.25.0
990 */
992
993/**
994 * @ingroup QrmiResourceStatus
995 * Returns the resource's status code (Online/Offline/Paused).
996 *
997 * # Safety
998 *
999 * * `status` must have been returned by a previous call to qrmi_resource_status().
1000 *
1001 * * `outp` must be non-null.
1002 *
1003 * @code
1004 * QrmiResourceStatus *status = NULL;
1005 * QrmiReturnCode rc = qrmi_resource_status(qrmi, &status);
1006 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1007 * QrmiResourceStatusCode code;
1008 * rc = qrmi_resource_status_code(status, &code);
1009 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1010 * switch (code) {
1011 * case QRMI_RESOURCE_STATUS_CODE_ONLINE:
1012 * printf("online\n");
1013 * break;
1014 * case QRMI_RESOURCE_STATUS_CODE_OFFLINE:
1015 * printf("offline\n");
1016 * break;
1017 * case QRMI_RESOURCE_STATUS_CODE_PAUSED:
1018 * printf("paused\n");
1019 * break;
1020 * case QRMI_RESOURCE_STATUS_CODE_BUSY:
1021 * printf("busy\n");
1022 * break;
1023 * }
1024 * }
1025 * qrmi_resource_status_free(status);
1026 * }
1027 * @endcode
1028 *
1029 * @param (status) [in] A QrmiResourceStatus handle
1030 * @param (outp) [out] The status code
1031 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1032 * @version 0.25.0
1033 */
1035
1036/**
1037 * @ingroup QrmiResourceStatus
1038 * Converts a QrmiResourceStatusCode value to a human-readable, lowercase
1039 * string ("online", "offline", "paused"). Intended for logging
1040 * and diagnostic output.
1041 *
1042 * # Example
1043 *
1044 * @code
1045 * QrmiResourceStatusCode code;
1046 * QrmiReturnCode rc = qrmi_resource_status_code(status, &code);
1047 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1048 * printf("status=%s\n", qrmi_resource_status_code_to_string(code));
1049 * }
1050 * @endcode
1051 *
1052 * @param (code) [in] A QrmiResourceStatusCode value
1053 * @return A statically-allocated, human-readable string. Must NOT be
1054 * freed and remains valid for the lifetime of the program.
1055 * @version 0.25.0
1056 */
1058
1059/**
1060 * @ingroup QrmiResourceStatus
1061 * Returns the vendor-specific status reason (e.g. "maintenance",
1062 * "calibration"), if reported.
1063 *
1064 * # Safety
1065 *
1066 * * `status` must have been returned by a previous call to qrmi_resource_status().
1067 *
1068 * @code
1069 * QrmiResourceStatus *status = NULL;
1070 * QrmiReturnCode rc = qrmi_resource_status(qrmi, &status);
1071 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1072 * char *reason = qrmi_resource_status_reason(status);
1073 * if (reason != NULL) {
1074 * printf("reason=%s\n", reason);
1075 * qrmi_string_free(reason);
1076 * } else {
1077 * printf("no status reason reported\n");
1078 * }
1079 * qrmi_resource_status_free(status);
1080 * }
1081 * @endcode
1082 *
1083 * @param (status) [in] A QrmiResourceStatus handle
1084 * @return status reason string if the vendor reported one. Must call
1085 * qrmi_string_free() to free if no longer used. Returns NULL if
1086 * `status` is NULL or the vendor did not report a reason.
1087 * @version 0.25.0
1088 */
1090
1091/**
1092 * @ingroup QrmiResourceStatus
1093 * Returns whether the resource is currently healthy.
1094 *
1095 * # Safety
1096 *
1097 * * `status` must have been returned by a previous call to qrmi_resource_status().
1098 *
1099 * * `outp` must be non-null.
1100 *
1101 * @code
1102 * QrmiResourceStatus *status = NULL;
1103 * QrmiReturnCode rc = qrmi_resource_status(qrmi, &status);
1104 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1105 * bool healthy = false;
1106 * rc = qrmi_resource_status_healthy(status, &healthy);
1107 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1108 * printf("healthy=%d\n", healthy);
1109 * } else if (rc == QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR) {
1110 * printf("this vendor does not report health information\n");
1111 * } else {
1112 * printf("qrmi_resource_status_healthy() failed: %s\n", qrmi_get_last_error());
1113 * }
1114 * qrmi_resource_status_free(status);
1115 * }
1116 * @endcode
1117 *
1118 * @param (status) [in] A QrmiResourceStatus handle
1119 * @param (outp) [out] Whether the resource is healthy
1120 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1121 * @ref QrmiReturnCode::QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR
1122 * if the vendor does not report health information.
1123 * @version 0.25.0
1124 */
1126
1127/**
1128 * @ingroup QrmiResourceStatus
1129 * Returns whether the resource is currently busy.
1130 *
1131 * # Safety
1132 *
1133 * * `status` must have been returned by a previous call to qrmi_resource_status().
1134 *
1135 * * `outp` must be non-null.
1136 *
1137 * @code
1138 * QrmiResourceStatus *status = NULL;
1139 * QrmiReturnCode rc = qrmi_resource_status(qrmi, &status);
1140 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1141 * bool busy = false;
1142 * rc = qrmi_resource_status_busy(status, &busy);
1143 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1144 * printf("busy=%d\n", busy);
1145 * } else if (rc == QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR) {
1146 * printf("this vendor does not report busy information\n");
1147 * } else {
1148 * printf("qrmi_resource_status_busy() failed: %s\n", qrmi_get_last_error());
1149 * }
1150 * qrmi_resource_status_free(status);
1151 * }
1152 * @endcode
1153 *
1154 * @param (status) [in] A QrmiResourceStatus handle
1155 * @param (outp) [out] Whether the resource is busy
1156 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1157 * @ref QrmiReturnCode::QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR
1158 * if the vendor does not report health information.
1159 * @version 0.25.0
1160 */
1162
1163/**
1164 * @ingroup QrmiResourceStatus
1165 * Returns the number of jobs pending in the queue.
1166 *
1167 * # Safety
1168 *
1169 * * `status` must have been returned by a previous call to qrmi_resource_status().
1170 *
1171 * * `outp` must be non-null.
1172 *
1173 * @code
1174 * QrmiResourceStatus *status = NULL;
1175 * QrmiReturnCode rc = qrmi_resource_status(qrmi, &status);
1176 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1177 * uint64_t pending_job_count = 0;
1178 * rc = qrmi_resource_status_pending_job_count(status, &pending_job_count);
1179 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1180 * printf("pending_job_count=%llu\n", (unsigned long long)pending_job_count);
1181 * } else if (rc == QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR) {
1182 * printf("this resource has no queue / does not report pending job count\n");
1183 * } else {
1184 * printf("qrmi_resource_status_pending_job_count() failed: %s\n", qrmi_get_last_error());
1185 * }
1186 * qrmi_resource_status_free(status);
1187 * }
1188 * @endcode
1189 *
1190 * @param (status) [in] A QrmiResourceStatus handle
1191 * @param (outp) [out] Number of pending jobs
1192 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1193 * @ref QrmiReturnCode::QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR
1194 * if the resource has no queue / the vendor does not report this.
1195 * @version 0.25.0
1196 */
1198
1199/**
1200 * @ingroup QrmiResourceStatus
1201 * Returns the resource's capacity information, if reported.
1202 *
1203 * # Safety
1204 *
1205 * * `status` must have been returned by a previous call to qrmi_resource_status().
1206 *
1207 * * `outp` must be non-null.
1208 *
1209 * @code
1210 * QrmiResourceCapacity *capacity = NULL;
1211 * QrmiReturnCode rc = qrmi_resource_status_capacity(status, &capacity);
1212 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1213 * printf("available_slots=%u\n", capacity->available_slots);
1214 * qrmi_resource_capacity_free(capacity);
1215 * }
1216 * @endcode
1217 *
1218 * @param (status) [in] A QrmiResourceStatus handle
1219 * @param (outp) [out] Capacity handle if succeeded. Must call
1220 * qrmi_resource_capacity_free() to free if no longer used.
1221 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1222 * @ref QrmiReturnCode::QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR
1223 * if the vendor does not report capacity information.
1224 * @version 0.25.0
1225 */
1227 QrmiResourceCapacity **outp);
1228
1229/**
1230 * @ingroup QrmiResourceStatus
1231 * Frees a QrmiResourceCapacity handle returned by
1232 * qrmi_resource_status_capacity().
1233 *
1234 * # Safety
1235 *
1236 * * `ptr` must have been returned by a previous call to
1237 * qrmi_resource_status_capacity(). Otherwise, or if `ptr` has already
1238 * been freed, undefined behavior occurs.
1239 *
1240 * @code
1241 * QrmiResourceCapacity *capacity = NULL;
1242 * QrmiReturnCode rc = qrmi_resource_status_capacity(status, &capacity);
1243 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1244 * printf("available_slots=%u\n", capacity->available_slots);
1245 * qrmi_resource_capacity_free(capacity);
1246 * }
1247 * @endcode
1248 *
1249 * @param (ptr) [in] A QrmiResourceCapacity handle to be freed
1250 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1251 * @version 0.25.0
1252 */
1254
1255/**
1256 * @ingroup QrmiQuantumResource
1257 * Returns resource identifier.
1258 *
1259 * # Safety
1260 *
1261 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
1262 *
1263 * * `outp` must be non-null.
1264 */
1266
1267/**
1268 * @ingroup QrmiQuantumResource
1269 * Returns resource type.
1270 *
1271 * # Safety
1272 *
1273 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
1274 *
1275 * * `outp` must be non-null.
1276 */
1278
1279/**
1280 * @ingroup QrmiQuantumResource
1281 * Acquires quantum resource.
1282 *
1283 * # Safety
1284 *
1285 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
1286 *
1287 * * `outp` must be non-null.
1288 *
1289 * # Example
1290 *
1291 * @code
1292 * char *acquisition_token;
1293 * QrmiReturnCode rc = qrmi_resource_acquire(qrmi, &acquisition_token);
1294 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1295 * printf("acquisition token = %s\n", acquisition_token);
1296 * }
1297 * else {
1298 * printf("qrmi_resource_acquire failed.");
1299 * }
1300 * @endcode
1301 *
1302 * @param (qrmi) [in] A QrmiQuantumResource handle
1303 * @param (acquisition_token) [out] An acquisition token if succeeded. Must call qrmi_string_free() to free if no longer used.
1304 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1305 * @version 0.6.0
1306 */
1308 char **acquisition_token);
1309
1310/**
1311 * @ingroup QrmiQuantumResource
1312 * Releases quantum resource.
1313 *
1314 * # Safety
1315 *
1316 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
1317 *
1318 * * `acquisition_token` must contain the nul terminator.
1319 *
1320 * * The nul terminator must be within `isize::MAX` from `acquisition_token`
1321 *
1322 * # Example
1323 *
1324 * @code
1325 * char *acquisition_token = NULL;
1326 * QrmiReturnCode rc = qrmi_resource_acquire(qrmi, &acquisition_token);
1327 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1328 * rc = qrmi_resource_release(qrmi, acquisition_token);
1329 * if (rc != QRMI_RETURN_CODE_SUCCESS) {
1330 * printf("Failed to release a quantum resource\n");
1331 * }
1332 * }
1333 * @endcode
1334 *
1335 * @param (qrmi) [in] A QrmiQuantumResource handle
1336 * @param (acquisition_token) [in] An acquisition token returned by qrmi_resource_acquire() call.
1337 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1338 * @version 0.6.0
1339 */
1340QrmiReturnCode qrmi_resource_release(QrmiQuantumResource *qrmi, const char *acquisition_token);
1341
1342/**
1343 * @ingroup QrmiQuantumResource
1344 * Starts a task.
1345 *
1346 * # Safety
1347 *
1348 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
1349 *
1350 * * `task_id` must be non-null.
1351 *
1352 * * The memory pointed to by `input` and `program_id` in QrmiPayload_QiskitPrimitive_Body contain a valid nul terminator.
1353 *
1354 * * The memory pointed to by `sequence` in QrmiPayload_PasqalCloud_Body must contain a valid nul terminator.
1355 *
1356 * * The memory pointed to by `job_spec` in QrmiPayload_Oqtopus_Body
1357 * must contain a valid nul terminator.
1358 *
1359 * # Example
1360 *
1361 * @code
1362 * QrmiPayload payload;
1363 * char *job_id = NULL;
1364 * QrmiReturnCode rc;
1365 * const char* input = "your Qiskit estimator primitive input";
1366 *
1367 * payload.tag = QRMI_PAYLOAD_QISKIT_PRIMITIVE;
1368 * payload.QISKIT_PRIMITIVE.input = (char *)input;
1369 * payload.QISKIT_PRIMITIVE.program_id = "estimator";
1370 *
1371 * rc = qrmi_resource_task_start(qrmi, &payload, &job_id);
1372 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1373 * printf("Job ID: %s\n", job_id);
1374 * }
1375 * else {
1376 * printf("failed to start a task.\n");
1377 * }
1378 * @endcode
1379 *
1380 * Any failure code other than @ref QrmiReturnCode::QRMI_RETURN_CODE_ERROR means
1381 * that no task was created: QRMI or the vendor's API refused the request.
1382 * @ref QrmiReturnCode::QRMI_RETURN_CODE_ERROR leaves that unknown (e.g. a lost
1383 * response), so the task may exist.
1384 *
1385 * @param (qrmi) [in] A QrmiQuantumResource handle
1386 * @param (payload) [in] payload
1387 * @param (task_id) [out] A task identifier if succeeded. Must call qrmi_string_free() to free if no longer used.
1388 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1389 * @version 0.6.0
1390 */
1392 const QrmiPayload *payload,
1393 char **task_id);
1394
1395/**
1396 * @ingroup QrmiQuantumResource
1397 * Stops a task.
1398 *
1399 * # Safety
1400 *
1401 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
1402 *
1403 * * The memory pointed to by `task_id` must contain a valid nul terminator at the
1404 * end of the string.
1405 *
1406 * * The nul terminator must be within `isize::MAX` from `task_id`
1407 *
1408 * # Example
1409 *
1410 * @code
1411 * QrmiReturnCode rc = qrmi_resource_task_stop(qrmi, job_id);
1412 * if (rc != QRMI_RETURN_CODE_SUCCESS) {
1413 * printf("Failed to stop a task\n");
1414 * }
1415 * @endcode
1416 *
1417 * @param (qrmi) [in] A QrmiQuantumResource handle
1418 * @param (task_id) [in] A task ID, returned by a previous call to qrmi_resource_task_start()
1419 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1420 * @version 0.6.0
1421 */
1423
1424/**
1425 * @ingroup QrmiQuantumResource
1426 * Returns the status of the specified task.
1427 *
1428 * # Safety
1429 *
1430 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
1431 *
1432 * * The memory pointed to by `task_id` must contain a valid nul terminator.
1433 *
1434 * * The memory pointed to by `status` must have enough room to store `QrmiTaskStatus` value.
1435 *
1436 * * The nul terminator must be within `isize::MAX` from `task_id`
1437 *
1438 * # Example
1439 *
1440 * @code
1441 * QrmiTaskStatus status;
1442 * while (1) {
1443 * rc = qrmi_resource_task_status(qrmi, job_id, &status);
1444 * if (rc != QRMI_RETURN_CODE_SUCCESS || status != QRMI_TASK_STATUS_RUNNING) {
1445 * break;
1446 * }
1447 * sleep(1);
1448 * }
1449 * @endcode
1450 *
1451 * @param (qrmi) [in] A QrmiQuantumResource handle
1452 * @param (task_id) [in] A task identifier
1453 * @param (status) [out] A pointer to the memory to store `QrmiTaskStatus` value
1454 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1455 * @version 0.6.0
1456 */
1458 const char *task_id,
1459 QrmiTaskStatus *status);
1460
1461/**
1462 * @ingroup QrmiQuantumResource
1463 * Returns the result of a task.
1464 *
1465 * # Safety
1466 *
1467 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
1468 *
1469 * * `outp` must be non-null.
1470 *
1471 * * The memory pointed to by `task_id` must contain a valid nul terminator.
1472 *
1473 * * The nul terminator must be within `isize::MAX` from `task_id`
1474 *
1475 * # Example
1476 *
1477 * @code
1478 * QrmiReturnCode rc = qrmi_resource_task_status(qrmi, job_id, &status);
1479 * if (rc == QRMI_RETURN_CODE_SUCCESS && status == QRMI_TASK_STATUS_COMPLETED) {
1480 * char *result = NULL;
1481 * qrmi_resource_task_result(qrmi, job_id, &result);
1482 * printf("%s\n", result);
1483 * qrmi_string_free((char *)result);
1484 * }
1485 * @endcode
1486 *
1487 * @param (qrmi) [in] A QrmiQuantumResource handle
1488 * @param (task_id) [in] A task identifier
1489 * @param (outp) [out] Task result if succeeded. Must call qrmi_string_free() to free if no longer used.
1490 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1491 * @version 0.1.0
1492 */
1494 const char *task_id,
1495 char **outp);
1496
1497/**
1498 * @ingroup QrmiQuantumResource
1499 * Returns the log messages of a task.
1500 *
1501 * # Safety
1502 *
1503 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
1504 *
1505 * * `outp` must be non-null.
1506 *
1507 * * The memory pointed to by `task_id` must contain a valid nul terminator.
1508 *
1509 * * The nul terminator must be within `isize::MAX` from `task_id`
1510 *
1511 * # Example
1512 *
1513 * @code
1514 * QrmiReturnCode rc = qrmi_resource_task_status(qrmi, job_id, &status);
1515 * if (rc == QRMI_RETURN_CODE_SUCCESS && status == QRMI_TASK_STATUS_COMPLETED) {
1516 * char *logs = NULL;
1517 * qrmi_resource_task_logs(qrmi, job_id, &logs);
1518 * printf("%s\n", logs);
1519 * qrmi_string_free((char *)logs);
1520 * }
1521 * @endcode
1522 *
1523 * @param (qrmi) [in] A QrmiQuantumResource handle
1524 * @param (task_id) [in] A task identifier
1525 * @param (outp) [out] Task log messages if succeeded. Must call qrmi_string_free() to free if no longer used.
1526 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1527 * @version 0.1.0
1528 */
1530 const char *task_id,
1531 char **outp);
1532
1533/**
1534 * @ingroup QrmiQuantumResource
1535 * 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](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_configuration_schema.json) and [BackendProperties](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_properties_schema.json) so that we are able to create a Target object by calling `qiskit_ibm_runtime.utils.backend_converter.convert_to_target` or uquivalent functions.
1536 *
1537 * # Safety
1538 *
1539 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
1540 *
1541 * * `outp` must be non-null.
1542 *
1543 * # Example
1544 *
1545 * @code
1546 * char *target = NULL;
1547 * QrmiReturnCode rc;
1548 * rc = qrmi_resource_target(qrmi, &target);
1549 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1550 * printf("target = %s\n", target);
1551 * qrmi_string_free(target);
1552 * }
1553 * @endcode
1554 *
1555 * @param (qrmi) [in] A QrmiQuantumResource handle
1556 * @param (outp) [out] A serialized target data if succeeded. Must call qrmi_string_free() to free if no longer used.
1557 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1558 * @version 0.1.0
1559 */
1561 char **outp);
1562
1563/**
1564 * @ingroup QrmiQuantumResource
1565 * Returns a resource metadata
1566 *
1567 * # Safety
1568 *
1569 * * `qrmi` must have been returned by a previous call to qrmi_resource_new().
1570 *
1571 * * `outp` must be non-null.
1572 *
1573 * # Example
1574 *
1575 * @code
1576 * QrmiResourceMetadata *metadata = NULL;
1577 * QrmiReturnCode rc = qrmi_resource_metadata(qrmi, &metadata);
1578 * @endcode
1579 *
1580 * @param (qrmi) [in] A QrmiQuantumResource handle
1581 * @param (outp) [out] A QrmiResourceMetadata handle. Must call qrmi_resource_metadata_free() to free if no longer used.
1582 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1583 * @version 0.6.0
1584 */
1586 QrmiResourceMetadata **outp);
1587
1588/**
1589 * @ingroup QrmiResourceMetadata
1590 * Frees the memory space pointed to by `ptr`, which must have been returned by a previous call to qrmi_resource_metadata(). Otherwise, or if ptr has already been freed, segmentation fault occurs. If `ptr` is NULL, returns < 0.
1591 * # Safety
1592 *
1593 * * `ptr` must have been returned by a previous call to qrmi_resource_metadata().
1594 *
1595 * # Example
1596 *
1597 * @code
1598 * QrmiResourceMetadata *metadata = NULL;
1599 * QrmiReturnCode rc = qrmi_resource_metadata(qrmi, &metadata);
1600 * if (retval == QRMI_RETURN_CODE_SUCCESS) {
1601 * qrmi_resource_metadata_free(metadata);
1602 * }
1603 * @endcode
1604 *
1605 * @param (ptr) [in] A QrmiResourceMetadata handle to be free
1606 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1607 * @version 0.6.0
1608 */
1610
1611/**
1612 * @ingroup QrmiResourceMetadata
1613 * Returns metadata value of the specified key
1614 *
1615 * # Safety
1616 *
1617 * * `metadata` must have been returned by a previous call to qrmi_resource_metadata().
1618 *
1619 * * The memory pointed to by `key` must contain a valid nul terminator.
1620 *
1621 * * The nul terminator must be within `isize::MAX` from `key`.
1622 *
1623 * # Example
1624 *
1625 * @code
1626 * char *value = qrmi_resource_metadata_value(metadata, "backend_name");
1627 * printf("metadata value=[%s]\n", value);
1628 * qrmi_string_free(value);
1629 * @endcode
1630 *
1631 * @param (metadata) [in] A QrmiResourceMetadata handle
1632 * @param (key) [in] metadata key name
1633 * @return metadata value if succeeded. Must call qrmi_string_free() to free if no longer used.
1634 * @version 0.6.0
1635 */
1636char *qrmi_resource_metadata_value(QrmiResourceMetadata *metadata, const char *key);
1637
1638/**
1639 * @ingroup QrmiResourceMetadata
1640 * Returns a list of the metadata keys
1641 *
1642 * # Safety
1643 *
1644 * * `metadata` must have been returned by a previous call to qrmi_resource_metadata().
1645 *
1646 * * `num_keys` and `key_names` must be non-null.
1647 *
1648 * # Example
1649 *
1650 * @code
1651 * size_t num_keys = 0;
1652 * char **metadata_keys = NULL;
1653 * QrmiReturnCode rc = qrmi_resource_metadata_keys(metadata, &num_keys, &metadata_keys);
1654 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1655 * for (int i = 0; i < num_keys; i++) {
1656 * printf("%s\n", metadata_keys[i]);
1657 * }
1658 * qrmi_string_array_free(num_keys, metadata_keys);
1659 * }
1660 * @endcode
1661 *
1662 * @param (metadata) [in] A QrmiResourceMetadata handle
1663 * @param (num_keys) [out] number of keys available in the metadata
1664 * @param (key_names) [out] A list of metadata key names if succeeded. Must call qrmi_string_array_free() to free if no longer used.
1665 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1666 */
1668 size_t *num_keys,
1669 char **key_names[]);
1670
1671/**
1672 * @ingroup QrmiResourceProvider
1673 * Returns a QrmiResourceProvider handle for the specified resource type and environment.
1674 *
1675 * Created handle must be released with qrmi_provider_free() when no longer needed.
1676 *
1677 * Currently supported resource types:
1678 * - @ref QrmiResourceType::QRMI_RESOURCE_TYPE_QISKIT_RUNTIME_SERVICE(deprecated)
1679 * - @ref QrmiResourceType::QRMI_RESOURCE_TYPE_IBM_QUANTUM_COMPUTE_SERVICE
1680 * - @ref QrmiResourceType::QRMI_RESOURCE_TYPE_IBM_QUANTUM_SYSTEM
1681 *
1682 * # Safety
1683 *
1684 * * `environments` must be a valid pointer to a QrmiEnvironmentVariables struct.
1685 *
1686 * # Example
1687 *
1688 * @code
1689 * QrmiConfig *config = qrmi_config_load("/path/to/qrmi_config.json");
1690 * QrmiResourceDef *def = qrmi_config_resource_def_get(config, "ibm_inst1");
1691 * QrmiResourceProvider *provider = qrmi_provider_new(def->type, &def->environments);
1692 * if (provider == NULL) {
1693 * char *err = qrmi_get_last_error();
1694 * printf("error: %s\n", err);
1695 * qrmi_string_free(err);
1696 * }
1697 * @endcode
1698 *
1699 * @param (resource_type) [in] QrmiResourceType variant
1700 * @param (environments) [in] Pointer to QrmiEnvironmentVariables
1701 * @return A QrmiResourceProvider handle if succeeded, otherwise NULL.
1702 * Must call qrmi_provider_free() to free if no longer used.
1703 * @version 0.15.0
1704 */
1706 const QrmiEnvironmentVariables *environments);
1707
1708/**
1709 * @ingroup QrmiResourceProvider
1710 * Frees the memory space pointed to by `ptr`, which must have been returned by
1711 * a previous call to qrmi_provider_new(). If `ptr` is NULL, returns NullPointerError.
1712 *
1713 * # Safety
1714 *
1715 * * `ptr` must have been returned by a previous call to qrmi_provider_new().
1716 *
1717 * # Example
1718 *
1719 * @code
1720 * QrmiConfig *config = qrmi_config_load("/path/to/qrmi_config.json");
1721 * QrmiResourceDef *def = qrmi_config_resource_def_get(config, "ibm_inst1");
1722 * QrmiResourceProvider *provider = qrmi_provider_new(def->type, &def->environments);
1723 * if (provider != NULL) {
1724 * qrmi_provider_free(provider);
1725 * }
1726 * @endcode
1727 *
1728 * @param (ptr) [in] A QrmiResourceProvider handle to be freed
1729 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1730 * @version 0.15.0
1731 */
1733
1734/**
1735 * @ingroup QrmiResourceProvider
1736 * Returns a list of available quantum resources, optionally filtered.
1737 *
1738 * Results are expected to be sorted in least-busy order.
1739 *
1740 * The caller is responsible for freeing the returned struct with
1741 * qrmi_provider_resources_free(). Individual handles inside the struct
1742 * must NOT be freed separately.
1743 *
1744 * # Safety
1745 *
1746 * * `provider` must have been returned by a previous call to qrmi_provider_new().
1747 * * `filters` may be NULL (no filtering) or a valid nul-terminated C string.
1748 * * `resources_out` must be non-null and point to a zero-initialized QrmiQuantumResources.
1749 *
1750 * # Filter string format
1751 *
1752 * `key=value` pairs joined by `&`. Supported filters(constraints) are defined by each resource provider's implementation.
1753 *
1754 * # Example
1755 *
1756 * @code
1757 * QrmiQuantumResources resources = {0};
1758 * QrmiReturnCode rc = qrmi_provider_resources(provider, "num_qubits=127", &resources);
1759 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1760 * for (size_t i = 0; i < resources.length; i++) {
1761 * char *id = NULL;
1762 * qrmi_resource_id(resources.resources[i], &id);
1763 * printf("resource: %s\n", id);
1764 * qrmi_string_free(id);
1765 * }
1766 * qrmi_provider_resources_free(&resources);
1767 * }
1768 * @endcode
1769 *
1770 * @param (provider) [in] A QrmiResourceProvider handle
1771 * @param (filters) [in] Filter string, or NULL for no filtering
1772 * @param (resources_out) [out] Pointer to a QrmiQuantumResources struct to populate
1773 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1774 * @version 0.15.0
1775 */
1777 const char *filters,
1778 QrmiQuantumResources *resources_out);
1779
1780/**
1781 * @ingroup QrmiResourceProvider
1782 * Frees a QrmiQuantumResources struct populated by qrmi_provider_resources().
1783 *
1784 * This frees both the individual QrmiQuantumResource handles and the internal
1785 * array. After calling this, the struct's fields are zeroed.
1786 * Do NOT call qrmi_resource_free() on individual elements after calling this.
1787 *
1788 * # Safety
1789 *
1790 * * `resources` must have been populated by a previous call to qrmi_provider_resources().
1791 *
1792 * # Example
1793 *
1794 * @code
1795 * qrmi_provider_resources_free(&resources);
1796 * @endcode
1797 *
1798 * @param (resources) [in] Pointer to a QrmiQuantumResources struct to free
1799 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1800 * @version 0.15.0
1801 */
1803
1804/**
1805 * @ingroup QrmiResourceProvider
1806 * Returns the least busy available quantum resource, optionally filtered.
1807 *
1808 * Equivalent to calling qrmi_provider_resources() and taking the first element.
1809 * If no resources match the filter, `*resource_out` is set to NULL and the
1810 * function returns QRMI_RETURN_CODE_SUCCESS.
1811 *
1812 * The returned QrmiQuantumResource handle must be freed with qrmi_resource_free()
1813 * when no longer needed.
1814 *
1815 * # Safety
1816 *
1817 * * `provider` must have been returned by a previous call to qrmi_provider_new().
1818 * * `filters` may be NULL (no filtering) or a valid nul-terminated C string.
1819 * * `resource_out` must be non-null.
1820 *
1821 * # Example
1822 *
1823 * @code
1824 * QrmiQuantumResource *resource = NULL;
1825 * QrmiReturnCode rc = qrmi_provider_least_busy(provider, NULL, &resource);
1826 * if (rc == QRMI_RETURN_CODE_SUCCESS && resource != NULL) {
1827 * char *id = NULL;
1828 * qrmi_resource_id(resource, &id);
1829 * printf("least busy: %s\n", id);
1830 * qrmi_string_free(id);
1831 * qrmi_resource_free(resource);
1832 * }
1833 * @endcode
1834 *
1835 * @param (provider) [in] A QrmiResourceProvider handle
1836 * @param (filters) [in] Filter string, or NULL for no filtering
1837 * @param (resource_out) [out] Least busy QrmiQuantumResource handle, or NULL if none found
1838 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1839 * @version 0.15.0
1840 */
1842 const char *filters,
1843 QrmiQuantumResource **resource_out);
1844
1845/**
1846 * @ingroup QrmiService
1847 * Discovers the QPU resources assigned to the current job -- read from the
1848 * `QRMI_JOB_QPU_RESOURCES` / `QRMI_JOB_QPU_TYPES` environment variables, or
1849 * their legacy `SLURM_JOB_QPU_RESOURCES` / `SLURM_JOB_QPU_TYPES`
1850 * equivalents -- and returns the ones that are currently accessible.
1851 *
1852 * This is the C counterpart of `qrmi.QRMIService` (Python) and
1853 * `qrmi::QRMIService` (Rust); all three share the same underlying
1854 * discovery/filtering logic.
1855 *
1856 * Unlike qrmi_provider_resources(), which is called against a persistent
1857 * QrmiResourceProvider handle (and can be called repeatedly, e.g. with
1858 * different filters), this function takes no arguments and is a one-shot
1859 * operation: there is no separate "service" handle to create or free.
1860 * Discovery happens inline, and each QrmiQuantumResource handle placed in
1861 * `resources_out` is independently owned by the caller from that point on
1862 * -- usable with the same qrmi_resource_*() functions as a handle returned
1863 * by qrmi_resource_new(), just not individually freed (see
1864 * qrmi_service_resources_free() below).
1865 *
1866 * The caller is responsible for freeing the returned struct with
1867 * qrmi_service_resources_free(). Individual handles inside the struct must
1868 * NOT be freed separately.
1869 *
1870 * # Safety
1871 *
1872 * * `resources_out` must be non-null and point to a zero-initialized
1873 * QrmiQuantumResources.
1874 *
1875 * # Example
1876 *
1877 * @code
1878 * QrmiQuantumResources resources = {0};
1879 * QrmiReturnCode rc = qrmi_service_resources(&resources);
1880 * if (rc == QRMI_RETURN_CODE_SUCCESS) {
1881 * for (size_t i = 0; i < resources.length; i++) {
1882 * char *id = NULL;
1883 * qrmi_resource_id(resources.resources[i], &id);
1884 * printf("resource: %s\n", id);
1885 * qrmi_string_free(id);
1886 * }
1887 * qrmi_service_resources_free(&resources);
1888 * } else {
1889 * const char *err = qrmi_get_last_error();
1890 * printf("error: %s\n", err);
1891 * }
1892 * @endcode
1893 *
1894 * @param (resources_out) [out] Pointer to a QrmiQuantumResources struct to populate
1895 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1896 * @version 0.23.0
1897 */
1899
1900/**
1901 * @ingroup QrmiService
1902 * Frees a QrmiQuantumResources struct populated by qrmi_service_resources().
1903 *
1904 * This frees both the individual QrmiQuantumResource handles and the
1905 * internal array. After calling this, the struct's fields are zeroed.
1906 * Do NOT call qrmi_resource_free() on individual elements after calling
1907 * this.
1908 *
1909 * # Safety
1910 *
1911 * * `resources` must have been populated by a previous call to
1912 * qrmi_service_resources().
1913 *
1914 * # Example
1915 *
1916 * @code
1917 * qrmi_service_resources_free(&resources);
1918 * @endcode
1919 *
1920 * @param (resources) [in] Pointer to a QrmiQuantumResources struct to free
1921 * @return @ref QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
1922 * @version 0.23.0
1923 */
1925
1926#ifdef __cplusplus
1927} // extern "C"
1928#endif // __cplusplus
1929
1930#endif /* QRMI_H */
const char * qrmi_config_resource_type_to_str(QrmiResourceType type)
QrmiConfig * qrmi_config_load(const char *filename)
QrmiReturnCode qrmi_config_free(QrmiConfig *ptr)
QrmiResourceDef * qrmi_config_resource_def_get(QrmiConfig *config, const char *resource_id)
QrmiReturnCode qrmi_config_resource_names_get(QrmiConfig *config, size_t *num_names, char **names[])
QrmiReturnCode qrmi_config_resource_type_from_str(const char *type_str, QrmiResourceType *outp)
QrmiReturnCode qrmi_config_resource_def_free(QrmiResourceDef *ptr)
QrmiReturnCode qrmi_resource_acquire(QrmiQuantumResource *qrmi, char **acquisition_token)
QrmiReturnCode qrmi_resource_task_stop(QrmiQuantumResource *qrmi, const char *task_id)
QrmiReturnCode qrmi_resource_target(QrmiQuantumResource *qrmi, char **outp)
QrmiQuantumResource * qrmi_resource_new(const char *resource_id, QrmiResourceType resource_type)
QrmiReturnCode qrmi_resource_task_logs(QrmiQuantumResource *qrmi, const char *task_id, char **outp)
QrmiReturnCode qrmi_resource_release(QrmiQuantumResource *qrmi, const char *acquisition_token)
QrmiReturnCode qrmi_resource_task_result(QrmiQuantumResource *qrmi, const char *task_id, char **outp)
QrmiReturnCode qrmi_resource_free(QrmiQuantumResource *ptr)
QrmiReturnCode qrmi_resource_metadata(QrmiQuantumResource *qrmi, QrmiResourceMetadata **outp)
QrmiReturnCode qrmi_resource_type(QrmiQuantumResource *qrmi, QrmiResourceType *outp)
QrmiQuantumResource * qrmi_resource_new_from_config(const char *resource_id, QrmiResourceType resource_type, const QrmiConfigMap *config)
QrmiReturnCode qrmi_resource_status(QrmiQuantumResource *qrmi, QrmiResourceStatus **outp)
QrmiReturnCode qrmi_resource_id(QrmiQuantumResource *qrmi, char **outp)
QrmiReturnCode qrmi_resource_task_start(QrmiQuantumResource *qrmi, const QrmiPayload *payload, char **task_id)
QrmiReturnCode qrmi_resource_task_status(QrmiQuantumResource *qrmi, const char *task_id, QrmiTaskStatus *status)
QrmiReturnCode qrmi_resource_is_accessible(QrmiQuantumResource *qrmi, bool *outp)
char * qrmi_resource_metadata_value(QrmiResourceMetadata *metadata, const char *key)
QrmiReturnCode qrmi_resource_metadata_free(QrmiResourceMetadata *ptr)
QrmiReturnCode qrmi_resource_metadata_keys(QrmiResourceMetadata *metadata, size_t *num_keys, char **key_names[])
QrmiReturnCode qrmi_provider_resources_free(QrmiQuantumResources *resources)
QrmiReturnCode qrmi_provider_free(QrmiResourceProvider *ptr)
QrmiReturnCode qrmi_provider_resources(QrmiResourceProvider *provider, const char *filters, QrmiQuantumResources *resources_out)
QrmiResourceProvider * qrmi_provider_new(QrmiResourceType resource_type, const QrmiEnvironmentVariables *environments)
QrmiReturnCode qrmi_provider_least_busy(QrmiResourceProvider *provider, const char *filters, QrmiQuantumResource **resource_out)
QrmiReturnCode qrmi_service_resources_free(QrmiQuantumResources *resources)
QrmiReturnCode qrmi_service_resources(QrmiQuantumResources *resources_out)
char * qrmi_get_last_error(void)
QrmiReturnCode qrmi_log_callback_set(QrmiLogCallback callback)
QrmiReturnCode qrmi_string_free(char *ptr)
QrmiReturnCode qrmi_string_array_free(size_t size, char *array[])
QrmiReturnCode qrmi_resource_status_code(QrmiResourceStatus *status, QrmiResourceStatusCode *outp)
struct QrmiResourceStatus QrmiResourceStatus
Definition qrmi.h:242
QrmiReturnCode qrmi_resource_status_free(QrmiResourceStatus *ptr)
QrmiPayload_Tag
Definition qrmi.h:321
@ QRMI_PAYLOAD_ALICE_BOB_FELIS
Definition qrmi.h:330
@ QRMI_PAYLOAD_MAESTRO_LOCAL
Definition qrmi.h:342
@ QRMI_PAYLOAD_QISKIT_PRIMITIVE
Definition qrmi.h:325
@ QRMI_PAYLOAD_PASQAL_CLOUD
Definition qrmi.h:329
@ QRMI_PAYLOAD_OQTOPUS
Definition qrmi.h:338
@ QRMI_PAYLOAD_IQM_SERVER
Definition qrmi.h:334
QrmiReturnCode qrmi_resource_status_capacity(QrmiResourceStatus *status, QrmiResourceCapacity **outp)
QrmiReturnCode
Definition qrmi.h:55
@ QRMI_RETURN_CODE_PARSE_ERROR
Definition qrmi.h:77
@ QRMI_RETURN_CODE_MISSING_CONFIG_KEY_ERROR
Definition qrmi.h:97
@ QRMI_RETURN_CODE_UNSUPPORTED_RESOURCE_TYPE_ERROR
Definition qrmi.h:81
@ QRMI_RETURN_CODE_UNSUPPORTED_PAYLOAD_ERROR
Definition qrmi.h:89
@ QRMI_RETURN_CODE_AUTHENTICATION_FAILED_ERROR
Definition qrmi.h:115
@ QRMI_RETURN_CODE_RESOURCE_NOT_FOUND_ERROR
Definition qrmi.h:106
@ QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR
Definition qrmi.h:85
@ QRMI_RETURN_CODE_INVALID_CONFIG_ERROR
Definition qrmi.h:119
@ QRMI_RETURN_CODE_NULL_POINTER_ERROR
Definition qrmi.h:69
@ QRMI_RETURN_CODE_ERROR
Definition qrmi.h:65
@ QRMI_RETURN_CODE_TASK_NOT_READY_ERROR
Definition qrmi.h:93
@ QRMI_RETURN_CODE_INVALID_INPUT_ERROR
Definition qrmi.h:102
@ QRMI_RETURN_CODE_SUCCESS
Definition qrmi.h:59
@ QRMI_RETURN_CODE_TASK_NOT_FOUND_ERROR
Definition qrmi.h:111
@ QRMI_RETURN_CODE_ENV_VAR_NOT_SET_ERROR
Definition qrmi.h:73
QrmiResourceStatusCode
Definition qrmi.h:158
@ QRMI_RESOURCE_STATUS_CODE_PAUSED
Definition qrmi.h:171
@ QRMI_RESOURCE_STATUS_CODE_ONLINE
Definition qrmi.h:162
@ QRMI_RESOURCE_STATUS_CODE_OFFLINE
Definition qrmi.h:166
QrmiReturnCode qrmi_resource_status_healthy(QrmiResourceStatus *status, bool *outp)
QrmiReturnCode qrmi_resource_status_busy(QrmiResourceStatus *status, bool *outp)
QrmiResourceType
Definition qrmi.h:125
@ QRMI_RESOURCE_TYPE_IBM_QUANTUM_SYSTEM
Definition qrmi.h:129
@ QRMI_RESOURCE_TYPE_QISKIT_RUNTIME_SERVICE
Definition qrmi.h:133
@ QRMI_RESOURCE_TYPE_OQTOPUS
Definition qrmi.h:148
@ QRMI_RESOURCE_TYPE_IQM_SERVER
Definition qrmi.h:147
@ QRMI_RESOURCE_TYPE_MAESTRO_LOCAL
Definition qrmi.h:152
@ QRMI_RESOURCE_TYPE_IBM_QUANTUM_COMPUTE_SERVICE
Definition qrmi.h:137
@ QRMI_RESOURCE_TYPE_ALICE_BOB_FELIS
Definition qrmi.h:146
@ QRMI_RESOURCE_TYPE_PASQAL_LOCAL
Definition qrmi.h:142
@ QRMI_RESOURCE_TYPE_PASQAL_CLOUD
Definition qrmi.h:141
const char * qrmi_resource_status_code_to_string(QrmiResourceStatusCode code)
char * qrmi_resource_status_reason(QrmiResourceStatus *status)
struct QrmiQuantumResource QrmiQuantumResource
Definition qrmi.h:227
struct QrmiResourceProvider QrmiResourceProvider
Definition qrmi.h:237
QrmiEnvironmentVariables QrmiConfigMap
Definition qrmi.h:305
QrmiReturnCode qrmi_get_last_error_kind(void)
void(* QrmiLogCallback)(const char *level, const char *target, const char *message)
Definition qrmi.h:250
QrmiTaskStatus
Definition qrmi.h:177
@ QRMI_TASK_STATUS_CANCELLED
Definition qrmi.h:197
@ QRMI_TASK_STATUS_QUEUED
Definition qrmi.h:181
@ QRMI_TASK_STATUS_COMPLETED
Definition qrmi.h:189
@ QRMI_TASK_STATUS_FAILED
Definition qrmi.h:193
@ QRMI_TASK_STATUS_RUNNING
Definition qrmi.h:185
QrmiReturnCode qrmi_resource_capacity_free(QrmiResourceCapacity *ptr)
struct QrmiResourceMetadata QrmiResourceMetadata
Definition qrmi.h:232
struct QrmiConfig QrmiConfig
Definition qrmi.h:222
QrmiReturnCode qrmi_resource_status_pending_job_count(QrmiResourceStatus *status, uint64_t *outp)
Definition qrmi.h:269
QrmiKeyValue * variables
Definition qrmi.h:273
size_t length
Definition qrmi.h:277
Definition qrmi.h:255
char * value
Definition qrmi.h:263
char * key
Definition qrmi.h:259
Definition qrmi.h:367
char * human_qir
Definition qrmi.h:371
char * input_params
Definition qrmi.h:375
Definition qrmi.h:378
char * job_type
Definition qrmi.h:386
char * tag
Definition qrmi.h:395
char * iqmjson
Definition qrmi.h:382
int use_timeslot
Definition qrmi.h:391
Definition qrmi.h:414
char * input
Definition qrmi.h:418
uint32_t simulation_method
Definition qrmi.h:434
char * config
Definition qrmi.h:442
uint32_t qubits
Definition qrmi.h:426
uint32_t simulator_type
Definition qrmi.h:430
char * job_type
Definition qrmi.h:422
char * observables
Definition qrmi.h:438
Definition qrmi.h:398
char * job_spec
Definition qrmi.h:411
Definition qrmi.h:356
char * sequence
Definition qrmi.h:360
int32_t job_runs
Definition qrmi.h:364
char * program_id
Definition qrmi.h:353
char * input
Definition qrmi.h:349
Definition qrmi.h:445
QrmiPayload_MaestroLocal_Body MAESTRO_LOCAL
Definition qrmi.h:453
QrmiPayload_PasqalCloud_Body PASQAL_CLOUD
Definition qrmi.h:449
QrmiPayload_IQMServer_Body IQM_SERVER
Definition qrmi.h:451
QrmiPayload_Tag tag
Definition qrmi.h:446
QrmiPayload_AliceBobFelis_Body ALICE_BOB_FELIS
Definition qrmi.h:450
QrmiPayload_QiskitPrimitive_Body QISKIT_PRIMITIVE
Definition qrmi.h:448
QrmiPayload_Oqtopus_Body OQTOPUS
Definition qrmi.h:452
Definition qrmi.h:462
QrmiQuantumResource ** resources
Definition qrmi.h:466
size_t length
Definition qrmi.h:470
Definition qrmi.h:310
uint64_t max_slots
Definition qrmi.h:318
uint64_t available_slots
Definition qrmi.h:314
Definition qrmi.h:283
QrmiEnvironmentVariables environments
Definition qrmi.h:299
bool is_dynamic
Definition qrmi.h:295
QrmiResourceType type
Definition qrmi.h:291
char * name
Definition qrmi.h:287