Skip to main contentIBM Quantum Documentation Preview
This is a preview build of IBM Quantum® documentation. Refer to quantum.cloud.ibm.com/docs for the official documentation.

Sampler examples

Package versions

The code on this page was developed using the following requirements. We recommend using these versions or newer.

qiskit[all]~=2.3.0
qiskit-ibm-runtime~=0.43.1

Generate entire error-mitigated quasi-probability distributions sampled from quantum circuit outputs. Leverage Sampler’s capabilities for search and classification algorithms like Grover’s and QVSM.

Run a single experiment

Use Sampler to return the measurement outcome as bitstrings or counts of a single circuit.

import numpy as np
from qiskit.circuit.library import iqp
from qiskit.transpiler import generate_preset_pass_manager
from qiskit.quantum_info import random_hermitian
from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler

n_qubits = 127

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

mat = np.real(random_hermitian(n_qubits, seed=1234))
circuit = iqp(mat)
circuit.measure_all()

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

sampler = Sampler(backend)
job = sampler.run([isa_circuit])
result = job.result()

# Get results for the first (and only) PUB
pub_result = result[0]

print(f" > First ten results: {pub_result.data.meas.get_bitstrings()[:10]}")

Output:

 > First ten results: ['0101110000110001001111000101001111000110110100011000100101011101110011010010010101000110000111101010101000001010000100100000100', '0100010101111101010000100010011100110001010000011000000010001100010111000011001010000100100000100000000010000000010010101011110', '1101010111111111100010000011101010101010100100011001000000001001110010001000000010000010000101000111000100010010000001111000010', '1001110001100001001101111010111100000100010110010001001100111000110010111000001010001000000000000000100101101001110010101000110', '0001000000011011000011000111001000000000100110110011111110110100110000101010100010000010101011011000101011101000100000110000011', '1011100010011111010000001110110000111101000001110010011001100011111010001100100000110001000010001010110011100010000111000111010', '1101110000011000001011011000001111001110010111111111100100010001110100000010000001011000110000000011010011110100101001101000010', '0110100000110011000011001000110110110001000100100001111010001101000001010111000000101010101000001110100100001010110001000100101', '1000011010011011001111010010100000001110010010100000011010000110011010100000111000010010100111000001100101100010110010101001010', '1011011100111001010010101001000111000001110011110011001111010100100011101111011101011000000111011010000011100011010000001000000']

Run multiple experiments in a single job

Use Sampler to return the measurement outcome as bitstrings or counts of multiple circuits in one job.

import numpy as np
from qiskit.circuit.library import iqp
from qiskit.transpiler import generate_preset_pass_manager
from qiskit.quantum_info import random_hermitian
from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler

n_qubits = 127

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

rng = np.random.default_rng()
mats = [np.real(random_hermitian(n_qubits, seed=rng)) for _ in range(3)]
circuits = [iqp(mat) for mat in mats]
for circuit in circuits:
    circuit.measure_all()

pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuits = pm.run(circuits)

sampler = Sampler(mode=backend)
job = sampler.run(isa_circuits)
result = job.result()

for idx, pub_result in enumerate(result):
    print(
        f" > First five results for pub {idx}: {pub_result.data.meas.get_bitstrings()[:5]}"
    )

Output:

 > First ten results for pub 0: ['1000000101000100010111001010101010000001001010101011011001011110001000000110110101010000010000000000110001001000011111110000001', '1111101011011011110001011000001100001101100001000101111011101110000101111010001011111010001001000010111001110111000010001011010', '1100100101110010000110101011110010111001101010001101100010110100110110000110110010001110001000001010011100001000011011000111010', '1100010010000100100010110100011010011001010101101101101001100001001110011001011011111100011100100001000101010000111101110001101', '0011101011101100010011111001001110000101100110000110000001111000011010011110000110100000110011011000000010110001010000111000100', '0110101101110000010110100100010011000100100010000010010010110001111111110000101011000100010000000100100100110011010111101110111', '1101011000111100011000010110000010001100101011000001110010110001111101010101011110110010000100011101000001010110010101000000100', '0000101010010100000010111110111000001011000000001011000110100010110011111000110110010110011010111101001011000000001101001110110', '1100101000110001000011111110010001011000010110010101101000000101011110000100011011111011011010001001110011011101001101010100000', '0110011000101110101001010100110010101000010111100001000111011000110101011010010101110011001010101000001001001000110010100010101']
 > First ten results for pub 1: ['1100100001011010010100000110101010100111101100110000100001011000100010001101010101101110000011010010011000010000010001000001000', '1100000011000000100110011000000110010000011111000000001010000101000010011001000001010000001000001010001000110010111000010000000', '0010000111101000111010101010101001010000001110100001011011100011000111000000010101001000010101001100000010100010011000000000010', '0010100100001000011100001010011000001010000010001000000001011100001010001110010110111101101000001101010101000000000011000100110', '0101101000011110111000100010000000101110100001010101110010001100001100001000111111110101001010100110000000010011111111000000010', '0101010111000000001110100110100011010111000111110100010010010001011010001000101001100001100110001001001000010010000011100100000', '0110010000001110111010010100010010010011010010110101001110010010001001101010111000010000000100011001001000001111010001100010010', '1100001100101011011010000110111110001101010100010100101100111000010000101101101010111011111011101100000000110000100101001000101', '0000111100001000000101101001010111110100011011011101101111000000001010001001100010110000100000000001010100110001001100110010000', '0100100001001011110000110001100001111011111100000001010111011011100010110111101110101111101010100101000000110111000110000000000']
 > First ten results for pub 2: ['1000010100111010101010111110101000110101010001111110011110011001010100001100100000000001000111111011001101100001001110011101100', '1110100000111000000000110110010100000011110000011110000110100010000100001100010101101001100100010111000010100101011000001000000', '1000010111011000000001110111010101000111111010010011110100001010000000111111100100001111111101010100001001011100111101010000010', '0000111011110110010011100111001010001000011010010110010010101000101110011100000010000101011000101001001001000100111101010100100', '0100000100111101110000101111011000100111101011101110100001000001000010101111100100000111010001101001100001100011011110101101100', '0100001000110101010010010100100110000100001010100001110001110101010011000111100111001001100000010100110111010111010100010100100', '0011111000010001101100000110111001000000100111110100001100001100010010010101011000000111011011111010100010000100100000100000000', '1000010010101100110110110110100010100000111001101011110100001000011000001000000110010001001011100100000000100000000000000000000', '0001011100010011111110011110000001000000010100111111000000101010000011011110110000110001010010000010010001000101110001111100010', '1111010100011100010010010110000101110000010001100101011111001100010111100001011001000001011010111011100001000001100000000000110']

