Executor broadcasting semantics

The data provided to the Executor primitive can be arranged in a variety of shapes to provide flexibility in a workload through broadcasting. This guide explains how the Executor handles array inputs and outputs using broadcasting semantics. Understanding these concepts will help you efficiently sweep over parameter values, combine multiple experimental configurations, and interpret the shape of returned data.

Quick start example

This example demonstrates the core idea. It creates a parametric circuit and and five different parameter configurations. The executor automatically runs all five configurations and returns data organized by configuration, with one result per classical register in each quantum program item.

The rest of this guide explains how this works in detail and how to build more complex sweeps, including samplomatic-based randomization and inputs.

import numpy as np
from qiskit.circuit import Parameter, QuantumCircuit
from qiskit_ibm_runtime.quantum_program import QuantumProgram
 
# A circuit with 3 parameters
circuit = QuantumCircuit(3)
circuit.rx(Parameter("a"), 0)
circuit.rx(Parameter("b"), 1)
circuit.rx(Parameter("c"), 2)
circuit.measure_all()
 
# 5 different parameter configurations (shape: 5 configurations × 3 parameters)
parameter_values = np.linspace(0, np.pi, 15).reshape(5, 3)
 
program = QuantumProgram(shots=1024)
program.append(circuit, circuit_arguments=parameter_values)
 
# Run and get results
result = executor.run(program).result()
 
# result is a list with one entry per program item
# result[0] is a dict mapping classical register names to data arrays
# Output bool arrays have shape (5, 1024, 3)
#   5 = number of parameter configurations
#   1024 = number of shots
#   3 = bits in the classical register
result[0]["meas"]

Intrinsic and extrinsic axes

Broadcasting only applies to extrinsic axes. The intrinsic axes are always preserved as specified.

• Intrinsic axes (rightmost): Determined by the data type. For example, if your circuit has three parameters, then parameter values require three numbers, giving an intrinsic shape of (3,).

• Extrinsic axes (leftmost): Your sweep dimensions. These define how many configurations you want to run.

Example

Consider a circuit with two parameters that you want to sweep over a 4x3 grid of configurations, varying both parameter values and a noise scale factor:

import numpy as np
 
# Parameter values: 4 configurations along axis 0, intrinsic shape (2,)
# Full shape: (4, 1, 2) - the "1" allows broadcasting with noise_scale
parameter_values = np.array([
    [[0.1, 0.2]],
    [[0.3, 0.4]],
    [[0.5, 0.6]],
    [[0.7, 0.8]],
])  # shape (4, 1, 2)
 
# Noise scale: 3 configurations, intrinsic shape () (scalar)
# Full shape: (3,)
noise_scale = np.array([0.8, 1.0, 1.2])  # shape (3,)
 
# Extrinsic shapes: (4, 1) and (3,) → broadcast to (4, 3)
# Result: 12 total configurations in a 4×3 grid
 
program.append(
    template,
    samplex=samplex,
    samplex_arguments={
        "parameter_values": parameter_values,
        "noise_scale.mod_ref1": noise_scale,
    },
)

The shapes are as follows:

Output array shapes

Output arrays follow the same extrinsic/intrinsic pattern:

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

The most common output is bitstring data from measurements, which is formatted as an array of boolean values:

Example

If you provide inputs with extrinsic shapes (4, 1) and (3,), the broadcast extrinsic shape is (4, 3). For a circuit with 1024 shots and a 3-bit classical register:

# Input extrinsic shapes: (4, 1) and (3,) → (4, 3)
# Output for classical register "meas":
#   extrinsic: (4, 3)
#   intrinsic: (1024, 3)  - shots × bits
#   full shape: (4, 3, 1024, 3)
 
result = executor.run(program).result()
meas_data = result[0]["meas"]  # result[0] for first program item
print(meas_data.shape)  # (4, 3, 1024, 3)
 
# Access a specific configuration
config_2_1 = meas_data[2, 1, :, :]  # shape (1024, 3)

Randomization and the shape parameter

When using a samplex, each element of the extrinsic shape corresponds to an independent circuit execution. The samplex typically injects randomness (for example, twirling gates) into each execution, so even without explicitly requesting multiple randomizations, each element naturally receives its own random realization.

You can use the shape parameter to augment the extrinsic shape for the item, effectively adding axes that correspond specifically to randomizing the same configuration many times. It must be broadcastable from the shape implicit in your samplex_arguments. Axes where shape exceeds the implicit shape enumerate additional independent randomizations.

No explicit randomization axes

If you omit shape (or set it to match your input shapes), you get one execution per input configuration. Each execution is still randomized by the samplex, but with only a single random realization you don't benefit from averaging over multiple randomizations.

The following example demonstrates the default behavior:

program.append(
    template,
    samplex=samplex,
    samplex_arguments={
        "parameter_values": np.random.rand(10, 3),  # extrinsic (10,)
    },
    # shape defaults to (10,) - one randomized execution per config
)
# Output shape for "meas": (10, num_shots, creg_size)

Single randomization axis

To run multiple randomizations per configuration, extend the shape with additional axes. For example, the following code runs 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)

Multiple randomization axes

You can organize randomizations into a multi-dimensional grid. This is useful for structured analysis, for example, separating randomizations by type or grouping them for statistical processing.

Here, the input extrinsic shape (10,) broadcasts to the requested shape (2, 14, 10), with axes 0 and 1 filled by independent randomizations.

program.append(
    template,
    samplex=samplex,
    samplex_arguments={
        "parameter_values": np.random.rand(10, 3),  # extrinsic (10,)
    },
    shape=(2, 14, 10),  # 2×14=28 randomizations per configuration, 10 configurations
)
# Output shape for "meas": (2, 14, 10, num_shots, creg_size)

How shape and input shapes interact

The shape parameter must be broadcastable from your input extrinsic shapes. This means:

• Input shapes with size-1 dimensions can expand to match shape.
• Input shapes must align from the right with shape.
• Axes in shape that exceed the input dimensions enumerate randomizations.

Note that shape can contain size-1 dimensions that expand to match input dimensions, as is illustrated in the last row of the following table.

Examples:

Indexing into results

With randomization axes, you can index into specific randomization/parameter combinations:

# Using shape=(2, 14, 10) with input extrinsic shape (10,)
result = executor.run(program).result()
meas_data = result[0]["meas"]  # shape (2, 14, 10, 1024, 3)
 
# Get all shots for randomization (0, 7) and parameter config 3
specific = meas_data[0, 7, 3, :, :]  # shape (1024, 3)
 
# Average over all randomizations for parameter config 5 on bit 2
averaged = meas_data[:, :, 5, :, 2].mean(axis=(0, 1))

Common patterns

Sweep a single parameter

To sweep one parameter while holding others fixed:

 
    # Circuit has 3 parameters, sweep first one over 20 values
    sweep_values = np.linspace(0, 2*np.pi, 20)
    fixed_values = [0.5, 0.3]
 
    parameter_values = np.column_stack([
        sweep_values,
        np.full(20, fixed_values[0]),
        np.full(20, fixed_values[1]),
    ])  # shape (20, 3)

Next steps