{
"cells": [
{
"cell_type": "markdown",
"id": "0be36083-7bf5-48b7-9241-7979d6853d0c",
"metadata": {},
"source": [
"---\n",
"title: Sampler examples\n",
"description: Practical examples of using the Sampler primitive in Qiskit Runtime.\n",
"---\n",
"\n",
"# Sampler examples\n",
"\n"
]
},
{
"cell_type": "markdown",
"id": "ef0ce9e6-eee0-4b4b-a068-52e8cbd69115",
"metadata": {
"tags": [
"version-info"
]
},
"source": [
"{/*\n",
" DO NOT EDIT THIS CELL!!!\n",
" This cell's content is generated automatically by a script. Anything you add\n",
" here will be removed next time the notebook is run. To add new content, create\n",
" a new cell before or after this one.\n",
" */}\n",
"\n",
"\n",
" Package versions
\n",
"\n",
" The code on this page was developed using the following requirements.\n",
" We recommend using these versions or newer.\n",
"\n",
" ```\n",
" qiskit[all]~=2.3.0\n",
" qiskit-ibm-runtime~=0.43.1\n",
" ```\n",
" \n",
"\n"
]
},
{
"cell_type": "markdown",
"id": "ab973ab2-72aa-4a57-9132-b46002738489",
"metadata": {},
"source": [
"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.\n",
"\n",
"## Run a single experiment\n",
"\n",
"Use Sampler to return the measurement outcome as bitstrings or counts of a single circuit.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "fffb9af3-e122-4ca9-93e3-79edd6112ff8",
"metadata": {
"scrolled": true
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" > First ten results: ['0101110000110001001111000101001111000110110100011000100101011101110011010010010101000110000111101010101000001010000100100000100', '0100010101111101010000100010011100110001010000011000000010001100010111000011001010000100100000100000000010000000010010101011110', '1101010111111111100010000011101010101010100100011001000000001001110010001000000010000010000101000111000100010010000001111000010', '1001110001100001001101111010111100000100010110010001001100111000110010111000001010001000000000000000100101101001110010101000110', '0001000000011011000011000111001000000000100110110011111110110100110000101010100010000010101011011000101011101000100000110000011', '1011100010011111010000001110110000111101000001110010011001100011111010001100100000110001000010001010110011100010000111000111010', '1101110000011000001011011000001111001110010111111111100100010001110100000010000001011000110000000011010011110100101001101000010', '0110100000110011000011001000110110110001000100100001111010001101000001010111000000101010101000001110100100001010110001000100101', '1000011010011011001111010010100000001110010010100000011010000110011010100000111000010010100111000001100101100010110010101001010', '1011011100111001010010101001000111000001110011110011001111010100100011101111011101011000000111011010000011100011010000001000000']\n"
]
}
],
"source": [
"import numpy as np\n",
"from qiskit.circuit.library import iqp\n",
"from qiskit.transpiler import generate_preset_pass_manager\n",
"from qiskit.quantum_info import random_hermitian\n",
"from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler\n",
"\n",
"n_qubits = 127\n",
"\n",
"service = QiskitRuntimeService()\n",
"backend = service.least_busy(\n",
" operational=True, simulator=False, min_num_qubits=n_qubits\n",
")\n",
"\n",
"mat = np.real(random_hermitian(n_qubits, seed=1234))\n",
"circuit = iqp(mat)\n",
"circuit.measure_all()\n",
"\n",
"pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n",
"isa_circuit = pm.run(circuit)\n",
"\n",
"sampler = Sampler(backend)\n",
"job = sampler.run([isa_circuit])\n",
"result = job.result()\n",
"\n",
"# Get results for the first (and only) PUB\n",
"pub_result = result[0]\n",
"\n",
"print(f\" > First ten results: {pub_result.data.meas.get_bitstrings()[:10]}\")"
]
},