Quantum Elements Orbit API reference

Type: Iterable[SamplerPubLike] or Iterable[EstimatorPubLike]

One or more PUBs matching the selected primitive.

• Required: Yes
• Valid input types: Iterable of Sampler PUB-like objects or iterable of Estimator PUB-like objects

Each PUB must match the selected primitive's input contract.

• For primitive="sampler": each PUB follows the Sampler PUB shape, such as (circuit, parameter_values, shots).
• For primitive="estimator": each PUB follows the Estimator PUB shape, such as (circuit, observables, parameter_values, precision).
• Circuits do not need to be ISA circuits in the default options.transpilation_mode="optimize" path; Orbit transpiles and schedules them internally.

Type: str

Selects which Qiskit Runtime primitive Orbit uses for execution.

• Required: Yes
• Valid input types: str

The primitive determines what each PUB must contain and what result data each PubResult returns.

• Choices: "sampler" / "estimator"
• Use "sampler" for sampled bitstring data.
• Use "estimator" for expectation values and standard errors.

Type: str or None

Default value: None

Name of the IBM Quantum backend to run on.

• Required: No

• Default value: None

• Valid input types: str or None

• When omitted or None, Orbit resolves an eligible operational non-simulator backend with least_busy().

• Example: "ibm_boston"

Type: dict or None

Default value: None

Function-specific options controlling Orbit execution behavior.

• Required: No
• Default value: None
• Valid input types: dict or None

Options control transpilation, DD insertion, Qiskit Runtime options, 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:

{
    "pub_options": [
        {"mode": "raw"},
        {"mode": "orbit"},
        {
            "mode": "custom",
            "dd_strategy": [[{"dd_sequence": "CPMG", "pulse_density": 1.00, "dd_reps": 1}]],
            "transpilation_mode": "optimize",
            "mem": True
        }
    ]
}

Type: bool

Default value: False

Whether Orbit returns a DD insertion report without submitting a Qiskit Runtime job.

• Required: No

• Default value: False

• Valid input types: bool

• When True, no QPU time is used; orbit simply pre-processes the circuits in pubs and provides an insertion report.

• When False (default value), a Qiskit Runtime job with Orbit-modified circuits is submitted and processed.

• If both preview and simulator are True, preview mode takes precedence and simulator execution is ignored.

Type: bool

Default value: False

Whether preview mode includes the prepared post-Orbit circuit for each PUB in metadata.

• Required: No

• Default value: False

• Valid input types: bool

• Used only when preview=True.

• When True, each PUB report includes debugCircuit.circuit, debugCircuit.usedQubits, and operation counts. It also includes best-effort debugCircuit.qasm when Qiskit can export the circuit.

• Leave this disabled for normal runs because circuit payloads can be large.

Type: string

Default value: optimize

How Orbit prepares PUB circuits before DD insertion.

• Required: No

• Default value: "optimize"

• Valid input values: "optimize", "prepare", or "validate"

• "optimize" runs repeated Qiskit optimization_level=2 transpilation and keeps the candidate with the lowest two-qubit depth for static and dynamic circuits.

• "prepare" runs Qiskit optimization_level=0 preparation and ALAP scheduling. If physical_layout is supplied, Orbit first materializes the circuit onto those physical wire indices and uses Qiskit's trivial layout method.

• "validate" treats the input circuit as already physically prepared. Orbit validates backend compatibility where practical, does not remap, route, optimize, or schedule-repair before DD insertion, and ignores physical_layout with a warning.

Type: object or null

Default value: None

Optional logical-to-physical qubit mapping.

• Required: No
• Default value: None
• Valid input types: object with non-negative integer keys and values, or None

Example: {"0": 85, "1": 89} maps logical qubit 0 to physical qubit 85 and logical qubit 1 to physical qubit 89. Python callers may use integer keys; JSON object keys are strings.

• In "optimize" mode, this is passed as an initial layout seed and the final mapping may change during optimization/routing.
• In "prepare" mode, Orbit materializes the circuit onto these physical wire indices, then uses level-0 preparation with layout_method="trivial". Explicit routing SWAPs can still move quantum state during execution.
• In "validate" mode, the supplied circuit wires are authoritative, so physical_layout is ignored with a warning.

Type: int

Default value: 300

Number of stochastic transpilation seeds Orbit tries in transpilation_mode="optimize".

• Required: No
• Default value: 300
• Valid input types: positive integer

Type: bool or None

Default value: None

Whether Orbit applies Sampler-only measurement error mitigation using M3.

• Required: No

• Default value: None

• Valid input types: bool or None

• When True, applies measurement error mitigation to shots from sampler.

• When False, does not post-process shots.

• When None, Orbit mode enables MEM for executed Sampler PUBs and raw/custom modes skip MEM unless configured.

• Explicit True requires primitive="sampler", preview=False, and simulator=False.

• Raw Sampler counts are preserved and mitigated counts are attached to Orbit metadata.

• If mitigation fails during post-processing, Orbit preserves the raw result and records the mitigation failure in metadata.

Type: list[dict] or None

Default value: None

Per-PUB execution modes and overrides.

• Required: No

• Default value: None

• Valid input types: list[dict] or None

• One entry is broadcast to all PUBs; otherwise pass one entry per PUB.

• {"mode": "raw"} uses a single Qiskit optimization_level=0 transpilation and scheduling pass for static or dynamic circuits, and skips Orbit optimization, Orbit DD, dynamic DD, and MEM.

• {"mode": "orbit"} uses Orbit defaults.

• {"mode": "custom"} can override transpilation_mode, physical_layout, dd_qubits, dd_strategy, dynamic_dd_seq, and mem for that PUB.

• Raw mode always uses transpilation_mode="prepare" with physical_layout=None, skips Orbit DD, and ignores global preparation options.

