qe/orbit 0.3.23 update

docs/api/functions/quantum-elements-orbit.mdx

@@ -15,7 +15,7 @@ description: "API reference for Quantum Elements Orbit, including inputs, output
     />
 </CardGroup>
 
-Quantum Elements Orbit is a Qiskit Function that prepares quantum circuits for a selected IBM Quantum&reg; 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&reg; 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.
 
 <Admonition type="note" title="Default behavior">
   If `backend_name` is omitted, Orbit selects an eligible least-busy IBM Quantum backend available to IBM Quantum Compute Service. If `options` is omitted or `None`, Orbit uses its built-in defaults: transpile and schedule circuits, insert the default DD strategy, submit to the service, and attach DD insertion metadata to the result.
@@ -98,7 +98,7 @@ Function-specific options controlling Orbit execution behavior.
 - Default value: `None`
 - 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, `qiskit-ibm-runtime` batch execution, preview mode, simulator mode, backend-information export, and measurement error mitigation.
 - Unknown option keys are rejected.
 - Pass `None`, `{}`, or omit `options` to use all defaults.
 - Example: 
@@ -338,6 +338,7 @@ Whether Orbit saves backend calibration properties after an executed Quantum Com
 
 - Choices: `True` / `False`
 - When enabled, Orbit queries `service.job(job_id).properties()`, writes the serialized backend properties under `/data`, and reports the saved path in Orbit metadata.
+- In batch mode, Orbit attempts one snapshot for every child job and reports them in `backendInfo.snapshots`.
 - Failures are reported as warnings and do not discard otherwise successful primitive results.
 </Attribute>
 
