qe/orbit 0.3.23 update - #5597
Open
nic-ezzell-QE wants to merge 3 commits into
Open
Conversation
- corrects batch mode execution to be consistent with Quantum Elements Orbit version: 0.3.23 - adds additional details on parameter meanings
- Adds scalings plots to the getting started - Makes broader picure more understandable
- Orbit now supports batch mode, details are now in the API ref - Updated error codes for Orbit, including new error codes for batch mode and other changes
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
Contributor
|
Thanks for contributing to Qiskit documentation! Before your PR can be merged, it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient. Thanks! 🙌 One or more of the following people are relevant to this code:
|
|
|
abbycross
reviewed
Sep 1, 2026
| </CardGroup> | ||
|
|
||
| Quantum Elements Orbit is a Qiskit Function that prepares quantum circuits for a selected IBM Quantum® backend, inserts dynamical decoupling (DD) into scheduled idle windows, and runs the resulting workload through an IBM Quantum primitive. Orbit accepts Sampler and Estimator PUBs and returns a standard [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) with Orbit-specific metadata attached to the top-level result and to each [Primitive Unified Bloc (PUB)](/docs/guides/primitive-input-output) result. | ||
| Quantum Elements Orbit is a Qiskit Function that prepares quantum circuits for a selected IBM Quantum® backend, inserts dynamical decoupling (DD) into scheduled idle windows, and runs the resulting workload through an IBM Quantum primitive. Workloads can run as one Quantum Compute job or be partitioned across child jobs in a server-side Qiskit Runtime Batch. Orbit accepts Sampler and Estimator PUBs and returns a standard [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) with Orbit-specific metadata attached to the top-level result and to each [Primitive Unified Bloc (PUB)](/docs/guides/primitive-input-output) result. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Quantum Elements Orbit is a Qiskit Function that prepares quantum circuits for a selected IBM Quantum® backend, inserts dynamical decoupling (DD) into scheduled idle windows, and runs the resulting workload through an IBM Quantum primitive. Workloads can run as one Quantum Compute job or be partitioned across child jobs in a server-side Qiskit Runtime Batch. Orbit accepts Sampler and Estimator PUBs and returns a standard [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) with Orbit-specific metadata attached to the top-level result and to each [Primitive Unified Bloc (PUB)](/docs/guides/primitive-input-output) result. | |
| Quantum Elements Orbit is a Qiskit Function that prepares quantum circuits for a selected IBM Quantum® backend, inserts dynamical decoupling (DD) into scheduled idle windows, and runs the resulting workload through an IBM Quantum primitive. Workloads can run as one Quantum Compute job or be partitioned across child jobs in a server-side `qiskit-ibm-runtime` batch. Orbit accepts Sampler and Estimator PUBs and returns a standard [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) with Orbit-specific metadata attached to the top-level result and to each [Primitive Unified Bloc (PUB)](/docs/guides/primitive-input-output) result. |
abbycross
reviewed
Sep 1, 2026
| - Valid input types: `dict` or `None` | ||
|
|
||
| Options control transpilation, DD insertion, Quantum Compute options, preview mode, simulator mode, backend-information export, and measurement error mitigation. | ||
| Options control transpilation, DD insertion, Quantum Compute options, Runtime Batch execution, preview mode, simulator mode, backend-information export, and measurement error mitigation. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Options control transpilation, DD insertion, Quantum Compute options, Runtime Batch execution, preview mode, simulator mode, backend-information export, and measurement error mitigation. | |
| Options control transpilation, DD insertion, Quantum Compute options, `qiskit-ibm-runtime` batch execution, preview mode, simulator mode, backend-information export, and measurement error mitigation. |
abbycross
reviewed
Sep 1, 2026
|
|
||
| <Attribute attributeTypeHint="dict or None" attributeValue="None"> | ||
|
|
||
| Server-side [Qiskit Runtime Batch](/docs/guides/run-jobs-batch) configuration. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Server-side [Qiskit Runtime Batch](/docs/guides/run-jobs-batch) configuration. | |
| Server-side [`qiskit-ibm-runtime` batch](/docs/guides/run-jobs-batch) configuration. |
abbycross
reviewed
Sep 1, 2026
Comment on lines
+509
to
+513
| - When supplied, Orbit partitions the prepared PUBs in input order, creates the authenticated Runtime Batch inside the remote Function, submits all child jobs, closes the Batch, and then collects and merges the child results in the original PUB order. | ||
| - Batch mode is intended for independent workloads whose PUBs are known up front, such as parameter sweeps or curve generation. Use a Runtime session instead when later inputs depend on earlier results. | ||
| - Batch mode requires execution on a real IBM Quantum backend and is incompatible with `preview=True` or `simulator=True`. | ||
| - The configuration must be JSON serializable. Do not create a local `qiskit_ibm_runtime.Batch` object and pass it to `orbit.run(...)`; a caller-created Batch cannot control the asynchronous Qiskit Function execution environment. | ||
| - If the PUB count is less than or equal to `max_pubs_per_job`, Orbit creates one child job and the Batch provides no partition parallelism. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - When supplied, Orbit partitions the prepared PUBs in input order, creates the authenticated Runtime Batch inside the remote Function, submits all child jobs, closes the Batch, and then collects and merges the child results in the original PUB order. | |
| - Batch mode is intended for independent workloads whose PUBs are known up front, such as parameter sweeps or curve generation. Use a Runtime session instead when later inputs depend on earlier results. | |
| - Batch mode requires execution on a real IBM Quantum backend and is incompatible with `preview=True` or `simulator=True`. | |
| - The configuration must be JSON serializable. Do not create a local `qiskit_ibm_runtime.Batch` object and pass it to `orbit.run(...)`; a caller-created Batch cannot control the asynchronous Qiskit Function execution environment. | |
| - If the PUB count is less than or equal to `max_pubs_per_job`, Orbit creates one child job and the Batch provides no partition parallelism. | |
| - When supplied, Orbit partitions the prepared PUBs in input order, creates the authenticated batch inside the remote Function, submits all child jobs, closes the batch, and then collects and merges the child results in the original PUB order. | |
| - Batch mode is intended for independent workloads whose PUBs are known up front, such as parameter sweeps or curve generation. Use [session mode](/docs/guides/run-jobs-session) instead when later inputs depend on earlier results. | |
| - Batch mode requires execution on a real IBM Quantum backend and is incompatible with `preview=True` or `simulator=True`. | |
| - The configuration must be JSON serializable. Do not create a local `qiskit_ibm_runtime.Batch` object and pass it to `orbit.run(...)`; a caller-created batch cannot control the asynchronous Qiskit Function execution environment. | |
| - If the PUB count is less than or equal to `max_pubs_per_job`, Orbit creates one child job and the batch provides no partition parallelism. |
abbycross
reviewed
Sep 1, 2026
| `max_pubs_per_job` | ||
| <Attribute attributeTypeHint="int"> | ||
|
|
||
| Maximum number of consecutive PUBs submitted in each child Runtime job. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Maximum number of consecutive PUBs submitted in each child Runtime job. | |
| Maximum number of consecutive PUBs submitted in each child job. |
abbycross
reviewed
Sep 1, 2026
| `max_time` | ||
| <Attribute attributeTypeHint="int or str or None" attributeValue="None"> | ||
|
|
||
| Optional maximum lifetime of the Runtime Batch. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Optional maximum lifetime of the Runtime Batch. | |
| Optional maximum lifetime of the `qiskit-ibm-runtime` batch. |
abbycross
reviewed
Sep 1, 2026
| - Valid input types: `int`, `str`, or `None` | ||
|
|
||
| - A positive integer specifies seconds, such as `7200`. | ||
| - A Runtime duration string contains one or more positive number-and-unit pairs using `s`, `m`, `h`, or `d`, such as `"2h"` or `"1h30m"`. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - A Runtime duration string contains one or more positive number-and-unit pairs using `s`, `m`, `h`, or `d`, such as `"2h"` or `"1h30m"`. | |
| - A duration string contains one or more positive number-and-unit pairs using `s`, `m`, `h`, or `d`, such as `"2h"` or `"1h30m"`. |
abbycross
reviewed
Sep 1, 2026
| </Attribute> | ||
| </LeftColoredBar> | ||
|
|
||
| For example, the following call partitions `ordered_pubs` into child jobs of at most 300 PUBs, all within one Runtime Batch: |
Collaborator
There was a problem hiding this comment.
Suggested change
| For example, the following call partitions `ordered_pubs` into child jobs of at most 300 PUBs, all within one Runtime Batch: | |
| For example, the following call partitions `ordered_pubs` into child jobs of at most 300 PUBs, all within one batch: |
abbycross
reviewed
Sep 1, 2026
| ## Outputs | ||
|
|
||
| The function returns a Qiskit `PrimitiveResult` containing one `PubResult` per input PUB. Orbit preserves the selected primitive's normal result data and adds Orbit metadata under `quantum_elements_orbit`. | ||
| The function returns a Qiskit `PrimitiveResult` containing one `PubResult` per input PUB. Orbit preserves the selected primitive's normal result data and adds Orbit metadata under `quantum_elements_orbit`. In Batch mode, child results are merged so the returned PUB count and order match the original input PUBs, regardless of the child-job boundaries. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The function returns a Qiskit `PrimitiveResult` containing one `PubResult` per input PUB. Orbit preserves the selected primitive's normal result data and adds Orbit metadata under `quantum_elements_orbit`. In Batch mode, child results are merged so the returned PUB count and order match the original input PUBs, regardless of the child-job boundaries. | |
| The function returns a Qiskit `PrimitiveResult` containing one `PubResult` per input PUB. Orbit preserves the selected primitive's normal result data and adds Orbit metadata under `quantum_elements_orbit`. In batch mode, child results are merged so the returned PUB count and order match the original input PUBs, regardless of the child-job boundaries. |
abbycross
reviewed
Sep 1, 2026
|
|
||
| `batch` | ||
| <Attribute attributeTypeHint="dict[str, Any]"> | ||
| Present in Batch mode. Contains the Runtime Batch ID in `id`, ordered child Runtime job IDs in `jobIds`, and ordered partition records in `partitions`. Each partition record contains `index`, `pubStart`, `pubCount`, and `jobId`. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Present in Batch mode. Contains the Runtime Batch ID in `id`, ordered child Runtime job IDs in `jobIds`, and ordered partition records in `partitions`. Each partition record contains `index`, `pubStart`, `pubCount`, and `jobId`. | |
| Present in batch mode. Contains the Runtime batch ID in `id`, ordered child job IDs in `jobIds`, and ordered partition records in `partitions`. Each partition record contains `index`, `pubStart`, `pubCount`, and `jobId`. |
abbycross
reviewed
Sep 1, 2026
| `backendInfo` | ||
| <Attribute attributeTypeHint="dict[str, Any]"> | ||
| Backend calibration export status. Includes `enabled`, `saved`, and, when available, backend name, job ID, saved path, and warnings. | ||
| Backend calibration export status. Includes `enabled`, `saved`, and, when available, backend name, job ID, saved path, and warnings. In Batch mode, `snapshots` contains one child-job export report per partition. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Backend calibration export status. Includes `enabled`, `saved`, and, when available, backend name, job ID, saved path, and warnings. In Batch mode, `snapshots` contains one child-job export report per partition. | |
| Backend calibration export status. Includes `enabled`, `saved`, and, when available, backend name, job ID, saved path, and warnings. In batch mode, `snapshots` contains one child-job export report per partition. |
abbycross
reviewed
Sep 1, 2026
|
|
||
| ### Batch output | ||
|
|
||
| For a Batch run, `result.metadata["quantum_elements_orbit"]["batch"]` maps each returned PUB range to the child Runtime job that executed it: |
Collaborator
There was a problem hiding this comment.
Suggested change
| For a Batch run, `result.metadata["quantum_elements_orbit"]["batch"]` maps each returned PUB range to the child Runtime job that executed it: | |
| For a batch run, `result.metadata["quantum_elements_orbit"]["batch"]` maps each returned PUB range to the child job that executed it: |
abbycross
reviewed
Sep 1, 2026
| print(partition["index"], partition["jobId"], start, stop) | ||
| ``` | ||
|
|
||
| `job.runtime_jobs()` exposes the child Runtime job IDs through the Qiskit Function job, and `job.runtime_sessions()` exposes the Runtime Batch ID. The Batch metadata travels with the `PrimitiveResult`, so use it when a later analysis must map PUBs to child jobs without retaining the original Function job object. |
Collaborator
There was a problem hiding this comment.
Suggested change
| `job.runtime_jobs()` exposes the child Runtime job IDs through the Qiskit Function job, and `job.runtime_sessions()` exposes the Runtime Batch ID. The Batch metadata travels with the `PrimitiveResult`, so use it when a later analysis must map PUBs to child jobs without retaining the original Function job object. | |
| `job.runtime_jobs()` exposes the child job IDs through the Qiskit Function job, and `job.runtime_sessions()` exposes the batch ID. The batch metadata travels with the `PrimitiveResult`, so use it when a later analysis must map PUBs to child jobs without retaining the original Function job object. |
abbycross
reviewed
Sep 1, 2026
| Check the error `message` and `details` fields first. They identify the invalid field, backend, PUB index, or upstream Quantum Compute failure when Orbit can determine it. | ||
|
|
||
| - Input validation errors use code `1221`. These include invalid option types, unknown option keys, empty `pubs`, invalid `dd_strategy`, invalid `pub_options` length, `dd_qubits` with resolved `transpilation_mode` other than `"validate"`, caller-prepared circuits that are not compatible with the selected backend target, invalid `physical_layout` values, and incompatible MEM requests such as `mem=True` with `primitive="estimator"`, `preview=True`, or `simulator=True`. | ||
| - Input validation errors use code `1221`. These include invalid option types, unknown option keys, empty `pubs`, invalid `dd_strategy`, invalid `pub_options` length, `dd_qubits` with resolved `transpilation_mode` other than `"validate"`, caller-prepared circuits that are not compatible with the selected backend target, invalid `physical_layout` values, a missing or non-positive `batch.max_pubs_per_job`, an invalid `batch.max_time`, Batch mode combined with preview or simulator mode, and incompatible MEM requests such as `mem=True` with `primitive="estimator"`, `preview=True`, or `simulator=True`. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - Input validation errors use code `1221`. These include invalid option types, unknown option keys, empty `pubs`, invalid `dd_strategy`, invalid `pub_options` length, `dd_qubits` with resolved `transpilation_mode` other than `"validate"`, caller-prepared circuits that are not compatible with the selected backend target, invalid `physical_layout` values, a missing or non-positive `batch.max_pubs_per_job`, an invalid `batch.max_time`, Batch mode combined with preview or simulator mode, and incompatible MEM requests such as `mem=True` with `primitive="estimator"`, `preview=True`, or `simulator=True`. | |
| - Input validation errors use code `1221`. These include invalid option types, unknown option keys, empty `pubs`, invalid `dd_strategy`, invalid `pub_options` length, `dd_qubits` with resolved `transpilation_mode` other than `"validate"`, caller-prepared circuits that are not compatible with the selected backend target, invalid `physical_layout` values, a missing or non-positive `batch.max_pubs_per_job`, an invalid `batch.max_time`, batch mode combined with preview or simulator mode, and incompatible MEM requests such as `mem=True` with `primitive="estimator"`, `preview=True`, or `simulator=True`. |
abbycross
reviewed
Sep 1, 2026
| - DD insertion, post-DD basis translation, transpilation, and QASM round-trip failures use code `1003`. These can occur when a circuit cannot be transpiled, scheduled, converted, or padded consistently for the selected backend and DD strategy. | ||
| - Quantum Compute submission failures use code `1245`; jobs that fail before producing a result use code `5203`. Orbit preserves an upstream Quantum Compute error code when one is exposed, with the Orbit fallback code in `details`. For Batch failures, `details` can also include `batch_id`, `failed_partition`, `failed_job_id`, `completed_job_ids`, and `remaining_job_ids`. | ||
| - Orbit pre-submit preparation failures that are not input, backend, or DD failures use QE code `4701`. The `details.stage` field identifies the boundary, such as `runtime_service` or `pre_submit_preparation`. | ||
| - Orbit result-shaping failures use QE code `4702`. These occur when Runtime returns a result with the wrong PUB shape or Orbit cannot attach the required metadata; `details.stage` identifies `result_iteration`, `result_shape`, `pub_metadata`, `result_metadata`, or `batch_result_merge`. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - Orbit result-shaping failures use QE code `4702`. These occur when Runtime returns a result with the wrong PUB shape or Orbit cannot attach the required metadata; `details.stage` identifies `result_iteration`, `result_shape`, `pub_metadata`, `result_metadata`, or `batch_result_merge`. | |
| - Orbit result-shaping failures use QE code `4702`. These occur when Quantum Compute returns a result with the wrong PUB shape or Orbit cannot attach the required metadata; `details.stage` identifies `result_iteration`, `result_shape`, `pub_metadata`, `result_metadata`, or `batch_result_merge`. |
Author
|
A couple of meta comments.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
We change the Quantum Elements Orbit documentation with