Saltar al contenido principal

Entradas y salidas del Sampler

Versiones de paquetes

El código de esta página fue desarrollado con los siguientes requisitos. Recomendamos usar estas versiones o versiones más recientes.

qiskit[all]~=2.4.0
qiskit-ibm-runtime~=0.46.1

Esta página ofrece una descripción general de las entradas y salidas de la primitiva Qiskit Runtime Sampler, que ejecuta cargas de trabajo en los recursos de cómputo de IBM Quantum®. Sampler te permite definir eficientemente cargas de trabajo vectorizadas usando una estructura de datos conocida como Primitive Unified Bloc (PUB). Se usan como entradas para el método run() de la primitiva Sampler, que ejecuta la carga de trabajo definida como un job. Luego, una vez completado el job, los resultados se devuelven en un formato que depende tanto de los PUBs utilizados como de las opciones de runtime especificadas desde la primitiva.

Entradas​

Cada PUB tiene el formato:

(<circuito único>, <uno o más valores de parámetros opcionales>, <shots opcionales>),

Puede haber múltiples elementos parameter values, y cada elemento puede ser un array o un único parámetro, dependiendo del circuito elegido. Además, la entrada debe contener mediciones.

Para la primitiva Sampler, un PUB puede contener como máximo tres valores:

  • Un único QuantumCircuit, que puede contener uno o más objetos Parameter Nota: Estos circuitos también deben incluir instrucciones de medición para cada uno de los qubits que se van a muestrear.
  • Una colección de valores de parámetros para vincular el circuito contra θk\theta_k (solo es necesario si se utilizan objetos Parameter que deben vincularse en tiempo de ejecución)
  • (Opcionalmente) un número de shots para medir el circuito

El siguiente código demuestra un ejemplo de un conjunto de entradas vectorizadas para la primitiva Sampler y las ejecuta en un backend de IBM® como un único objeto RuntimeJobV2.

# Added by doQumentation — required packages for this notebook
!pip install -q numpy qiskit qiskit-ibm-runtime
from qiskit.circuit import (
    Parameter,
    QuantumCircuit,
    ClassicalRegister,
    QuantumRegister,
)
from qiskit.transpiler import generate_preset_pass_manager
from qiskit.quantum_info import SparsePauliOp
from qiskit.primitives.containers import BitArray

from qiskit_ibm_runtime import (
    QiskitRuntimeService,
    SamplerV2 as Sampler,
)

import numpy as np

# Instantiate runtime service and get
# the least busy backend
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

# Define a circuit with two parameters.
circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
circuit.ry(Parameter("a"), 0)
circuit.rz(Parameter("b"), 0)
circuit.cx(0, 1)
circuit.h(0)
circuit.measure_all()

# Transpile the circuit
pm = generate_preset_pass_manager(optimization_level=1, backend=backend)
transpiled_circuit = pm.run(circuit)
layout = transpiled_circuit.layout

# Now define a sweep over parameter values, the last axis of dimension 2 is
# for the two parameters "a" and "b"
params = np.vstack(
    [
        np.linspace(-np.pi, np.pi, 100),
        np.linspace(-4 * np.pi, 4 * np.pi, 100),
    ]
).T

sampler_pub = (transpiled_circuit, params)

# Instantiate the new Sampler object, then run the transpiled circuit
# using the set of parameters and observables.
sampler = Sampler(mode=backend)
job = sampler.run([sampler_pub])
result = job.result()

Salidas​

Después de que uno o más PUBs se envíen a un QPU para su ejecución y un job se complete exitosamente, los datos se devuelven como un objeto contenedor PrimitiveResult al que se accede llamando al método RuntimeJobV2.result(). El PrimitiveResult contiene una lista iterable de objetos SamplerPubResult que contienen los resultados de ejecución para cada PUB. Estos datos son muestras de la salida del circuito.

Cada elemento de esta lista corresponde a un PUB enviado al método run() de la primitiva (por ejemplo, un job enviado con 20 PUBs devolverá un objeto PrimitiveResult que contiene una lista de 20 objetos SamplerPubResult, uno correspondiente a cada PUB).

Cada objeto SamplerPubResult posee tanto un atributo data como un atributo metadata.

  • El atributo data es un DataBin personalizado que contiene los valores de medición reales, las desviaciones estándar, etc. Los data bins son objetos similares a diccionarios que contienen un BitArray por cada ClassicalRegister en el circuito.
  • La clase BitArray es un contenedor para datos de shots ordenados. Almacena los bitstrings muestreados como bytes dentro de un array bidimensional. El eje más a la izquierda de este array recorre los shots ordenados, mientras que el eje más a la derecha recorre los bytes.
  • El atributo metadata contiene información sobre las opciones de runtime utilizadas (explicado más adelante en la sección Metadatos del resultado de esta página).

El siguiente es un esquema visual de la estructura de datos PrimitiveResult:

    └── PrimitiveResult
        ├── SamplerPubResult[0]
        │   ├── metadata
        │   └── data  ## In the form of a DataBin object
        │       ├── NAME_OF_CLASSICAL_REGISTER
        │       │   └── BitArray of count data (default is 'meas')
        |       |
        │       └── NAME_OF_ANOTHER_CLASSICAL_REGISTER
        │           └── BitArray of count data (exists only if more than one
        |                 ClassicalRegister was specified in the circuit)
        ├── SamplerPubResult[1]
        |   ├── metadata
        |   └── data  ## In the form of a DataBin object
        |       └── NAME_OF_CLASSICAL_REGISTER
        |           └── BitArray of count data for second pub
        ├── ...
        ├── ...
        └── ...

En pocas palabras, un único job devuelve un objeto PrimitiveResult y contiene una lista de uno o más objetos SamplerPubResult. Estos objetos SamplerPubResult almacenan entonces los datos de medición para cada PUB que se envió al job.

Como primer ejemplo, veamos el siguiente circuito de diez qubits:

# generate a ten-qubit GHZ circuit
circuit = QuantumCircuit(10)
circuit.h(0)
circuit.cx(range(0, 9), range(1, 10))

# append measurements with the `measure_all` method
circuit.measure_all()

# transpile the circuit
transpiled_circuit = pm.run(circuit)

# run the Sampler job and retrieve the results
sampler = Sampler(mode=backend)
job = sampler.run([transpiled_circuit])
result = job.result()

# the data bin contains one BitArray
data = result[0].data
print(f"Databin: {data}\n")

# to access the BitArray, use the key "meas", which is the default name of
# the classical register when this is added by the `measure_all` method
array = data.meas
print(f"BitArray: {array}\n")
print(f"The shape of register `meas` is {data.meas.array.shape}.\n")
print(f"The bytes in register `alpha`, shot by shot:\n{data.meas.array}\n")
Databin: DataBin(meas=BitArray(<shape=(), num_shots=4096, num_bits=10>))

BitArray: BitArray(<shape=(), num_shots=4096, num_bits=10>)

The shape of register `meas` is (4096, 2).

The bytes in register `alpha`, shot by shot:
[[  0   0]
 [  3 255]
 [  0   0]
 ...
 [  3 255]
 [  2 255]
 [  3 255]]

A veces puede ser conveniente convertir el formato de bytes del BitArray a bitstrings. El método get_count devuelve un diccionario que mapea los bitstrings al número de veces que ocurrieron.

# optionally, convert away from the native BitArray format to a dictionary format
counts = data.meas.get_counts()
print(f"Counts: {counts}")
Counts: {'0000000000': 1649, '1111111111': 1344, '1111111000': 26, '1101111111': 40, '1111110000': 20, '0010000000': 32, '1000000000': 67, '1111110110': 4, '0000011110': 4, '0000000001': 78, '0010100000': 1, '1100000000': 37, '1111111110': 126, '1111110111': 35, '1111011111': 32, '0011111000': 1, '1011110111': 1, '0000011111': 48, '1111000000': 14, '0110000000': 1, '1110111110': 2, '1110011111': 4, '1111100000': 19, '1101111000': 1, '1111111011': 8, '0001011111': 3, '1110000000': 31, '0000000111': 25, '1110000001': 3, '0011111111': 24, '0000100000': 7, '1111111101': 30, '1111101111': 16, '0111111111': 37, '0000011101': 4, '0101111111': 4, '1011111110': 2, '0000000010': 17, '1011111111': 20, '0000100111': 1, '0010000111': 1, '1011010000': 1, '1101101111': 2, '1011110000': 1, '1000000001': 4, '0000001000': 23, '0011111110': 8, '1111111001': 1, '1100111111': 2, '0000011000': 2, '0001111110': 2, '0000111111': 20, '0001111111': 33, '1110111111': 11, '1010000000': 3, '0111011111': 2, '0000000100': 2, '0000000110': 2, '0000001111': 22, '0111101111': 1, '0000010111': 1, '0000000011': 15, '0001000010': 1, '1111111100': 19, '1111101000': 1, '0000001110': 2, '1011110100': 1, '0001000000': 11, '1001111111': 2, '0100000000': 6, '1100000011': 2, '1000001110': 1, '1100001111': 1, '0000010000': 3, '1101111110': 5, '0001111101': 1, '0001110111': 1, '0011000000': 2, '0111101110': 1, '1100000001': 1, '1111000001': 1, '0000000101': 1, '1101110111': 2, '0011111011': 1, '0000111110': 1, '1111101110': 3, '1111001000': 1, '1011111100': 1, '1111110101': 2, '1101001111': 1, '1111011110': 3, '1000011111': 1, '0000001001': 2, '1111010000': 1, '1110100010': 1, '1111110001': 2, '1101110000': 2, '0000010100': 1, '0111111110': 2, '0001000001': 1, '1000010000': 1, '1111011100': 1, '0111111100': 1, '1011101111': 1, '0000111101': 1, '1100011111': 2, '1101100000': 1, '1111011011': 1, '0010011111': 1, '0000110111': 3, '1111100010': 1, '1110111101': 1, '0000111001': 1, '1111100001': 1, '0001111100': 1, '1110011110': 1, '1100000010': 1, '0011110000': 1, '0001100111': 1, '1111010111': 1, '0010000001': 1, '0010000011': 1, '1101000111': 1, '1011111101': 1, '0000001100': 1}

Cuando un circuito contiene más de un registro clásico, los resultados se almacenan en diferentes objetos BitArray. El siguiente ejemplo modifica el fragmento anterior dividiendo el registro clásico en dos registros distintos:

# generate a ten-qubit GHZ circuit with two classical registers
circuit = QuantumCircuit(
    qreg := QuantumRegister(10),
    alpha := ClassicalRegister(1, "alpha"),
    beta := ClassicalRegister(9, "beta"),
)
circuit.h(0)
circuit.cx(range(0, 9), range(1, 10))

# append measurements with the `measure_all` method
circuit.measure([0], alpha)
circuit.measure(range(1, 10), beta)

# transpile the circuit
transpiled_circuit = pm.run(circuit)

# run the Sampler job and retrieve the results
sampler = Sampler(mode=backend)
job = sampler.run([transpiled_circuit])
result = job.result()

# the data bin contains two BitArrays, one per register, and can be accessed
# as attributes using the registers' names
data = result[0].data
print(f"BitArray for register 'alpha': {data.alpha}")
print(f"BitArray for register 'beta': {data.beta}")
BitArray for register 'alpha': BitArray(<shape=(), num_shots=4096, num_bits=1>)
BitArray for register 'beta': BitArray(<shape=(), num_shots=4096, num_bits=9>)

Usar objetos BitArray para post-procesamiento eficiente​

Dado que los arrays generalmente ofrecen mejor rendimiento en comparación con los diccionarios, es recomendable realizar cualquier post-procesamiento directamente sobre los objetos BitArray en lugar de sobre diccionarios de conteos. La clase BitArray ofrece una variedad de métodos para realizar algunas operaciones comunes de post-procesamiento:

print(f"The shape of register `alpha` is {data.alpha.array.shape}.")
print(f"The bytes in register `alpha`, shot by shot:\n{data.alpha.array}\n")

print(f"The shape of register `beta` is {data.beta.array.shape}.")
print(f"The bytes in register `beta`, shot by shot:\n{data.beta.array}\n")

# post-select the bitstrings of `beta` based on having sampled "1" in `alpha`
mask = data.alpha.array == "0b1"
ps_beta = data.beta[mask[:, 0]]
print(f"The shape of `beta` after post-selection is {ps_beta.array.shape}.")
print(f"The bytes in `beta` after post-selection:\n{ps_beta.array}")

# get a slice of `beta` to retrieve the first three bits
beta_sl_bits = data.beta.slice_bits([0, 1, 2])
print(
    f"The shape of `beta` after bit-wise slicing is {beta_sl_bits.array.shape}."
)
print(f"The bytes in `beta` after bit-wise slicing:\n{beta_sl_bits.array}\n")

# get a slice of `beta` to retrieve the bytes of the first five shots
beta_sl_shots = data.beta.slice_shots([0, 1, 2, 3, 4])
print(
    f"The shape of `beta` after shot-wise slicing is {beta_sl_shots.array.shape}."
)
print(
    f"The bytes in `beta` after shot-wise slicing:\n{beta_sl_shots.array}\n"
)

# calculate the expectation value of diagonal operators on `beta`
ops = [SparsePauliOp("ZZZZZZZZZ"), SparsePauliOp("IIIIIIIIZ")]
exp_vals = data.beta.expectation_values(ops)
for o, e in zip(ops, exp_vals):
    print(f"Exp. val. for observable `{o}` is: {e}")

# concatenate the bitstrings in `alpha` and `beta` to "merge" the results of the two
# registers
merged_results = BitArray.concatenate_bits([data.alpha, data.beta])
print(f"\nThe shape of the merged results is {merged_results.array.shape}.")
print(f"The bytes of the merged results:\n{merged_results.array}\n")
The shape of register `alpha` is (4096, 1).
The bytes in register `alpha`, shot by shot:
[[0]
 [0]
 [0]
 ...
 [0]
 [0]
 [0]]

The shape of register `beta` is (4096, 2).
The bytes in register `beta`, shot by shot:
[[  0   0]
 [  1 248]
 [  0   0]
 ...
 [  0   0]
 [  0   0]
 [  0   0]]

The shape of `beta` after post-selection is (0, 2).
The bytes in `beta` after post-selection:
[]
The shape of `beta` after bit-wise slicing is (4096, 1).
The bytes in `beta` after bit-wise slicing:
[[0]
 [0]
 [0]
 ...
 [0]
 [0]
 [0]]

The shape of `beta` after shot-wise slicing is (5, 2).
The bytes in `beta` after shot-wise slicing:
[[  0   0]
 [  1 248]
 [  0   0]
 [  0   0]
 [  0   0]]

Exp. val. for observable `SparsePauliOp(['ZZZZZZZZZ'],
              coeffs=[1.+0.j])` is: 0.07470703125
Exp. val. for observable `SparsePauliOp(['IIIIIIIIZ'],
              coeffs=[1.+0.j])` is: 0.0244140625

The shape of the merged results is (4096, 2).
The bytes of the merged results:
[[  0   0]
 [  3 240]
 [  0   0]
 ...
 [  0   0]
 [  0   0]
 [  0   0]]

Metadatos del resultado​

Además de los resultados de ejecución, tanto los objetos PrimitiveResult como SamplerPubResult contienen un atributo de metadatos sobre el job enviado. Los metadatos que contienen información para todos los PUBs enviados (como las diversas opciones de runtime disponibles) se pueden encontrar en PrimitiveResult.metatada, mientras que los metadatos específicos de cada PUB se encuentran en SamplerPubResult.metadata.

Los metadatos del resultado del Sampler también incluyen información de temporización de ejecución llamada el span de ejecución.

nota

En el campo de metadatos, las implementaciones primitivas pueden devolver cualquier información sobre la ejecución que sea relevante para ellas, y no hay pares clave-valor garantizados por la primitiva base. Por lo tanto, los metadatos devueltos pueden ser diferentes en diferentes implementaciones de primitivas.

# Print out the results metadata
print("The metadata of the PrimitiveResult is:")
for key, val in result.metadata.items():
    print(f"'{key}' : {val},")

print("\nThe metadata of the PubResult result is:")
for key, val in result[0].metadata.items():
    print(f"'{key}' : {val},")
The metadata of the PrimitiveResult is:
'execution' : {'execution_spans': ExecutionSpans([DoubleSliceSpan(<start='2026-05-13 14:23:00', stop='2026-05-13 14:23:02', size=4096>)])},
'version' : 2,

The metadata of the PubResult result is:
'circuit_metadata' : {},

Ver los spans de ejecución​

Los resultados de los jobs SamplerV2 ejecutados en Qiskit Runtime contienen información de temporización de ejecución en sus metadatos. Esta información de temporización puede usarse para establecer límites de marca de tiempo superior e inferior sobre cuándo se ejecutaron shots particulares en el QPU. Los shots se agrupan en objetos ExecutionSpan, cada uno de los cuales indica una hora de inicio, una hora de fin y una especificación de qué shots se recopilaron en el span.

Un span de ejecución especifica qué datos se ejecutaron durante su ventana proporcionando un método ExecutionSpan.mask. Este método, dado cualquier índice de Primitive Unified Block (PUB), devuelve una máscara booleana que es True para todos los shots ejecutados durante su ventana. Los PUBs están indexados por el orden en que se proporcionaron a la llamada run del Sampler. Si, por ejemplo, un PUB tiene forma (2, 3) y se ejecutó con cuatro shots, entonces la forma de la máscara es (2, 3, 4). Consulta la página API de execution_span para obtener todos los detalles.

Para ver la información de los spans de ejecución, revisa los metadatos del resultado devuelto por SamplerV2, que vienen en forma de objeto ExecutionSpans. Este objeto es un contenedor similar a una lista que contiene instancias de subclases de ExecutionSpan, como SliceSpan.

Ejemplo:

# Define two circuits, each with one parameter with two parameters.
circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
circuit.ry(Parameter("a"), 0)
circuit.cx(0, 1)
circuit.h(0)
circuit.measure_all()

pm = generate_preset_pass_manager(optimization_level=1, backend=backend)
transpiled_circuit = pm.run(circuit)

params = np.random.uniform(size=(2, 3)).T

sampler_pub = (transpiled_circuit, params)

# Instantiate the new Estimator object, then run the transpiled circuit
# using the set of parameters and observables.

job = sampler.run([sampler_pub], shots=4)

result = job.result()
spans = job.result().metadata["execution"]["execution_spans"]
print(spans)
ExecutionSpans([DoubleSliceSpan(<start='2026-05-13 14:23:20', stop='2026-05-13 14:23:21', size=24>)])
from qiskit.primitives import BitArray

# Get the mask of the 1st PUB for the 0th span.
mask = spans[0].mask(0)

# Decide whether the 0th shot of parameter set (1, 2) occurred in this span.
in_this_span = mask[2, 1, 0]

# Create a new bit array containing only the PUB-1 data collected during this span.
bits = result[0].data.meas
filtered_data = BitArray(bits.array[mask], bits.num_bits)

Los spans de ejecución pueden filtrarse para incluir información relacionada con PUBs específicos, seleccionados por sus índices:

# take the subset of spans that reference data in PUBs 0 or 2
spans.filter_by_pub([0, 2])
ExecutionSpans([DoubleSliceSpan(<start='2026-05-13 14:23:20', stop='2026-05-13 14:23:21', size=24>)])

Ver información global sobre la colección de spans de ejecución:

print("Number of execution spans:", len(spans))
print("  Start of the first span:", spans.start)
print("     End of the last span:", spans.stop)
print("       Total duration (s):", spans.duration)
Number of execution spans: 1
  Start of the first span: 2026-05-13 14:23:20.441518
     End of the last span: 2026-05-13 14:23:21.564845
       Total duration (s): 1.123327

Extraer e inspeccionar un span particular:

spans.sort()
print(" Start of first span:", spans[0].start)
print("   End of first span:", spans[0].stop)
print("#shots in first span:", spans[0].size)
Start of first span: 2026-05-13 14:23:20.441518
   End of first span: 2026-05-13 14:23:21.564845
#shots in first span: 24
nota

Es posible que las ventanas de tiempo especificadas por distintos spans de ejecución se superpongan. Esto no se debe a que un QPU estuviera realizando múltiples ejecuciones a la vez, sino que es un artefacto de cierto procesamiento clásico que puede ocurrir simultáneamente con la ejecución cuántica. La garantía que se hace es que los datos referenciados definitivamente ocurrieron en el span de ejecución reportado, pero no necesariamente que los límites de la ventana de tiempo son tan precisos como sea posible.

Fuente: IBM Quantum docs — actualizado el 13 may 2026
Versión en inglés en doQumentation — actualizado el 13 may 2026
Esta traducción se basa en la versión en inglés del 13 may 2026
¿Problema con el sitio o la traducción?¿Problema de contenido? Editar en IBM Quantum docs