{
"cells": [
{
"cell_type": "markdown",
"id": "828c3465-62a7-4c42-b376-e3ec32f67595",
"metadata": {},
"source": [
"---\n",
"title: Noise learning helper\n",
"description: Get started with the noise learning helper program to save the noise models created when executing workloads in Qiskit IBM Runtime\n",
"---\n",
"\n",
"# Noise learning helper\n",
"\n"
]
},
{
"cell_type": "markdown",
"id": "40a246f5-4efd-4fb0-861b-c4e013c1572a",
"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",
" \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.4.1\n",
" qiskit-ibm-runtime~=0.47.0\n",
" samplomatic~=0.18.0\n",
" ```\n",
" \n",
"\n",
"\n"
]
},
{
"cell_type": "markdown",
"id": "cce93074-df51-4760-9fce-5a520c3bc59a",
"metadata": {},
"source": [
"The error mitigation techniques [PEA](/docs/guides/error-mitigation-and-suppression-techniques#pea) and [PEC](/docs/guides/error-mitigation-and-suppression-techniques#pec) both utilize a noise learning component based on a [Pauli-Lindblad noise model](https://arxiv.org/abs/2201.09866), which is typically managed during execution after submitting one or more jobs through `qiskit-ibm-runtime` without any local access to the fitted noise model. However, as of `qiskit-ibm-runtime` v0.27.1, a [`NoiseLearner`](/docs/api/qiskit-ibm-runtime/noise-learner) and associated [`NoiseLearnerOptions`](/docs/api/qiskit-ibm-runtime/options-noise-learner-options) class have been created to obtain the results of these noise learning experiments. These results can then be stored locally as a `NoiseLearnerResult` and used as input in later experiments. This page provides an overview of its usage and the associated options available.\n",
"\n",
"In addition, starting with `qiskit-ibm-runtime` v0.47.0, there is a new `NoiseLearnerV3` class that is compatible with the Executor primitive. This new version, also part of the [directed execution model](/docs/guides/directed-execution-model), gives you the ability to explicitly specify the layers you want to learn.\n",
"\n",
"\n",
" `NoiseLearner` only works with EstimatorV2 and `NoiseLearnerV3` only works with Executor.\n",
"\n",
"\n",
"## `NoiseLearner`\n",
"\n",
"### Overview\n",
"\n",
"The `NoiseLearner` class performs experiments that characterize noise processes based on a Pauli-Lindblad noise model for one (or more) circuits. It possesses a `run()` method that executes the learning experiments and takes as input either a list of circuits or a [PUB](/docs/guides/primitive-input-output), and returns a `NoiseLearnerResult` containing the learned noise channels and metadata about the job(s) submitted. Below is a code snippet demonstrating the usage of the helper program.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "d9a5320d-8ec6-483a-9ecf-931b0f5f5d13",
"metadata": {},
"outputs": [],
"source": [
"from qiskit import QuantumCircuit\n",
"from qiskit.transpiler import CouplingMap\n",
"from qiskit.transpiler import generate_preset_pass_manager\n",
"\n",
"from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2\n",
"from qiskit_ibm_runtime.noise_learner import NoiseLearner\n",
"from qiskit_ibm_runtime.options import (\n",
" NoiseLearnerOptions,\n",
" ResilienceOptionsV2,\n",
" EstimatorOptions,\n",
")\n",
"\n",
"# Build a circuit with two entangling layers\n",
"num_qubits = 27\n",
"edges = list(CouplingMap.from_line(num_qubits, bidirectional=False))\n",
"even_edges = edges[::2]\n",
"odd_edges = edges[1::2]\n",
"\n",
"circuit = QuantumCircuit(num_qubits)\n",
"for pair in even_edges:\n",
" circuit.cx(pair[0], pair[1])\n",
"for pair in odd_edges:\n",
" circuit.cx(pair[0], pair[1])\n",
"\n",
"# Choose a backend to run on\n",
"service = QiskitRuntimeService()\n",
"backend = service.least_busy()\n",
"\n",
"# Transpile the circuit for execution\n",
"pm = generate_preset_pass_manager(backend=backend, optimization_level=3)\n",
"circuit_to_learn = pm.run(circuit)\n",
"\n",
"# Instantiate a NoiseLearner object and execute the noise learning program\n",
"learner = NoiseLearner(mode=backend)\n",
"job = learner.run([circuit_to_learn])\n",
"noise_model = job.result()"
]
},
{
"cell_type": "markdown",
"id": "ef141d65-d14d-4e2b-9813-b8766e29fdb9",
"metadata": {},
"source": [
"The resulting `NoiseLearnerResult.data` is a list of [`LayerError`](../api/qiskit-ibm-runtime/utils-noise-learner-result-layer-error) objects containing the [noise model](https://arxiv.org/abs/2201.09866) for each individual entangling layer that belongs to the target circuit(s). Each `LayerError` stores the layer information, in the form of a circuit and a set of qubit labels, alongside the [`PauliLindbladError`](../api/qiskit-ibm-runtime/utils-noise-learner-result-pauli-lindblad-error) for the noise model that was learned for the given layer.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a9be8ff1-7494-407c-853c-50d471a2f55f",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Noise learner result contains 2 entries and has the following type:\n",
" \n",
"\n",
"Each element of `NoiseLearnerResult` then contains an object of type:\n",
" \n",
"\n",
"And each of these `LayerError` objects possess data on the generators for the error channel: \n",
"['IIIIIIIIIIIIIIIIIIIIIIIIIIX', 'IIIIIIIIIIIIIIIIIIIIIIIIIIY',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIIIZ', 'IIIIIIIIIIIIIIIIIIIIIIIIIXI',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIIXX', 'IIIIIIIIIIIIIIIIIIIIIIIIIXY',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIIXZ', 'IIIIIIIIIIIIIIIIIIIIIIIIIYI',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIIYX', 'IIIIIIIIIIIIIIIIIIIIIIIIIYY',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIIYZ', 'IIIIIIIIIIIIIIIIIIIIIIIIIZI',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIIZX', 'IIIIIIIIIIIIIIIIIIIIIIIIIZY',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIIZZ', 'IIIIIIIIIIIIIIIIIIIIIIIIXII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIXIX', 'IIIIIIIIIIIIIIIIIIIIIIIIXIY',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIXIZ', 'IIIIIIIIIIIIIIIIIIIIIIIIYII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIYIX', 'IIIIIIIIIIIIIIIIIIIIIIIIYIY',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIYIZ', 'IIIIIIIIIIIIIIIIIIIIIIIIZII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIZIX', 'IIIIIIIIIIIIIIIIIIIIIIIIZIY',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIIZIZ', 'IIIIIIIIIIIIIIIIIIIIIIIXIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIIYIII', 'IIIIIIIIIIIIIIIIIIIIIIIZIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIXIIII', 'IIIIIIIIIIIIIIIIIIIIIIXXIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIXYIII', 'IIIIIIIIIIIIIIIIIIIIIIXZIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIYIIII', 'IIIIIIIIIIIIIIIIIIIIIIYXIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIYYIII', 'IIIIIIIIIIIIIIIIIIIIIIYZIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIZIIII', 'IIIIIIIIIIIIIIIIIIIIIIZXIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIIZYIII', 'IIIIIIIIIIIIIIIIIIIIIIZZIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIXIIIII', 'IIIIIIIIIIIIIIIIIIIIIXXIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIXYIIII', 'IIIIIIIIIIIIIIIIIIIIIXZIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIYIIIII', 'IIIIIIIIIIIIIIIIIIIIIYXIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIYYIIII', 'IIIIIIIIIIIIIIIIIIIIIYZIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIZIIIII', 'IIIIIIIIIIIIIIIIIIIIIZXIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIIZYIIII', 'IIIIIIIIIIIIIIIIIIIIIZZIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIXIIIIII', 'IIIIIIIIIIIIIIIIIIIIXXIIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIXYIIIII', 'IIIIIIIIIIIIIIIIIIIIXZIIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIYIIIIII', 'IIIIIIIIIIIIIIIIIIIIYXIIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIYYIIIII', 'IIIIIIIIIIIIIIIIIIIIYZIIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIZIIIIII', 'IIIIIIIIIIIIIIIIIIIIZXIIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIIZYIIIII', 'IIIIIIIIIIIIIIIIIIIIZZIIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIXIIIIIII', 'IIIIIIIIIIIIIIIIIIIXXIIIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIXYIIIIII', 'IIIIIIIIIIIIIIIIIIIXZIIIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIYIIIIIII', 'IIIIIIIIIIIIIIIIIIIYXIIIIII',\n",
" 'IIIIIIIIIIIIIIIIIIIYYIIIIII', 'IIIIIIIIIIIIIIIIIIIYZIIIIII', ...]\n",
"\n",
"Along with the error rates: \n",
"[5.9e-04 5.3e-04 5.7e-04 ... 0.0e+00 1.0e-05 0.0e+00]\n",
"\n"
]
}
],
"source": [
"import numpy\n",
"\n",
"print(\n",
" f\"Noise learner result contains {len(noise_model.data)} entries\"\n",
" f\" and has the following type:\\n {type(noise_model)}\\n\"\n",
")\n",
"print(\n",
" f\"Each element of `NoiseLearnerResult` then contains\"\n",
" f\" an object of type:\\n {type(noise_model.data[0])}\\n\"\n",
")\n",
"# Results are truncated\n",
"with numpy.printoptions(threshold=200):\n",
" print(\n",
" f\"And each of these `LayerError` objects possess\"\n",
" f\" data on the generators for the error channel: \\n\"\n",
" f\"{noise_model.data[0].error.generators}\\n\"\n",
" )\n",
"# Results are truncated\n",
"with numpy.printoptions(threshold=200):\n",
" print(\n",
" f\"Along with the error rates: \\n{noise_model.data[0].error.rates}\\n\"\n",
" )"
]
},
{
"cell_type": "markdown",
"id": "faa3892e-30a5-48f7-87dd-39ab1b0846d9",
"metadata": {},
"source": [
"The `LayerError.error` attribute of the noise learning result contains the generators and error rates of the fitted Pauli Lindblad model, which has the form\n",
"\n",
"$\\Lambda(\\rho) = \\exp{\\sum_j r_j \\left(P_j \\rho P_j^\\dagger - \\rho\\right)},$\n",
"\n",
"where the $r_j$ are the `LayerError.rates` and $P_j$ are the Pauli operators specified in `LayerError.generators`.\n",
"\n"
]
},
{
"cell_type": "markdown",
"id": "fc0000e6-e77a-4b87-a9ee-262f904953fc",
"metadata": {},
"source": [
"### Noise learning options\n",
"\n",
"You can choose among several options to input when you instantiate a `NoiseLearner` object. These options are encapsulated by the `qiskit_ibm_runtime.options.NoiseLearnerOptions` class and include the ability to specify the maximum layers to learn, number of randomizations, and the twirling strategy, among others. Refer to the [`NoiseLearnerOptions`](/docs/api/qiskit-ibm-runtime/options-noise-learner-options) API documentation for detailed information.\n",
"\n",
"Following is a simple example that shows how to use the `NoiseLearnerOptions` in a `NoiseLearner` experiment:\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "fcd1bd93-405d-4cfb-a5d1-bb646404aa58",
"metadata": {},
"outputs": [],
"source": [
"# Build a GHZ circuit\n",
"circuit = QuantumCircuit(10)\n",
"circuit.h(0)\n",
"circuit.cx(range(0, 9), range(1, 10))\n",
"# Choose a backend to run on\n",
"service = QiskitRuntimeService()\n",
"backend = service.least_busy()\n",
"\n",
"# Transpile the circuit for execution\n",
"pm = generate_preset_pass_manager(backend=backend, optimization_level=3)\n",
"circuit_to_run = pm.run(circuit_to_learn)\n",
"\n",
"# Instantiate a NoiseLearnerOptions object\n",
"learner_options = NoiseLearnerOptions(\n",
" max_layers_to_learn=3, num_randomizations=32, twirling_strategy=\"all\"\n",
")\n",
"\n",
"# Instantiate a NoiseLearner object and execute the noise learning program\n",
"learner = NoiseLearner(mode=backend, options=learner_options)\n",
"job = learner.run([circuit_to_run])\n",
"noise_model = job.result()"
]
},
{
"cell_type": "markdown",
"id": "d952d0cc-497b-45ae-a55e-2b611ebbe4a3",
"metadata": {},
"source": [
"### Input noise model to a primitive\n",
"\n",
"The noise model learned on the circuit can also be used as an input to the `EstimatorV2` primitive implemented in Qiskit Runtime. This can be passed into the primitive a few different ways. The next three examples show how you can pass the noise model to the `estimator.options` attribute directly, by using a `ResilienceOptionsV2` object before instantiating an Estimator primitive, and by passing in an appropriately formatted dictionary.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "9826013a-f9fd-4d72-baa7-dc5395b81007",
"metadata": {},
"outputs": [],
"source": [
"# Pass the noise model to the `estimator.options` attribute directly\n",
"estimator = EstimatorV2(mode=backend)\n",
"estimator.options.resilience.layer_noise_model = noise_model"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "7ab10595-5c20-4954-9001-70b8879926b4",
"metadata": {},
"outputs": [],
"source": [
"# Specify options through a ResilienceOptionsV2 object\n",
"resilience_options = ResilienceOptionsV2(layer_noise_model=noise_model)\n",
"estimator_options = EstimatorOptions(resilience=resilience_options)\n",
"estimator = EstimatorV2(mode=backend, options=estimator_options)"
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "17b1f8de-fe14-4998-898b-ecd409a5efd3",
"metadata": {},
"outputs": [],
"source": [
"# Specify options by using a dictionary\n",
"options_dict = {\n",
" \"resilience_level\": 2,\n",
" \"resilience\": {\"layer_noise_model\": noise_model},\n",
"}\n",
"\n",
"estimator = EstimatorV2(mode=backend, options=options_dict)"
]
},
{
"cell_type": "markdown",
"id": "8c167b65-2e9a-41b9-b593-edfe80a2fde4",
"metadata": {},
"source": [
"After the noise model is passed into the `EstimatorV2` object, it can be used to run workloads and perform error mitigation as normal.\n",
"\n"
]
},
{
"cell_type": "markdown",
"id": "dad71939-7fe2-42f0-90fe-6974fe0854e7",
"metadata": {},
"source": [
"## NoiseLearnerV3\n",
"\n",
"### Overview\n",
"\n",
"Similar to `NoiseLearner`, the `NoiseLearnerV3` class performs experiments that characterize noise processes based on a Pauli-Lindblad noise model for one or more circuits. Its `run()` method takes a list of instructions, each of which must be a twirled-annotated [`BoxOp`](/docs/api/qiskit/qiskit.circuit.BoxOp) containing [ISA](/docs/guides/transpile#instruction-set-architecture) operations.\n",
"\n",
"The result of a `NoiseLearnerV3` job contains a list of [`NoiseLearnerV3Result`](/docs/api/qiskit-ibm-runtime/results-noise-learner-v3-result) objects, one for each input instruction.\n",
"The following code shows how to use the helper program.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "0bbd2c21-6045-4954-aee9-339e6b060805",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Found 3 unique layers\n",
"Each instruction is of type \n",
"And has annotations: [Twirl(group='pauli', dressing='left', decomposition='rzsx'), InjectNoise(ref='r789B', modifier_ref='', site='before')]\n"
]
}
],
"source": [
"from qiskit import QuantumCircuit\n",
"from qiskit.transpiler import CouplingMap\n",
"from qiskit.transpiler import generate_preset_pass_manager\n",
"\n",
"from qiskit_ibm_runtime import QiskitRuntimeService, Executor\n",
"from qiskit_ibm_runtime.noise_learner_v3 import NoiseLearnerV3\n",
"from samplomatic.transpiler import generate_boxing_pass_manager\n",
"from samplomatic.utils import find_unique_box_instructions\n",
"\n",
"\n",
"# Build a circuit with two entangling layers\n",
"num_qubits = 27\n",
"edges = list(CouplingMap.from_line(num_qubits, bidirectional=False))\n",
"even_edges = edges[::2]\n",
"odd_edges = edges[1::2]\n",
"\n",
"circuit = QuantumCircuit(num_qubits)\n",
"for pair in even_edges:\n",
" circuit.cx(pair[0], pair[1])\n",
"for pair in odd_edges:\n",
" circuit.cx(pair[0], pair[1])\n",
"\n",
"# Choose a backend to run on\n",
"service = QiskitRuntimeService()\n",
"backend = service.least_busy()\n",
"\n",
"# Transpile the circuit for execution\n",
"pm = generate_preset_pass_manager(backend=backend, optimization_level=3)\n",
"isa_circuit = pm.run(circuit)\n",
"\n",
"# Run the boxing pass manager to group instructions into annotated boxes\n",
"boxing_pm = generate_boxing_pass_manager(\n",
" enable_gates=True,\n",
" enable_measures=False,\n",
" inject_noise_targets=\"gates\", # no measurement mitigation\n",
" inject_noise_strategy=\"uniform_modification\",\n",
")\n",
"boxed_circuit = boxing_pm.run(isa_circuit)\n",
"\n",
"# Find unique boxed instructions\n",
"unique_box_instructions = find_unique_box_instructions(boxed_circuit.data)\n",
"print(f\"Found {len(unique_box_instructions)} unique layers\")\n",
"print(\n",
" f\"Each instruction is of type {type(unique_box_instructions[0].operation)}\"\n",
")\n",
"print(\n",
" f\"And has annotations: {unique_box_instructions[0].operation.annotations}\"\n",
")\n",
"\n",
"# Instantiate a NoiseLearnerV3 object and execute the noise learning program\n",
"learner = NoiseLearnerV3(backend)\n",
"learner.options.shots_per_randomization = 128\n",
"learner.options.num_randomizations = 32\n",
"learner_job = learner.run(unique_box_instructions)\n",
"learner_result = learner_job.result()"
]
},
{
"cell_type": "markdown",
"id": "937986c1-b08d-4218-ae5d-c9dbfbf4a0cf",
"metadata": {},
"source": [
"The job result is a list of `NoiseLearnerV3Result` objects, one for each input-boxed set of instructions. `NoiseLearnerV3Result` has a `to_pauli_lindblad_map()` method that returns a [`PauliLindbladMap`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap) object, which has methods to extract the generators, error rates, and more.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4a9b686b-cf8d-4986-8fff-83eedda1f2c1",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"The Noise learner V3 result contains 3 entries and each has the following type:\n",
" \n",
"\n",
"After converting to PauliLindbladMap, you can extract data on the generators for the error channel (truncated to 3): \n",
"\n",
"\n",
"Along with the error rates (truncated to 3): \n",
"[0.00026 0.00032 0.00023]\n",
"\n"
]
}
],
"source": [
"print(\n",
" f\"The Noise learner V3 result contains {len(learner_result)} entries\"\n",
" f\" and each has the following type:\\n {type(learner_result[0])}\\n\"\n",
")\n",
"noise_map = learner_result[0].to_pauli_lindblad_map()\n",
"print(\n",
" f\"After converting to PauliLindbladMap, you can extract data \"\n",
" f\" on the generators for the error channel \"\n",
" f\"(truncated to 3): \\n{noise_map.generators()[:3]}\\n\"\n",
")\n",
"with numpy.printoptions(threshold=20):\n",
" print(\n",
" f\"Along with the error rates \"\n",
" f\"(truncated to 3): \\n{noise_map.rates[:3]}\\n\"\n",
" )"
]
},
{
"cell_type": "markdown",
"id": "baa61d6a-7efc-498b-bccd-260871e174df",
"metadata": {},
"source": [
"### Noise learning options\n",
"\n",
"`NoiseLearnerV3` supports several options, including the number of randomizations and layer pair depth, among others. Similar to the primitives, you can specify the options during or after instantiating the `NoiseLearnerV3` object. The previous code example demonstrated how to set the `shots_per_randomization` and `num_randomizations` options. Refer to the [`NoiseLearnerV3Options`](/docs/api/qiskit-ibm-runtime/options-models-noise-learner-v3-options) API documentation for detailed information.\n",
"\n"
]
},