• Orbit and custom PUBs inherit global transpilation_mode and physical_layout unless they override them per PUB.

• Use duplicated PUBs with pub_options to compare raw, Orbit defaults, and a custom DD strategy in one Qiskit Runtime job. For a naive CPMG baseline, use {"dd_sequence": "CPMG", "pulse_density": 1.00, "dd_reps": 1} inside the custom PUB's dd_strategy.

For caller-prepared circuits, use transpilation_mode="validate" for the Orbit-enabled PUBs:

options = {
    "pub_options": [
        {"mode": "raw"},
        {"mode": "orbit", "transpilation_mode": "validate"},
        {
            "mode": "custom",
            "transpilation_mode": "validate",
            "dd_qubits": None,
            "dd_strategy": [[{"dd_sequence": "CPMG", "pulse_density": 1.00, "dd_reps": 1}]],
            "mem": False,
        },
    ]
}

Type: list[list[dict]]

Ordered DD strategies to apply to PUB circuits.

• Required: No

• Default value: [[{"dd_sequence": "auto", "pulse_density": 0.25, "dd_reps": 1}]]

• Valid input types: list[list[dict]]

• Choices: Non-empty outer list of non-empty strategy lists.

• The outer list indexes PUBs or circuits. If only one strategy is supplied, Orbit broadcasts it to all PUBs.

• Each inner list is applied round by round to the same circuit.

• Each round requires dd_sequence; pulse_density defaults to 0.25; dd_reps defaults to 1.

Type: str or dict or list or None

Default value: XY8

DD sequence used for Orbit's dynamic-circuit feedforward DD insertion.

• Required: No

• Default value: "XY8"

• Valid input types: str, dict, custom pulse-group list, or None

• Choices: Same sequence forms as dd_strategy[].dd_sequence, or None to disable the dynamic feedforward insertion stage.

• Applies when Orbit detects conditional logic or control flow and uses the dynamic-circuit DD pipeline.

• The normal dd_strategy pass runs first, then Orbit applies this sequence across labelled dynamic feedforward regions.

Type: list[int] or None

Default value: None

Global default allowlist of qubit indices eligible for Orbit DD insertion.

• Required: No

• Default value: None

• Valid input types: list[int] or None

• Choices: None or a list of integers >= 0

• None targets active/touched qubits only.

• A list can include idle-only qubits and excludes qubits not listed.

• pub_options[i].dd_qubits can override this value inside orbit or custom PUB entries.

• Explicit allowlists may only be supplied for Orbit-enabled PUBs whose resolved transpilation_mode is "validate", so the caller owns the physical qubit indices. Raw PUBs skip Orbit DD and do not accept dd_qubits.

Type: bool

Default value: False

Whether Orbit saves backend calibration properties after an executed Qiskit Runtime job.

• Required: No

• Default value: False

• Valid input types: bool

• 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.

• Failures are reported as warnings and do not discard otherwise successful primitive results.

Type: int

Default value: 4096

Default shots used for Sampler PUBs that do not specify shots explicitly.

• Required: No

• Default value: 4096

• Valid input types: int

• Choices: Integer > 0

• Applies only to primitive="sampler".

Type: float

Default value: 0.015625

Default target precision used for Estimator PUBs that do not specify precision explicitly.

• Required: No

• Default value: 0.015625

• Valid input types: float or int

• Choices: Float > 0

• Applies only to primitive="estimator".

Type: dict

Qiskit Runtime primitive options passed through to the underlying SamplerV2 or EstimatorV2 primitive.

• Required: No

• Default value: {"resilience_level": 0, "dynamical_decoupling": {"enable": false}}

• Valid input types: dict

• Nested option dictionaries are accepted, including advanced and experimental Qiskit Runtime options for the selected primitive.

• Runtime dynamical decoupling is disabled by default so Orbit's DD insertion is the only DD pass unless the user opts in.

For example, advanced Sampler users can enable dynamic-circuit debugging fields:

options = {
    "runtime_options": {
        "experimental": {
            "execution": {
                "scheduler_timing": True,
                "stretch_values": True,
            }
        }
    }
}

• Warning: One should thus alter this value with care, turning on specific approaches like twirling on manually while continuing to exclude DD.

Type: int or None

Default value: None

Soft cap on the Qiskit Runtime 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.

Type: bool

Default value: False

Whether Orbit executes the workload on a local Aer simulator instead of a real QPU.

• Required: No
• Default value: False
• Valid input types: bool

The simulator runs inside the function container.

• Choices: True / False
• Ignored when preview is True.
• A normal PrimitiveResult is returned with Orbit metadata attached.

Type: str

Default value: backend

Noise model used when simulator is True.

• Required: No

• Default value: "backend"

• Valid input types: str

• Choices: "backend" / "ideal"

• "backend" uses AerSimulator.from_backend(backend) when possible.

• "ideal" uses a plain noise-free AerSimulator.

Type: int or None

Default value: None

Duration of one DD gate or pulse.

• Required: No

• Default value: None

• Valid input types: int or None

• Warning: Use an explicit value only for controlled tests or when you have a calibrated backend-specific reason.

• The value uses the same units the backend uses for delays, typically dt.

• Choices: None or integer > 0

• When None, Orbit resolves a backend-aware value from backend.target using the longer calibrated X or sqrt(X) gate duration.

Type: PrimitiveResult

Standard Qiskit primitive result with Orbit metadata attached.

• For primitive="sampler", each PubResult.data contains Sampler result data such as classical-register bit arrays.
• For primitive="estimator", each PubResult.data contains Estimator result data such as expectation values and standard errors.
• In preview mode, each PubResult.data is empty because no Qiskit Runtime primitive is submitted.