
{
"cell_type": "markdown",
"id": "6b1cd3d9-8487-4889-9cd6-638a13fc7127",
"metadata": {},
"source": [
"## Run multiple experiments in a single job\n",
"\n",
"Use Sampler to return the measurement outcome as bitstrings or counts of multiple circuits in one job.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "4f68f509-7965-41f7-9f5e-7922a45ba22d",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" > First ten results for pub 0: ['1000000101000100010111001010101010000001001010101011011001011110001000000110110101010000010000000000110001001000011111110000001', '1111101011011011110001011000001100001101100001000101111011101110000101111010001011111010001001000010111001110111000010001011010', '1100100101110010000110101011110010111001101010001101100010110100110110000110110010001110001000001010011100001000011011000111010', '1100010010000100100010110100011010011001010101101101101001100001001110011001011011111100011100100001000101010000111101110001101', '0011101011101100010011111001001110000101100110000110000001111000011010011110000110100000110011011000000010110001010000111000100', '0110101101110000010110100100010011000100100010000010010010110001111111110000101011000100010000000100100100110011010111101110111', '1101011000111100011000010110000010001100101011000001110010110001111101010101011110110010000100011101000001010110010101000000100', '0000101010010100000010111110111000001011000000001011000110100010110011111000110110010110011010111101001011000000001101001110110', '1100101000110001000011111110010001011000010110010101101000000101011110000100011011111011011010001001110011011101001101010100000', '0110011000101110101001010100110010101000010111100001000111011000110101011010010101110011001010101000001001001000110010100010101']\n",
" > First ten results for pub 1: ['1100100001011010010100000110101010100111101100110000100001011000100010001101010101101110000011010010011000010000010001000001000', '1100000011000000100110011000000110010000011111000000001010000101000010011001000001010000001000001010001000110010111000010000000', '0010000111101000111010101010101001010000001110100001011011100011000111000000010101001000010101001100000010100010011000000000010', '0010100100001000011100001010011000001010000010001000000001011100001010001110010110111101101000001101010101000000000011000100110', '0101101000011110111000100010000000101110100001010101110010001100001100001000111111110101001010100110000000010011111111000000010', '0101010111000000001110100110100011010111000111110100010010010001011010001000101001100001100110001001001000010010000011100100000', '0110010000001110111010010100010010010011010010110101001110010010001001101010111000010000000100011001001000001111010001100010010', '1100001100101011011010000110111110001101010100010100101100111000010000101101101010111011111011101100000000110000100101001000101', '0000111100001000000101101001010111110100011011011101101111000000001010001001100010110000100000000001010100110001001100110010000', '0100100001001011110000110001100001111011111100000001010111011011100010110111101110101111101010100101000000110111000110000000000']\n",
" > First ten results for pub 2: ['1000010100111010101010111110101000110101010001111110011110011001010100001100100000000001000111111011001101100001001110011101100', '1110100000111000000000110110010100000011110000011110000110100010000100001100010101101001100100010111000010100101011000001000000', '1000010111011000000001110111010101000111111010010011110100001010000000111111100100001111111101010100001001011100111101010000010', '0000111011110110010011100111001010001000011010010110010010101000101110011100000010000101011000101001001001000100111101010100100', '0100000100111101110000101111011000100111101011101110100001000001000010101111100100000111010001101001100001100011011110101101100', '0100001000110101010010010100100110000100001010100001110001110101010011000111100111001001100000010100110111010111010100010100100', '0011111000010001101100000110111001000000100111110100001100001100010010010101011000000111011011111010100010000100100000100000000', '1000010010101100110110110110100010100000111001101011110100001000011000001000000110010001001011100100000000100000000000000000000', '0001011100010011111110011110000001000000010100111111000000101010000011011110110000110001010010000010010001000101110001111100010', '1111010100011100010010010110000101110000010001100101011111001100010111100001011001000001011010111011100001000001100000000000110']\n"
]
}
],
"source": [
"import numpy as np\n",
"from qiskit.circuit.library import iqp\n",
"from qiskit.transpiler import generate_preset_pass_manager\n",
"from qiskit.quantum_info import random_hermitian\n",
"from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler\n",
"\n",
"n_qubits = 127\n",
"\n",
"service = QiskitRuntimeService()\n",
"backend = service.least_busy(\n",
" operational=True, simulator=False, min_num_qubits=n_qubits\n",
")\n",
"\n",
"rng = np.random.default_rng()\n",
"mats = [np.real(random_hermitian(n_qubits, seed=rng)) for _ in range(3)]\n",
"circuits = [iqp(mat) for mat in mats]\n",
"for circuit in circuits:\n",
" circuit.measure_all()\n",
"\n",
"pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n",
"isa_circuits = pm.run(circuits)\n",
"\n",
"sampler = Sampler(mode=backend)\n",
"job = sampler.run(isa_circuits)\n",
"result = job.result()\n",
"\n",
"for idx, pub_result in enumerate(result):\n",
" print(\n",
" f\" > First five results for pub {idx}: {pub_result.data.meas.get_bitstrings()[:5]}\"\n",
" )"
]
},