
{
"cell_type": "markdown",
"id": "e76e997d-506f-4607-a89a-e4723c640a44",
"metadata": {},
"source": [
"### Input a noise model to Executor\n",
"\n",
"Executor follows the design intents specified in circuit annotations (in the form of a samplex) and options. `InjectNoise` is the annotation for specifying where to inject noise, and the `pauli_lindblad_maps` samplex argument specifies which noise map to use.\n",
"\n",
"The circuit in the previous example runs through the boxing pass manager, which groups instructions into annotated boxes. The relevant code is added here for ease of understanding.\n",
"\n",
"* `inject_noise_targets=”gates”` specifies to add the `InjectNoise` annotations to boxes that contain entanglers.\n",
"* `inject_noise_strategy=\"uniform_modification\"` specifies to assign the same `ref` and `modifier_ref` to all equivalent boxes with `InjectNoise` annotations.\n",
" * `InjectNoise.ref` is a unique identifier used to assign a noise model to that box.\n",
" * `InjectNoise.modifier_ref` allows scaling the noise model assigned to a box by multiplicative factors.\n",
"\n",
"```python\n",
"boxing_pm = generate_boxing_pass_manager(\n",
" enable_gates=True,\n",
" enable_measures=False,\n",
" inject_noise_targets=\"gates\", # no measurement mitigation\n",
" inject_noise_strategy=\"uniform_modification\",\n",
")\n",
"```\n",
"\n",
"The circuit from the previous example contains three boxes, two of which contain `InjectNoise` annotations with different `ref` attributes (since they are not equivalent).\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "3b86853b-6766-4cf6-9a6b-2ea1008aea42",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Annotations of box #0: [Twirl(group='pauli', dressing='left', decomposition='rzsx'), InjectNoise(ref='r789B', modifier_ref='r789B', site='before')]\n",
"\n",
"Annotations of box #1: [Twirl(group='pauli', dressing='left', decomposition='rzsx'), InjectNoise(ref='r054B', modifier_ref='r054B', site='before')]\n",
"\n",
"Annotations of box #2: [Twirl(group='pauli', dressing='right', decomposition='rzsx')]\n",
"\n"
]
}
],
"source": [
"# box_circuit comes from the example above\n",
"for idx, instruction in enumerate(boxed_circuit):\n",
" # The `InjectNoise` annotation defines which boxes to inject noise.\n",
" print(f\"Annotations of box #{idx}: {instruction.operation.annotations}\\n\")"
]
},
{
"cell_type": "markdown",
"id": "3ab1e503-b36a-46bd-b5d1-2735c3d0a82d",
"metadata": {},
"source": [
"The result of the `NoiseLearnerV3` job must be converted to a dictionary before being passed to Executor. This dictionary's keys are the `InjectNoise.ref` attributes and the values are the corresponding noise maps. This mapping tells Executor which noise models to inject where.\n",
"\n",
"The following code shows how to take the circuit and the `NoiseLearnerV3` result from the previous example and pass them to Executor, which will generate the circuit variants with the injected noise models and execute them on hardware.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 10,
"id": "96d59082-7adc-482a-b57f-0f7a5c3eb217",
"metadata": {},
"outputs": [],
"source": [
"from qiskit_ibm_runtime.quantum_program import QuantumProgram\n",
"from samplomatic import build\n",
"\n",
"# Generate a quantum program\n",
"program = QuantumProgram(shots=1000)\n",
"\n",
"# Build the template circuit and samplex pair\n",
"template_circuit, samplex = build(boxed_circuit)\n",
"\n",
"# Convert the NoiseLearnerV3 result to a dictionary\n",
"noise_maps = learner_result.to_dict(\n",
" instructions=unique_box_instructions, require_refs=False\n",
")\n",
"\n",
"# Append the samplex item and execute\n",
"program.append_samplex_item(\n",
" template_circuit,\n",
" samplex=samplex,\n",
" samplex_arguments={\n",
" \"pauli_lindblad_maps\": noise_maps,\n",
" },\n",
")\n",
"\n",
"executor = Executor(backend)\n",
"executor_job = executor.run(program)"
]
},
{
"cell_type": "markdown",
"id": "936c08fb-7838-4d61-9060-092b479e7909",
"metadata": {},
"source": [
"## Next steps\n",
"\n",
"\n",
" * Review the [EstimatorOptions API reference](/docs/api/qiskit-ibm-runtime/options-estimator-options) and [ResilienceOptionsV2 API reference](/docs/api/qiskit-ibm-runtime/options-resilience-options-v2).\n",
" * Learn more about [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) that are available through Qiskit Runtime.\n",
" * Learn how to implement [Estimator noise management](/docs/guides/estimator-noise-management).\n",
" * Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\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
}