Run parameterized circuits

Run several experiments in a single job, leveraging parameter values to increase circuit reusability.

import numpy as np
from qiskit.circuit.library import real_amplitudes
from qiskit.transpiler import generate_preset_pass_manager
from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler

n_qubits = 127

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

# Step 1: Map classical inputs to a quantum problem
circuit = real_amplitudes(num_qubits=n_qubits, reps=2)
circuit.measure_all()

# Define three sets of parameters for the circuit
rng = np.random.default_rng(1234)
parameter_values = [
    rng.uniform(-np.pi, np.pi, size=circuit.num_parameters) for _ in range(3)
]

# Step 2: Optimize problem for quantum execution.

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

# Step 3: Execute using Qiskit primitives.
sampler = Sampler(backend)
job = sampler.run([(isa_circuit, parameter_values)])
result = job.result()
# Get results for the first (and only) PUB
pub_result = result[0]
# Get counts from the classical register "meas".
print(
    f" >> First five results for the meas output register: {pub_result.data.meas.get_bitstrings()[:5]}"
)

Output:

 >> First ten results for the meas output register: ['1100011011100001011000001001000001111110000001011100011110011100111110000111000100011100001111100010010111110001001111011000101', '1100011101010101010000100110110110010001100101011101001011101010111110000111110100000011111010101101011101101101001111011110011', '0000000011000011001101001000111110001100010010011011001111000101000000001111111101101011100111010110111101010111011001010001011', '0101010001101110100010001100111001011101101100001000100001011101110100001000011011001011110101000110010001001010011011100011101', '0110101110000010110000001000010101100010010001001001101000010100110001011111110001000001100110010001011111001010011001001000101', '0111011111110111010111100110101000010100101000001010001001011111010010100111110110000011100001100000110000111000011011100000000', '0110100111001000100100110110010001011110000000110111000011110000100111001000100110011100100001100000101111111100010111100111001', '0101101111010110000000001000010110100101001100001101110010101111010110001010000111010010001111000000011001001001111100111010110', '0100000110010101111011110111000010001101011110010000110010001111001101010010000011111100100101101000010000111100111010000000110', '0011110110011011000110000100100110111000000010010101111011111000111001100011110100001100010100100001110101110100011100110001100']

Use batches and advanced options

Explore the batch execution mode and advanced options to optimize circuit performance on QPUs.

import numpy as np
from qiskit.circuit.library import iqp
from qiskit.quantum_info import random_hermitian
from qiskit.transpiler import generate_preset_pass_manager
from qiskit_ibm_runtime import Batch, SamplerV2 as Sampler
from qiskit_ibm_runtime import QiskitRuntimeService

n_qubits = 127

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

rng = np.random.default_rng(1234)
mat = np.real(random_hermitian(n_qubits, seed=rng))
circuit = iqp(mat)
circuit.measure_all()
mat = np.real(random_hermitian(n_qubits, seed=rng))
another_circuit = iqp(mat)
another_circuit.measure_all()

pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuit = pm.run(circuit)
another_isa_circuit = pm.run(another_circuit)

# The context manager automatically closes the batch.
with Batch(backend=backend) as batch:
    sampler = Sampler(mode=batch)
    job = sampler.run([isa_circuit])
    another_job = sampler.run([another_isa_circuit])
    result = job.result()
    another_result = another_job.result()

# first job

print(
    f" > The first five measurement results of job 1: {result[0].data.meas.get_bitstrings()[:5]}"
)

Output:

 > The first five measurement results of job 1: ['1001111000111001100010010111000111101101000000101000010010101001110000000010001110010001011000100100000101010010000001001000010', '0000010000001101010100011001001011011010000110000100011000000000011000010111101100010101011100100101000110011000110000000000011', '0001100011110010110100110010111001001110101100100010011001100100111000110011000100000000100001001001100100101010110010000111101', '1000100111000111010011111010010111011001100000001001101010100001101010010110100100001010000000101110100010000000100110001100000', '1011011111101100000001001010111100001001111010000000001011001000011010000101110000101010101011000110110011010011011000010000001']

# second job
print(
    " > The first five measurement results of job 2:",
    another_result[0].data.meas.get_bitstrings()[:5],
)

Output:

 > The first five measurement results of job 2: ['1100111000010110001000101110100001011010101100101001111000100100010101111111001000000000000000110000001100110001001000000010000', '0011010001111000001011011010011000110010101111001100000000011110011011110010010011010000000010010011001011001110010001000100100', '0101001001101010011010011000001001010000001111001100001001011100110001001001001110100001101000000101000001000011000000000110100', '0100010010100000101000001001100010000110100111010000101010010110111111110010000011001110000001100000001011000000000100000000001', '1101000000001110110101011000011111111101011101100010000001011010010001110100001010001010010110100010000010100011000000010100100']

Next steps

Recommendations