@@ -484,16 +485,80 @@ options = {
 
 <Attribute attributeTypeHint="int or None" attributeValue="None">
 
-Soft cap on the Quantum Compute job's maximum execution time.
+Soft cap on each Quantum Compute primitive job's maximum execution time.
 - Required: No
 - Default value: `None`
 - Valid input types: `int` or `None`
 
 The value is specified in seconds.
 - Choices: `None` or integer > 0
 - When `None`, the Runtime default is used.
+- In batch mode, the cap is applied to every child primitive job.
 </Attribute>
 
+##### `batch`
+
+<Attribute attributeTypeHint="dict or None" attributeValue="None">
+
+Server-side [`qiskit-ibm-runtime` batch](/docs/guides/run-jobs-batch) configuration.
+- Required: No
+- Default value: `None`
+- Valid input types: `dict` or `None`
+
+- When omitted or `None`, Orbit submits all prepared PUBs as one Quantum Compute primitive job.
+- 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.
+
+</Attribute>
+
+<LeftColoredBar color="blue">
+    `max_pubs_per_job`
+        <Attribute attributeTypeHint="int">
+
+        Maximum number of consecutive PUBs submitted in each child job.
+        - Required: Yes when `batch` is supplied
+        - Valid input types: `int`
+        - Choices: Integer > 0
+
+        For `N` input PUBs, Orbit creates `ceil(N / max_pubs_per_job)` child jobs. The last child job can contain fewer PUBs.
+        </Attribute>
+
+    `max_time`
+        <Attribute attributeTypeHint="int or str or None" attributeValue="None">
+
+        Optional maximum lifetime of the `qiskit-ibm-runtime` batch.
+        - Required: No
+        - Default value: `None`
+        - Valid input types: `int`, `str`, or `None`
+
+        - A positive integer specifies seconds, such as `7200`.
+        - A duration string contains one or more positive number-and-unit pairs using `s`, `m`, `h`, or `d`, such as `"2h"` or `"1h30m"`.
+        - A numeric string such as `"7200"` is invalid; use the integer `7200` instead.
+        </Attribute>
+</LeftColoredBar>
+
+For example, the following call partitions `ordered_pubs` into child jobs of at most 300 PUBs, all within one batch:
+
+```python
+job = orbit.run(
+    primitive="sampler",
+    pubs=ordered_pubs,
+    backend_name="ibm_brisbane",
+    options={
+        "batch": {
+            "max_pubs_per_job": 300,
+            "max_time": "2h",
+        }
+    },
+)
+
+result = job.result()
+batch_report = result.metadata["quantum_elements_orbit"]["batch"]
+```
+
 ##### `simulator`
 
 <Attribute attributeTypeHint="bool" attributeValue="False">
@@ -540,7 +605,7 @@ Duration of one DD gate or pulse.
 
 ## 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.
 
 <Attribute attributeTypeHint="PrimitiveResult">
 Standard `PrimitiveResult` with Orbit metadata attached.
@@ -578,6 +643,16 @@ Standard `PrimitiveResult` with Orbit metadata attached.
                 Simulator noise mode: `"backend"` or `"ideal"`.
                 </Attribute>
 
+            `executionMode`
+                <Attribute attributeTypeHint="str">
+                Present with value `"batch"` when Orbit used server-side `qiskit-ibm-runtime` batch execution.
+                </Attribute>
+
+            `batch`
+                <Attribute attributeTypeHint="dict[str, Any]">
+                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`.
+                </Attribute>
+
             `primitive`
                 <Attribute attributeTypeHint="str">
                 Selected primitive: `"sampler"` or `"estimator"`.
@@ -625,7 +700,7 @@ Standard `PrimitiveResult` with Orbit metadata attached.
 
             `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.
                 </Attribute>
 
             `warnings`
@@ -647,6 +722,32 @@ Standard `PrimitiveResult` with Orbit metadata attached.
         </Attribute>
 </LeftColoredBar>
 
+### Batch output
+
+For a batch run, `result.metadata["quantum_elements_orbit"]["batch"]` maps each returned PUB range to the child job that executed it:
+
+```python
+result = job.result()
+orbit_report = result.metadata["quantum_elements_orbit"]
+batch_report = orbit_report["batch"]
+
+print(orbit_report["executionMode"])  # "batch"
+print(batch_report["id"])
+print(batch_report["jobIds"])
+
+for partition in batch_report["partitions"]:
+    start = partition["pubStart"]
+    stop = start + partition["pubCount"]
+    child_results = list(result)[start:stop]
+    print(partition["index"], partition["jobId"], start, stop)
+```
+
+`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.
+
+When `save_backend_info=True`, Orbit attempts one backend-calibration snapshot per child job and reports the collection in top-level `backendInfo.snapshots`. If MEM is enabled for Sampler PUBs, Orbit uses each child job's calibration snapshot for the PUBs in that partition before re-merging the results.
+
+The `RUNNING: EXECUTING_QPU` resource-usage entry reports the sum of the available child-job QPU times. Child jobs without provider QPU-time data can make that measurement partial.
+
 ### Per-PUB Orbit metadata
 
 Each `PubResult.metadata["quantum_elements_orbit"]` contains the insertion report for that PUB.
@@ -764,19 +865,21 @@ If mitigation fails, Orbit preserves the raw result and records the failure stat
 
 ## Error handling
 
-Orbit raises structured `qiskit_serverless.ServerlessError` errors for fatal failures. Each error includes a `code`, `message`, and `details` payload. Orbit maps errors to existing IBM Quantum error-code categories when possible; validation errors use code `1221`. Orbit-specific errors use the QE reserved code range `4700` through `4709` when no existing IBM Quantum code is a better match. See the [IBM Quantum error code reference](/docs/errors) for general error-code guidance.
+Orbit raises structured `qiskit_serverless.ServerlessError` errors for fatal failures. Each error includes a `code`, `message`, and `details` payload. Orbit maps errors to existing IBM Quantum error-code categories when possible; validation errors use code `1221`. Orbit-specific errors use the QE reserved code range `4700` through `4709` only when no existing IBM Quantum code is a better match. See the [IBM Quantum error code reference](/docs/errors) for general error-code guidance.
 
 <Admonition type="caution" title="Common fatal errors">
   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`.
   - Unsupported primitive errors use code `1211`. Orbit accepts only `primitive="sampler"` and `primitive="estimator"`.
   - Backend selection or backend capability errors use code `1007` or `1009`. These include unavailable backend names, no eligible least-busy backend, or a backend without the timing information required for DD insertion.
-  - DD insertion 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`.
-  - Unexpected Orbit-specific failures are reported as structured errors in the QE reserved range (`4700--4709`) when no existing IBM Quantum error code applies.
+  - 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 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`.
+  - QE codes `4703` through `4709` are reserved for future Orbit-specific categories and are not currently assigned.
 </Admonition>
 
 Non-fatal conditions are reported as warnings instead of failing the job when Orbit can safely preserve the result. Run-level warnings appear in `metadata["quantum_elements_orbit"]["warnings"]`; PUB-level warnings appear in each PUB report. Recoverable warning events use code `1300` when the Qiskit Functions environment accepts warning events. Examples include `preview=True` taking precedence over `simulator=True`, `qiskit-ibm-runtime` DD being enabled alongside Orbit DD, Sampler ignoring `runtime_options.resilience_level`, or backend calibration export failing while the primitive result is otherwise available.
 
-Measurement error mitigation failures are also non-fatal. If M3 mitigation cannot be applied, Orbit preserves the raw Sampler result and records `measurementErrorMitigation.status="failed"` with an error message in Orbit metadata.
+Measurement error mitigation failures are also non-fatal. If M3 mitigation cannot be applied, Orbit preserves the raw Sampler result and records `measurementErrorMitigation.status="failed"` with an error message in Orbit metadata.