qiskit-ibm-runtime

Output arrays follow the pattern: [Extrinsic Shape] + [Intrinsic Shape].

• Extrinsic shape: Matches the broadcasted shape of all inputs.
• Intrinsic shape: Determined by the output type.

Common Output Intrinsic Shapes:

Example Calculation: If inputs broadcast to an extrinsic shape of (4, 3), and you have a circuit with 1024 shots and a 3-bit classical register:

• Extrinsic: (4, 3)
• Intrinsic: (1024, 3)
• Full Output Shape: (4, 3, 1024, 3)

To access a specific configuration in the result, index into the extrinsic dimensions: result[0]["meas"][config_idx_0, config_idx_1, :, :].

# Input extrinsic shapes: (4, 1) and (3,) $\rightarrow$ (4, 3)
# Output for classical register "meas":
#   extrinsic: (4, 3)
#   intrinsic: (1024, 3)  - shots $\times$ bits
#   full shape: (4, 3, 1024, 3)

result = executor.run(program).result()
meas_data = result[0]["meas"]
print(meas_data.shape)  # (4, 3, 1024, 3)

# Access a specific configuration (e.g., index 2, 1)
config_2_1 = meas_data[2, 1, :, :]  # shape (1024, 3)

When using a samplex, the executor can perform multiple independent randomizations (e.g., for twirling) for the same circuit configuration. This is controlled by the shape parameter in program.append().

• Default behavior: If shape is omitted or matches the input extrinsic shape, you get one execution per configuration. While randomized, you do not benefit from averaging over multiple randomizations.
• Multiple randomizations: To run multiple randomizations per configuration, extend the shape with additional axes. These extra axes represent independent random realizations.
• Multi-dimensional grids: You can organize randomizations into a multi-dimensional grid (e.g., shape=(2, 14, 10)) to facilitate structured analysis or statistical grouping.

# 20 randomizations for each of 10 parameter configurations
program.append(
    template,
    samplex=samplex,
    samplex_arguments={
        "parameter_values": np.random.rand(10, 3),  # extrinsic (10,)
    },
    shape=(20, 10),  # 20 randomizations × 10 configurations
)
# Output shape for "meas": (20, 10, num_shots, creg_size)

Broadcasting is the mechanism used to combine input arrays of different shapes to define a grid of experimental configurations. The executor follows NumPy-style broadcasting rules.

The Core Rule: Two shapes are compatible if, when aligned from the right, each pair of dimensions is either equal or one of them is 1. A dimension of size 1 is "stretched" to match the other.

Broadcasting Examples:

• Shape (5,) and (5,) $\rightarrow$ (5,) (element-wise pairing)
• Shape (3, 1) and (4,) $\rightarrow$ (3, 4) (3x4 grid of combinations)
• Shape (2, 1, 5) and (3, 1) $\rightarrow$ (2, 3, 5) (all combinations across dimensions)
• Shape (3,) and (4,) $\rightarrow$ Error (incompatible shapes)

Broadcasting only applies to extrinsic axes (the leftmost dimensions representing your sweep). The intrinsic axes (the rightmost dimensions determined by the data type) are always preserved.

The public API consists of all packages, modules, classes, functions, methods, and attributes that are publicly documented in the hosted API documentation.

Key Rules for Users:

• Documentation is required: Simply having a docstring in the source code is not enough; the object must be rendered in the official API documentation to be considered public.
• Import from high-level packages: You should always import objects from the highest-level package that exports them. For example, even if an object is physically located in qiskit_ibm_runtime.json, if it is documented as being in qiskit_ibm_runtime, you should use the latter import path.
• Experimental features: Some components may be marked as experimental. These are part of the public interface but are not subject to the stability guarantees of semantic versioning and may change without notice.

A Session is used when you need to call a primitive (like Estimator) iteratively without incurring queuing delays for every single job. A session starts when the first job within it is submitted, and subsequent jobs within that same session are prioritized by the scheduler.

Best Practices:

• Use sessions only when necessary for iterative algorithms (e.g., optimization loops).
• Avoid running excessive classical code between iterative calls within a session, as this can lock the QPU and consume expensive QPU time.
• While Sampler can be used in a session, Estimator is the primary use case.

To use a session, wrap your primitive execution within a with Session(backend=backend): context manager and pass the session object to the primitive's mode parameter.

from qiskit_ibm_runtime import QiskitRuntimeService, Session, EstimatorV2 as Estimator

service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

with Session(backend=backend) as session:
    estimator = Estimator(mode=session)
    # Run iterative jobs here
    job = estimator.run([(isa_circuit, isa_observables, params)])
    print(f"Session ID: {session.session_id}")

Instances are virtual servers that manage your workload execution (quantum programs and classical compute tasks like error mitigation). They are identified by a Cloud Resource Name (CRN).

When you specify an instance, only backends and jobs belonging to that instance are available. If no instance is specified, the service searches across all instances in your account.

Instance Selection Logic (if not specified):

1. If you have only one instance, it is selected by default.
2. If multiple instances exist, the one that has access to the requested backend is selected.
3. Otherwise, the first instance with access to the backend is selected.

You can also influence selection using region and plans_preference parameters.

from qiskit_ibm_runtime import QiskitRuntimeService

# List all accessible instances
service = QiskitRuntimeService(channel='ibm_quantum_platform')
print(service.instances())

# Specify instance at service level (sets default for the service)
service = QiskitRuntimeService(channel='ibm_quantum_platform', instance="IBM_CLOUD_INSTANCE_1")
backend1 = service.backend("ibmq_manila")

# Specify instance at backend level (overwrites service-level specification)
backend2 = service.backend("ibmq_manila", instance="IBM_CLOUD_INSTANCE_2")