
{
"cell_type": "markdown",
"id": "f6298621-8160-4e8b-8f43-316c5e388dd0",
"metadata": {},
"source": [
"## Run parameterized circuits\n",
"\n",
"Run several experiments in a single job, leveraging parameter values to increase circuit reusability.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "b8633a12-3cbc-42a2-85db-4ea1a2d7bda7",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" >> First ten results for the meas output register: ['1100011011100001011000001001000001111110000001011100011110011100111110000111000100011100001111100010010111110001001111011000101', '1100011101010101010000100110110110010001100101011101001011101010111110000111110100000011111010101101011101101101001111011110011', '0000000011000011001101001000111110001100010010011011001111000101000000001111111101101011100111010110111101010111011001010001011', '0101010001101110100010001100111001011101101100001000100001011101110100001000011011001011110101000110010001001010011011100011101', '0110101110000010110000001000010101100010010001001001101000010100110001011111110001000001100110010001011111001010011001001000101', '0111011111110111010111100110101000010100101000001010001001011111010010100111110110000011100001100000110000111000011011100000000', '0110100111001000100100110110010001011110000000110111000011110000100111001000100110011100100001100000101111111100010111100111001', '0101101111010110000000001000010110100101001100001101110010101111010110001010000111010010001111000000011001001001111100111010110', '0100000110010101111011110111000010001101011110010000110010001111001101010010000011111100100101101000010000111100111010000000110', '0011110110011011000110000100100110111000000010010101111011111000111001100011110100001100010100100001110101110100011100110001100']\n"
]
}
],
"source": [
"import numpy as np\n",
"from qiskit.circuit.library import real_amplitudes\n",
"from qiskit.transpiler import generate_preset_pass_manager\n",
"from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler\n",
"\n",
"n_qubits = 127\n",
"\n",
"service = QiskitRuntimeService()\n",
"backend = service.least_busy(\n",
" operational=True, simulator=False, min_num_qubits=n_qubits\n",
")\n",
"\n",
"# Step 1: Map classical inputs to a quantum problem\n",
"circuit = real_amplitudes(num_qubits=n_qubits, reps=2)\n",
"circuit.measure_all()\n",
"\n",
"# Define three sets of parameters for the circuit\n",
"rng = np.random.default_rng(1234)\n",
"parameter_values = [\n",
" rng.uniform(-np.pi, np.pi, size=circuit.num_parameters) for _ in range(3)\n",
"]\n",
"\n",
"# Step 2: Optimize problem for quantum execution.\n",
"\n",
"pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n",
"isa_circuit = pm.run(circuit)\n",
"\n",
"# Step 3: Execute using Qiskit primitives.\n",
"sampler = Sampler(backend)\n",
"job = sampler.run([(isa_circuit, parameter_values)])\n",
"result = job.result()\n",
"# Get results for the first (and only) PUB\n",
"pub_result = result[0]\n",
"# Get counts from the classical register \"meas\".\n",
"print(\n",
" f\" >> First five results for the meas output register: {pub_result.data.meas.get_bitstrings()[:5]}\"\n",
")"
]
},
{
"cell_type": "markdown",
"id": "06bf761a-e9b7-47ca-911e-01b126090466",
"metadata": {},
"source": [
"## Use batches and advanced options\n",
"\n",
"Explore the batch [execution mode](/docs/guides/execution-modes) and advanced options to optimize circuit performance on QPUs.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "536ac5b5-00cf-42bf-a114-28144008d744",
"metadata": {
"scrolled": true
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" > The first five measurement results of job 1: ['1001111000111001100010010111000111101101000000101000010010101001110000000010001110010001011000100100000101010010000001001000010', '0000010000001101010100011001001011011010000110000100011000000000011000010111101100010101011100100101000110011000110000000000011', '0001100011110010110100110010111001001110101100100010011001100100111000110011000100000000100001001001100100101010110010000111101', '1000100111000111010011111010010111011001100000001001101010100001101010010110100100001010000000101110100010000000100110001100000', '1011011111101100000001001010111100001001111010000000001011001000011010000101110000101010101011000110110011010011011000010000001']\n"
]
}
],
"source": [
"import numpy as np\n",
"from qiskit.circuit.library import iqp\n",
"from qiskit.quantum_info import random_hermitian\n",
"from qiskit.transpiler import generate_preset_pass_manager\n",
"from qiskit_ibm_runtime import Batch, SamplerV2 as Sampler\n",
"from qiskit_ibm_runtime import QiskitRuntimeService\n",
"\n",
"n_qubits = 127\n",
"\n",
"service = QiskitRuntimeService()\n",
"backend = service.least_busy(\n",
" operational=True, simulator=False, min_num_qubits=n_qubits\n",
")\n",
"\n",
"rng = np.random.default_rng(1234)\n",
"mat = np.real(random_hermitian(n_qubits, seed=rng))\n",
"circuit = iqp(mat)\n",
"circuit.measure_all()\n",
"mat = np.real(random_hermitian(n_qubits, seed=rng))\n",
"another_circuit = iqp(mat)\n",
"another_circuit.measure_all()\n",
"\n",
"pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n",
"isa_circuit = pm.run(circuit)\n",
"another_isa_circuit = pm.run(another_circuit)\n",
"\n",
"# The context manager automatically closes the batch.\n",
"with Batch(backend=backend) as batch:\n",
" sampler = Sampler(mode=batch)\n",
" job = sampler.run([isa_circuit])\n",
" another_job = sampler.run([another_isa_circuit])\n",
" result = job.result()\n",
" another_result = another_job.result()\n",
"\n",
"# first job\n",
"\n",
"print(\n",
" f\" > The first five measurement results of job 1: {result[0].data.meas.get_bitstrings()[:5]}\"\n",
")"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "44b4c746-232b-4876-87c4-002cf6d11db7",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" > The first five measurement results of job 2: ['1100111000010110001000101110100001011010101100101001111000100100010101111111001000000000000000110000001100110001001000000010000', '0011010001111000001011011010011000110010101111001100000000011110011011110010010011010000000010010011001011001110010001000100100', '0101001001101010011010011000001001010000001111001100001001011100110001001001001110100001101000000101000001000011000000000110100', '0100010010100000101000001001100010000110100111010000101010010110111111110010000011001110000001100000001011000000000100000000001', '1101000000001110110101011000011111111101011101100010000001011010010001110100001010001010010110100010000010100011000000010100100']\n"
]
}
],
"source": [
"# second job\n",
"print(\n",
" \" > The first five measurement results of job 2:\",\n",
" another_result[0].data.meas.get_bitstrings()[:5],\n",
")"
]
},
{
"cell_type": "markdown",
"id": "d5c423e4-7586-4fdf-8452-3c62a705c955",
"metadata": {},
"source": [
"## Next steps\n",
"\n",
"\n",
" * [Specify advanced runtime options](runtime-options-overview).\n",
" * Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n",
" * Learn how to transpile locally in the [Transpile](/docs/guides/transpile/) section.\n",
" * Try the [Compare transpiler settings](/docs/guides/circuit-transpilation-settings) guide.\n",
" * Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n",
" * Understand the [Job limits](/docs/guides/job-limits) when sending a job to an IBM® QPU.\n",
"\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"id": "a1b8767d",
"source": "© IBM Corp., 2017-2026"
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3"
}
},
"nbformat": 4,
"nbformat_minor": 4
}