From dd2bc88cc2a66691786283b5c83062106cba0d96 Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Tue, 16 Jul 2024 15:48:15 -0400 Subject: [PATCH 01/44] Restore Options changes (revert #1722) This reverts commit 743c2149220d8f52445185c6118acde3ad3bd385. Co-authored-by: Arnau Casau Co-authored-by: Ian Hincks Co-authored-by: Jessie Yu --- .../qiskit-quantum-instance.mdx | 4 +- .../qiskit-runtime-examples.mdx | 2 +- .../qiskit-runtime-options.mdx | 2 +- .../qiskit-runtime-use-case.mdx | 12 +- docs/guides/_toc.json | 2 +- docs/guides/configure-error-mitigation.mdx | 50 +-- docs/guides/configure-error-suppression.mdx | 19 +- docs/guides/get-started-with-primitives.mdx | 8 +- docs/guides/primitives.mdx | 10 +- docs/guides/runtime-options-overview.mdx | 410 +++++++++++++++--- public/images/optimize/resilience-2.psd | Bin 0 -> 399862 bytes public/images/optimize/resilience-2.svg | 33 ++ 12 files changed, 435 insertions(+), 117 deletions(-) create mode 100644 public/images/optimize/resilience-2.psd create mode 100644 public/images/optimize/resilience-2.svg diff --git a/docs/api/migration-guides/qiskit-quantum-instance.mdx b/docs/api/migration-guides/qiskit-quantum-instance.mdx index cd5abe749cc..a3b2a238cbb 100644 --- a/docs/api/migration-guides/qiskit-quantum-instance.mdx +++ b/docs/api/migration-guides/qiskit-quantum-instance.mdx @@ -81,7 +81,7 @@ yourself two questions: This question is not new. In the legacy algorithm workflow, you would set up a [`qiskit.utils.QuantumInstance`](../qiskit/0.46/qiskit.utils.QuantumInstance) with either a real system from a provider, or a simulator. For this migration, this "system selection" process is translated to **where** do you import your primitives from: - + * Using **local** statevector simulators for quick prototyping: **Reference primitives** * Using **local** noisy simulations for finer algorithm tuning: **Aer primitives** * Accessing **runtime-enabled systems** (or cloud simulators): **Qiskit Runtime primitives** @@ -90,7 +90,7 @@ yourself two questions: Arguably, the `Sampler` is the closest primitive to [`qiskit.utils.QuantumInstance`](../qiskit/0.46/qiskit.utils.QuantumInstance), as they both execute circuits and provide a result. However, with the [`qiskit.utils.QuantumInstance`](../qiskit/0.46/qiskit.utils.QuantumInstance), the result data was system-dependent (it could be a counts `dict`, a `numpy.array` for -statevector simulations, and so on), while `Sampler` normalizes its `SamplerResult` to +statevector simulations, and so on), while `Sampler` normalizes its `SamplerResult` to return a [`qiskit.result.QuasiDistribution`](../qiskit/qiskit.result.QuasiDistribution) object with the resulting quasi-probability distribution. The `Estimator` provides a specific abstraction for the expectation value calculation that can replace diff --git a/docs/api/migration-guides/qiskit-runtime-examples.mdx b/docs/api/migration-guides/qiskit-runtime-examples.mdx index 86c049bb62d..18f2e913faf 100644 --- a/docs/api/migration-guides/qiskit-runtime-examples.mdx +++ b/docs/api/migration-guides/qiskit-runtime-examples.mdx @@ -225,8 +225,8 @@ Output -The legacy workflow required additional elements and steps to compute an expectation value. The `QuantumInstance` class stored a `PassManager` and a `Backend` instance, and wrapped the conversion step to ISA circuits and `backend.run` calls. The `CircuitSampler` class from `qiskit.opflow` wrapped the `QuantumInstance`, `run`, and `transpile` methods. This degree of nesting is no longer supported; the new workflow allows to access and directly manipulate all the key components of the computation (backend, pass manager, circuits and observables) at all stages of the algorithm. +The legacy workflow required additional elements and steps to compute an expectation value. The `QuantumInstance` class stored a `PassManager` and a `Backend` instance, and wrapped the conversion step to ISA circuits and `backend.run` calls. The `CircuitSampler` class from `qiskit.opflow` wrapped the `QuantumInstance`, `run`, and `transpile` methods. This degree of nesting is no longer supported; the new workflow allows to access and directly manipulate all the key components of the computation (backend, pass manager, circuits and observables) at all stages of the algorithm. ``` python from qiskit.opflow import StateFn, PauliExpectation, CircuitSampler diff --git a/docs/api/migration-guides/qiskit-runtime-options.mdx b/docs/api/migration-guides/qiskit-runtime-options.mdx index 9af6adb90c8..d990b5d8fc8 100644 --- a/docs/api/migration-guides/qiskit-runtime-options.mdx +++ b/docs/api/migration-guides/qiskit-runtime-options.mdx @@ -8,7 +8,7 @@ in_page_toc_max_heading_level: 2 # Migrate options -All `backend.run` options are now available through the Qiskit Runtime primitives, but there are additional options available with the V2 primitives. See the [API reference](/api/qiskit-ibm-runtime/options) for the full list of available options. See [End-to-end examples](qiskit-runtime-examples) and [Advanced Qiskit Runtime options](/guides/runtime-options-overview) for more information about specifying V2 primitives options. +All `backend.run` options are now available through the Qiskit Runtime primitives, but there are additional options available with the V2 primitives. See the [API reference](/api/qiskit-ibm-runtime/options) for the full list of available options. See [End-to-end examples](qiskit-runtime-examples) and [Advanced Qiskit Runtime options](/guides/runtime-options-overview) for more information about specifying V2 primitives options. | backend.run options | V2 Primitive options | Notes | |---------------------|-----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| diff --git a/docs/api/migration-guides/qiskit-runtime-use-case.mdx b/docs/api/migration-guides/qiskit-runtime-use-case.mdx index 7f4139944c2..7eab850ad67 100644 --- a/docs/api/migration-guides/qiskit-runtime-use-case.mdx +++ b/docs/api/migration-guides/qiskit-runtime-use-case.mdx @@ -7,7 +7,7 @@ description: Common use cases when migrating from backend.run to Qiskit Runtime This topic describes how to migrate programs with the most commonly used types of circuits. For a full example, see [End-to-end examples.](qiskit-runtime-examples) ## Basic circuits -The only changes when running basic circuits are how you run the job and retrieve results. +The only changes when running basic circuits are how you run the job and retrieve results. @@ -80,7 +80,7 @@ To migrate programs that run dynamic circuits, change the run call. - ```python + ```python from qiskit_ibm_runtime import SamplerV2 as Sampler sampler = Sampler(backend) @@ -92,7 +92,7 @@ print(f">>> Hardware counts: {pub_result.data.meas.get_counts()}") - ```python + ```python job = backend.run(dynamic_circ, dynamic=True) job.job_id() @@ -154,7 +154,7 @@ theta_values = [np.pi/2, np.pi/2, np.pi/2] -Only circuits that adhere to the Instruction Set Architecture (ISA) of a specific backend are accepted, so we must transform the circuits. +Only circuits that adhere to the Instruction Set Architecture (ISA) of a specific backend are accepted, so we must transform the circuits. ```python from qiskit_ibm_runtime import QiskitRuntimeService @@ -185,7 +185,7 @@ job = sampler.run([(isa_circuit, theta_values)]) result = job.result() # Get results for the first (and only) PUB pub_result = result[0] -# Get counts from the classical register "c". +# Get counts from the classical register "c". print(f" >> Counts for the c output register: {pub_result.data.c.get_counts()}") ``` @@ -232,7 +232,7 @@ pm = generate_preset_pass_manager(backend=backend, optimization_level=1) isa_circuit = pm.run(circuit) sampler = Sampler(backend) -# Get the averaged IQ data. +# Get the averaged IQ data. # This is equivalent to meas_level=1, meas_return="avg" in backend.run sampler.options.execution.meas_type = "avg_kerneled" job = sampler.run([isa_circuit], shots=10) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index c2bf639e3e1..642a04a387b 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -302,7 +302,7 @@ "title": "Configure runtime options", "children": [ { - "title": "Configure runtime compilation", + "title": "Configure error suppression", "url": "/guides/configure-error-suppression" }, { diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index d34410e7b77..07316d8a89c 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -35,22 +35,11 @@ which levels and corresponding methods are available for each of the primitives. -Error mitigation is task specific so the techniques you are able to +Error mitigation is task specific, so the techniques you are able to apply vary based whether you are sampling a distribution or generating expectation values. - -To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives. See the [transpilation documentation](./transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set `optimization_level=0`. - -*Exception*: When you initialize the Qiskit Runtime Service with the Q-CTRL channel strategy (example below), abstract circuits are still supported. - -``` python -service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl") -``` - - - @@ -100,7 +89,7 @@ applied at each resilience level. ## Configure Estimator V2 with resilience levels -You can use resilience levels to specify error mitigation techniques, or you can set custom techniques individually as described in [Custom error settings with Estimator V2.](#advanced-error) You cannot specify resilience levels in Sampler V2. However, you can set custom techniques individually. +You can use resilience levels to specify error mitigation techniques, or you can set custom techniques individually as described in [Custom error settings (V2 primitives).](#advanced-error) You cannot specify resilience levels in Sampler V2. However, you can set custom techniques individually.
Resilience Level 0 @@ -139,7 +128,7 @@ stage). This approach tends to reduce errors in expectation values, but is not guaranteed to produce an unbiased result. -![This image shows a graph. The x-axis is labeled Noise amplification factor. The y-axis is labeled Expectation value. An upward sloping line is labeled Mitigated value. Points near the line are noise-amplified values. There is a horizontal line just above the X-axis labeled Exact value. ](/images/optimize/resilience-2.png "Illustration of the ZNE method") +![This image shows a graph. The x-axis is labeled Noise amplification factor. The y-axis is labeled Expectation value. An upward sloping line is labeled Mitigated value. Points near the line are noise-amplified values. There is a horizontal line just above the X-axis labeled Exact value.](/images/optimize/resilience-2.svg "Illustration of the ZNE method") The overhead of this method scales with the number of noise factors. The default settings sample the expectation value at three noise factors, @@ -172,7 +161,7 @@ estimator = Estimator(backend, options={"resilience_level": 2}) -As you increase the resilience level, you will be able to use additional methods to improve the accuracy of your result. However, because the methods become more advanced with each level, they require additional sampling overhead (time) to generate more accurate expectation values. Note that higher resilience levels do not guarantee better quality. Higher levels only mean greater overhead. Each method has its strengths and weaknesses. For example, TREX (Twirled Readout Error eXtinction) is good for shallow circuits because of its readout error mitigation, whereas ZNE (Zero Noise Extrapolation) is good for deeper circuits. PEC can mitigate arbitrary errors but may not work in practice because of its large overhead. +As you increase the resilience level, you can use additional methods to improve the accuracy of your result. However, because the methods become more advanced with each level, they require additional sampling overhead (time) to generate more accurate expectation values. Note that higher resilience levels do not guarantee better quality. Higher levels only mean greater overhead. Each method has its strengths and weaknesses. For example, TREX (Twirled Readout Error eXtinction) is good for shallow circuits because of its readout error mitigation, whereas ZNE (Zero Noise Extrapolation) is good for deeper circuits. PEC can mitigate arbitrary errors but might not work in practice because of its large overhead. ## Configure Estimator (V1) with resilience levels @@ -217,7 +206,7 @@ stage). This approach tends to reduce errors in expectation values, but is not guaranteed to produce an unbiased result. -![This image shows a graph. The x-axis is labeled Noise amplification factor. The y-axis is labeled Expectation value. An upward sloping line is labeled Mitigated value. Points near the line are noise-amplified values. There is a horizontal line just above the X-axis labeled Exact value. ](/images/optimize/resilience-2.png "Illustration of the ZNE method") +![This image shows a graph. The x-axis is labeled Noise amplification factor. The y-axis is labeled Expectation value. An upward sloping line is labeled Mitigated value. Points near the line are noise-amplified values. There is a horizontal line just above the X-axis labeled Exact value.](/images/optimize/resilience-2.svg "Illustration of the ZNE method") The overhead of this method scales with the number of noise factors. The default settings sample the expectation value at three noise factors, @@ -320,7 +309,7 @@ problems. ### Example -The Estimator interface lets users seamlessly work with the variety of +The Estimator interface lets you seamlessly work with the variety of error mitigation methods to reduce error in expectation values of observables. The following code uses Zero Noise Extrapolation by simply setting `resilience_level=2`. @@ -471,32 +460,9 @@ job = estimator.run(circuits=[psi1], observables=[H1], parameter_values=[theta1] psi1_H1 = job.result() ``` - -## Turn off all error mitigation and error suppression - -You can turn off all error mitigation and suppression if you are, for example, doing research on your own mitigation techniques. To accomplish this, for EstimatorV2, set `resilience_level = 0`. For SamplerV2, no changes are necessary because no error mitigation or suppression options are enabled by default. - -Example: +## Turn off all error mitigation -Turn off all error mitigation and suppression in EstimatorV2. - -```python -from qiskit_ibm_runtime import EstimatorV2 as Estimator, Options, QiskitRuntimeService - -# Define the service. This allows you to access IBM Quantum systems. -service = QiskitRuntimeService() - -# Get a backend -backend = service.least_busy(operational=True, simulator=False) - -# Define Estimator -estimator = Estimator(backend) - -options = estimator.options - -# Turn off all error mitigation and suppression -options.resilience_level = 0 -``` +For instructions to turn off all error mitigation, see the [Turn off all error suppression and mitigation](runtime-options-overview#no-error-mitigation) section. ## Next steps diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index 3b490c3bf7c..c84d99d5caf 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -1,13 +1,15 @@ --- -title: Configure runtime compilation -description: How to configure runtime compilation in Qiskit Runtime. +title: Configure error suppression +description: How to configure error suppression in Qiskit Runtime. (Previous topic - runtime compilation) --- -# Configure runtime compilation for Qiskit Runtime +# Configure error suppression for Qiskit Runtime Runtime compilation techniques transform your circuit to minimize errors. Runtime compilation adds some classical pre-processing overhead to your overall runtime. Therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time. +Primitives let you employ runtime compilation by choosing advanced runtime compilation options. If you don't want any processing done to minimize errors, follow the instructions in the [Turn off all error mitigation and error suppression](runtime-options-overview#no-error-mitigation) section. + To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives. See the [transpilation documentation](./transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set `optimization_level=0`. @@ -126,11 +128,11 @@ psi1_H1 = job.result() -## Advanced runtime compilation options +## Advanced error suppression options - In the V2 primitives, you can explicitly enable and disable individual error mitigation/suppression methods, such as dynamical decoupling. + In the V2 primitives, you can explicitly enable and disable individual error mitigation and suppression methods, such as dynamical decoupling. Dynamical decoupling is not supported when the input circuits are dynamic. @@ -154,15 +156,18 @@ print(f">>> dynamical decoupling sequence to use: {sampler.options.dynamical_dec - Because all input must be ISA, options.transpilation.xxx will be ignored. + Because all input must be ISA, `options.transpilation.xxx` is ignored. See [Advanced runtime options](runtime-options-overview) for information. +## Turn off all error suppression + +For instructions to turn off all error suppression, see the [Turn off all error suppression and mitigation](runtime-options-overview#no-error-mitigation) section. ## Next steps - Try a tutorial that uses optimization levels, such as the [Variational quantum eigensolver](https://learning.quantum.ibm.com/tutorial/variational-quantum-eigensolver) tutorial. - - Learn how to transpile locally in the [Transpile](./transpile) section. + - Learn how to transpile locally in the [Transpile](./transpile/) section. - Try the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial. \ No newline at end of file diff --git a/docs/guides/get-started-with-primitives.mdx b/docs/guides/get-started-with-primitives.mdx index b79d69d4300..fc85c0d9d6c 100644 --- a/docs/guides/get-started-with-primitives.mdx +++ b/docs/guides/get-started-with-primitives.mdx @@ -9,7 +9,7 @@ description: How to use the Estimator and Sampler primitives in Qiskit Runtime. The steps in this topic describes how to set up primitives, explore the options you can use to configure them, and invoke them in a program. -To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives. See the [transpilation documentation](transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all primitives except Sampler V2 still optimize the input circuits. To bypass all optimization, set `optimization_level=0`. +To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives. See the [transpilation documentation](./transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set `optimization_level=0`. *Exception*: When you initialize the Qiskit Runtime Service with the Q-CTRL channel strategy (example below), abstract circuits are still supported. @@ -63,7 +63,7 @@ Output ```text >>> Observable: ['ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ...'] ``` - The circuit and observable need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits). We'll use the transpiler to do this. + The circuit and observable need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits). The following code uses the transpiler to do this. ```python pm = generate_preset_pass_manager(optimization_level=1, backend=backend) @@ -179,7 +179,7 @@ circuit = IQP(mat) circuit.measure_all() ``` -Again, we use the transpiler to get an ISA circuit. +Use the transpiler to get an ISA circuit. ```python pm = generate_preset_pass_manager(optimization_level=1, backend=backend) @@ -297,4 +297,6 @@ sampler = BackendSampler(backend) - Practice with primitives by working through the [Cost function lesson](https://learning.quantum.ibm.com/course/variational-algorithm-design/cost-functions#primitives) in IBM Quantum Learning. - Learn how to transpile locally in the [Transpile](transpile/) section. - Try the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial. + - Learn how to [use the primitive options.](runtime-options-overview) + - View the API for [Sampler](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions) and [Estimator](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) options. diff --git a/docs/guides/primitives.mdx b/docs/guides/primitives.mdx index db3fba855ff..c58c0820212 100644 --- a/docs/guides/primitives.mdx +++ b/docs/guides/primitives.mdx @@ -6,7 +6,7 @@ description: Introduction to primitives in Qiskit and Qiskit Runtime, and an exp # Introduction to primitives -Computing systems are built on multiple layers of abstraction. Abstractions allow to focus on a +Computing systems are built on multiple layers of abstraction. Abstractions allow you to focus on a particular level of detail relevant to the task at hand. The closer you get to the hardware, the lower the level of abstraction you need (for example, you might want to manipulate electrical signals), and vice versa. The more complex the task you want to perform, @@ -17,7 +17,7 @@ In this context, a *primitive* is the smallest processing instruction, the simpl one can create something useful for a given abstraction level. The recent progress in quantum computing has increased the need to work at higher levels of abstraction. -As we move toward larger systems and more complex workflows, the focus shifts from interacting with individual +With the movement toward larger systems and more complex workflows, the focus shifts from interacting with individual qubit signals to viewing quantum devices as systems that perform tasks we need. The two most common tasks quantum computers are used for are sampling quantum states and calculating expectation values. @@ -52,7 +52,7 @@ service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl") ## Benefits of Qiskit primitives For Qiskit users, primitives let you write quantum code for a specific system without having to explicitly -manage every detail. In addition, because of the additional layer of abstraction, you might be able to more easily +manage every detail. Also, because of the additional layer of abstraction, you might be able to more easily access advanced hardware capabilities of a given provider. For example, with Qiskit Runtime primitives, you can leverage the latest advancements in error mitigation and suppression by toggling options such as `resilience_level`, rather than building your own implementation of these techniques. @@ -62,13 +62,13 @@ best capabilities. ## V2 primitives -Version 2 (available with qiskit-ibm-runtime 0.21.0) is the first major interface change since the introduction of Qiskit Runtime primitives. Based on user feedback, the new version introduces the following major changes: +Version 2 (available with `qiskit-ibm-runtime` 0.21.0 and later) is the first major interface change since the introduction of Qiskit Runtime primitives. Based on user feedback, the new version introduces the following major changes: * The **new interface** lets you specify a single circuit and multiple observables (if using Estimator) and parameter value sets for that circuit. * You can **turn on or off individual error mitigation and suppression methods**. * You can choose to **get counts or per-shot measurements** instead of quasi-probabilities from Sampler V2. * Due to scaling issues, Sampler V2 does not support specifying a resilience level, and Estimator V2 supports only levels 0 - 2. -* To reduce the total execution time, V2 primitives only support ISA circuits. You can use the [Qiskit transpiler](runtime-options-overview#runtime-compilation) (manually) or the [AI-driven transpilation service (premium users)](qiskit-transpiler-service) to transform the circuits before making the queries to the primitives. +* To reduce the total execution time, v2 primitives only support ISA circuits. You can use the [Qiskit transpiler](./transpile) (manually) or the [AI-driven transpilation service (premium users)](./qiskit-transpiler-service) to transform the circuits before making the queries to the primitives. See the [EstimatorV2 API reference](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.EstimatorV2) and [SamplerV2 API reference](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.SamplerV2) for full details. diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index b9394203b31..92dfd5883ad 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -6,7 +6,8 @@ description: Specify options when building with Qiskit Runtime primitives # Advanced Qiskit Runtime options -When calling the primitives, you can pass in options by using an options class or a dictionary. In the options classes, commonly used options, such as `resilience_level`, are at the first level. Other options are grouped into different categories, such as `execution`. See the [options classes section](#options-classes) for details. + You can pass options to primitives to customize them to meet your needs. This section focuses on Qiskit Runtime primitive options. While the interface of the primitives' `run()` method is common across all implementations, their options are not. Consult the corresponding API references for information about the [`qiskit.primitives`](/api/qiskit/primitives#primitives) and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) options. + To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives. See the [transpilation documentation](./transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set `optimization_level=0`. @@ -18,11 +19,294 @@ service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl") ``` - - This section focuses on Qiskit Runtime primitive options. While most of the `primitives` interface is common across implementations, most options are not. Consult the - corresponding API references for information about the `qiskit.primitives` and `qiskit_aer.primitives` options. +## Overview + + +### Structure + +When calling the primitives, you can pass in options by using an options class or a dictionary. In the options classes, commonly used options, such as `resilience_level`, are at the first level. Other options are grouped into different categories, such as `execution`. See the [Set primitive options](#pass-options) section for full details. + + +### Defaults + +For V2 primitives, if you do not specify a value for an option, it is given a special value of `Unset` and the server default value is used. Thus, the default value will be the same regardless of your code version. +For V1 primitives, if you do not specify a value for an option, the Qiskit Runtime client's default value is used. In V1, the default value is dependant on the code version. + +The tables in the [Options classes summary](#options-classes) section lists the default values. + + +### Precedence rules + +There are several ways to set options. If you set different values for the same option in multiple places, this is the order of precedence: + +1. Any options set after primitive initialization. +2. Any options set during primitive initialization. + + +Shots (Sampler) or precision (Estimator) set in `run()` are not considered options, but take precidence over values set for `default_shots`or `default_precision`. See the [Run() method](#run-method) section for full details. + + +In the following example, these values would be used for the `estimator.run` job: `shots = 128` and `optimization_level = 1`. + +``` python +# Setting options during primitive initialization +estimator = Estimator(backend, options={"optimization_level": 0}) + +# Setting options after primitive initialization +# This uses auto complete. +estimator.options.optimization_level = 1 +estimator.options.default_shots = 4000 + +# Sample two circuits at 128 shots each. +estimator.run([circuit1, circuit2], shots=128) +``` + +#### Special cases + +The `default_shots` and `resilience_level` options require special consideration: + +If you set `default_shots` in an estimator, it overrides any value set for `default_precision`. + +The `resilience_level` is used to set a base configuration on any relevant options, and then any other user-specified options override that configuration. So it would be possible to undo the effect of setting the resilience level by reversing all of its settings manually. + +In the following example, setting the resilience level to 0 does not turn off `zne_mitigation` because `estimator.options.resilience.zne_mitigation = True` overrides the relevent setup from `estimator.options.resilience_level = 0`. + +``` python +from qiskit_ibm_runtime import EstimatorV2, QiskitRuntimeService +from qiskit import QuantumCircuit + +service = QiskitRuntimeService() +backend = service.backend("ibm_auckland") + +estimator = EstimatorV2(backend) + +estimator.options.default_shots = 100 +estimator.options.resilience_level = 0 +estimator.options.resilience.zne_mitigation = True +``` + + +## Options classes summary + + + + - [Resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2): Advanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC. Estimator only. + - [Dynamical decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions): Options for dynamical decoupling. + - [Execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2): Primitive execution options, including whether to initialize qubits and the repetition delay. + - [Twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions): Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. + - [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions): Execution environment options such as the logging level to set and job tags to add. + - [Simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions): Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to local testing mode only. + + + + - [Dynamical decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions): Options for dynamical decoupling. + - [Execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2): Primitive execution options, including whether to initialize qubits and the repetition delay. + - [Twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions): Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. + - [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions): Execution environment options such as the logging level to set and job tags to add. + - [Simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions): Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to **local testing mode only**. + + + + - [Resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptions): Advanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC. **Estimator only**. + - [Dynamical decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions): Options for dynamical decoupling. + - [Execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptions): Primitive execution options, including whether to initialize qubits and the repetition delay. + - [Twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions): Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. + - [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions): Execution environment options such as the logging level to set and job tags to add. + - [Simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions): Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to **local testing mode only**. + + + + + +### Available options + + +Scroll to see the full table. + + +| Options | Sub-options | Sub-sub-options | Choices | Default | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| [default_shots](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | Integer in the range[0, `backend.max_shots`] | None | +| [default_precision](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | float > 0 | `0.015625 (1 / sqrt(4096))` | +| [dynamical_decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions) | | | | | +| | enable | | `True`/`False` | `False` | +| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | +| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | +| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | +| [environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | | | | | +| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | +| | callback | |Callable function that receives Job ID and Job result. |`None` | +| | job_tags | |List of tags |`None` | +| [execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptions) | | | | | +| | init_qubits | | `True`/`False` | `True` | +| | rep_delay | | Value in the range supplied by `backend.rep_delay_range`. | Given by `backend.default_rep_delay`.| +| [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | +| [optimization_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | `0`/`1` | `1` | +| [resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptions) | | | | | +| | LayerNoiseLearning | | `True`/`False` | `True` | +| | | max_layers_to_learn | `None`/ integer >= 1 | `4` | +| | | shots_per_randomization | integer >= 1 | `128` | +| | | num_randomizations | integer >= 1 | `32` | +| | | layer_pair_depths | list[int] of 2-10 values in the range [0, 200] | `(0, 1, 2, 4, 16, 32)` | +| | measure_mitigation | | `True`/`False` | `True` | +| | measure_noise_learning | num_randomizations | integer >= 1 | `32` | +| | | shots_per_randomization | integer | 'auto' | +| | pec | max_overhead | `None`/ integer >1 | `100` | +| | | noise_gain | `auto`/ float in the range `[0, 1]` | `auto` | +| | pec_mitigation | | `True`/`False` | `False` | +| | zne_mitigation | | `True`/`False` | `False` | +| | zne | noise_factors | list of floats; each float >= 1 | `(1, 3, 5)` | +| | | amplifier | `gate_folding`, `gate_folding_front`, `gate_folding_back ` | `gate_folding` | +| | | extrapolator | one or more of `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | +| [resilience_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | `0`/`1`/`2` | `1` | +| [seed_estimator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | integer | `None` | +| [simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | | | | | +| | noise_model | | [Qiskit Aer NoiseModel](build-noise-models), or its representation | `None` | +| | seed_simulator | | integer | `None` | +| | coupling_map | | List of directed two-qubit interactions | full connectivity | +| | basis_gates | | List of basis gate names to unroll to | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | +| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | | | | | +| | enable_gates | | `True`/`False` | `False` | +| | enable_measure | | `True`/`False` | `True` | +| | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | +| | shots_per_randomization | | `auto`/ Integer no larger than `backend.max_shots`. | `'auto'` | +| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | + + + +| Options | Sub-options | Sub-sub-options | Choices | Default | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| [default_shots](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions) | | | Integer in the range[0, `backend.max_shots`] | `4096` | +| [dynamical_decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions) | | | | | +| | enable | | `True`/`False` | `False` | +| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | +| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | +| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | +| [environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | | | | | +| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | +| | callback | |Callable function that receives Job ID and Job result. |`None` | +| | job_tags | |List of tags |`None` | +| [execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2) | | | | | +| | init_qubits | | `True`/`False` | `True` | +| | rep_delay | | Value in the range supplied by `backend.rep_delay_range`. | Given by `backend.default_rep_delay`.| +| [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | +| [simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | | | | | +| | noise_model | | [Qiskit Aer NoiseModel](build-noise-models), or its representation | `None` | +| | seed_simulator | | integer | `None` | +| | coupling_map | | List of directed two-qubit interactions | full connectivity | +| | basis_gates | | List of basis gate names to unroll to | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | +| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | | | | | +| | enable_gates | | `True`/`False` | `False` | +| | enable_measure | | `True`/`False` | `True` | +| | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | +| | shots_per_randomization | | `auto`/ Integer no larger than `backend.max_shots`. | `'auto'` | +| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | + + + + +| Options | Sub-options | Sub-sub-options | Choices | Default | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| [optimization_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | `0`/`1` | `1` | +| [resilience_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | `0`/`1`/`2` | `1` | +| [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | +| [resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptions) | | | | | +| | extrapolator | | `LinearExtrapolator`/`QuadraticExtrapolator`/`CubicExtrapolator`/`QuarticExtrapolator` | `None`, or `LinearExtrapolator` if `resilience_level=2`. | +| | noise_amplifier | | | | +| | noise_factors | | Applies only for `resilience_level=2`. List of real valued noise factors. | `(1, 3, 5)` | +| [transpilation](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TranspilationOptions) | | | | | +| | skip_transpilation | | `True`/`False` | `False` | +| | initial_layout | | layout instance, dictionary, list, or None. See [qiskit.compiler.](../api/qiskit/compiler#transpile) | `None` | +| | layout_method | | `trivial`/`dense`/`noise_adaptive`/`sabre`/`none` | `None` | +| | routing_method | | `Basic`/`lookahead`/`stochastic`/`none` | | `None` +| | approximation_degree | | Float in the range 0 - 1 / `None` | `None` | +| [execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptions) | | | | | +| | init_qubits | | `True`/`False` | `True` | +| | shots | | Integer no larger than `backend.max_shots`. | 4000| +| [environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | | | | | +| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | +| | callback | |Callable function that receives Job ID and Job result. |`None` | +| | job_tags | |List of tags |`None` | +| [simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | | | | | +| | noise_model | | [Qiskit Aer NoiseModel](build-noise-models), or its representation | `None` | +| | seed_simulator | | integer | `None` | +| | coupling_map | | List of directed two-qubit interactions | full connectivity | +| | basis_gates | | List of basis gate names to unroll to | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | + + + + + + + + + +### Options compatibility + +Due to differences in the device compilation process, certain runtime features cannot be used together in a single job. Click the appropriate tab for a list of features that are incompatible with the selected feature: + + + + Incompatible with: + - Gate-folding ZNE + - PEA + - PEC + - Dynamical decoupling + - Pulse gates + + Can be used with gate twirling for non-conditional gates. + + + + Incompatible with: + - Dynamic circuits + - PEA + - PEC + + Can be used with pulse gates, but it might not work when using custom gates. + + + + Incompatible with: + - Dynamic circuits + - Gate-folding ZNE + - PEC + - Pulse gates + + + + Incompatible with: + - Dynamic circuits + - Gate-folding ZNE + - PEA + - Pulse gates + + + Incompatible with dynamic circuits. + + + + Incompatible with: + - Dynamic circuits + - PEA + - PEC + - Dynamical decoupling + + Other notes: + - Can be used with gate-folding ZNE, but it might not work with custom gates. + - Can be used with gate twirling, but it does not work with non-Clifford entanglers. + + + Compatible with all other features, with the following conditions: + - Can be used with dynamic circuits with non-conditional gates. + - Can be used with pulse gates, but it does not work with non-Clifford entanglers. + + + + + ## V2 changes Options are specified differently in the V2 primitives in these ways: @@ -50,18 +334,23 @@ options = Options() options.resilience_level = 1 options.execution.shots = 2048 ``` -## Pass options to a primitive + +## Set primitive options + +You can set options in an options class, when initializing the primitive, or both. ### Options class -When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Example: +When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Specify the options in this format: `primitive.options.option.sub-option.sub-sub-option = choice`. For example: `estimator.options.dynamical_decoupling.enable = True` + +Example: `SamplerV2` and `EstimatorV2` have separate options classes that do not need to be instantiated. You can see the available options and update option values during or after primitive initialization. Those options will then be applied when you use `run()` to perform the calculation. Example: ```python -estimator = Estimator(mode=backend) +estimator = Estimator(backend=backend) # Setting options after primitive initialization # This uses auto complete. @@ -73,7 +362,7 @@ estimator.options.default_shots = 4000 When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Example: ```python -estimator = Estimator(backend=backend, options=options) +estimator = Estimator(session=backend, options=options) result = estimator.run(circuit, observable).result() print(f">>> Metadata: {result.metadata[0]}") ``` @@ -113,13 +402,15 @@ estimator = Estimator(backend, options={"resilience_level": 2}) + ### Run() method -You can pass in options by using the `run()` method. This overwrites the options you specified when creating the `Estimator` or `Sampler` instance for that particular execution. +The run() method accepts options in V1 only. -In V2, the only options you can pass to `run()` are options defined in the interface. That is, `shots` for Sampler and `precision` for Estimator. +In V2, the only values you can pass to `run()` are those defined in the interface. That is, `shots` for Sampler and `precision` for Estimator. This overwrites any value set for `default_shots` or `default_precision` for the current run. + ```python # Sample two circuits at 128 shots each. sampler.run([circuit1, circuit2], shots=128) @@ -130,7 +421,7 @@ sampler.run([circuit1, circuit2], shots=128) You can pass any options to `run()`. Because most users will only overwrite a few options at the job level, it is not necessary to specify the options category. The code below, for example, specifies `shots=1024` instead of `execution={"shots": 1024}` (which is also valid). ```python -estimator = Estimator(backend=backend, options=options) +estimator = Estimator(session=backend, options=options) result = estimator.run(circuit, observable, shots=1024).result() print(f">>> Metadata: {result.metadata[0]}") ``` @@ -147,7 +438,24 @@ For some algorithms, setting a specific number of shots is a core part of their - ```python +Shots (or precision) can be specified in multiple places in V2. They are prioritized as follows: + +For any Sampler pub: + +1. Int-valued shots contained in the pub +2. The `run(...,shots=val)` value +3. The `options.default_shots` value + +For any Estimator pub: + +1. Float-valued precision contained in the pub +2. The `run(...,precision=val)` value +3. The `options.default_shots` value +4. The `options.default_precision` value + +Example: + +```python from qiskit_ibm_runtime import SamplerV2 as Sampler # Setting shots during primitive initialization @@ -162,7 +470,7 @@ sampler.options.update(default_shots=1024, dynamical_decoupling={"sequence_type" # Sample two circuits at 128 shots each. sampler.run([circuit1, circuit2], shots=128) -``` + ``` @@ -175,7 +483,7 @@ from qiskit_ibm_runtime import Estimator, Options options = Options() options.execution.shots = 1024 -estimator = Estimator(backend=backend, options=options) +estimator = Estimator(session=backend, options=options) ``` If you need to modify the number of shots set between iterations (primitive calls), you can set the @@ -184,7 +492,7 @@ shots directly in the `run()` method. This overwrites the initial `shots` settin ```python from qiskit_ibm_runtime import Estimator -estimator = Estimator(backend=backend) +estimator = Estimator(session=backend) estimator.run(circuits=circuits, observables=observables, shots=50) @@ -199,14 +507,12 @@ For more information about the primitive options, refer to the +### Error suppression +The Qiskit Runtime primitives must be called with circuits already suitable for execution on the target system. This implies that the user has already transpiled the circuits to respect the native gate set and connectivity constraints of the target system. -### Runtime compilation - -The Qiskit Runtime primitives expect to be called with circuits already suitable for execution on the target system. This implies that the user has already transpiled their circuits to respect the native gate set and connectivity constraints of the target system. - -In the V2 primitives, you can explicitly enable and disable individual error mitigation/suppression methods, such as dynamical decoupling. For an example, see the -[Runtime compilation topic](configure-error-suppression#transpilation-table). +In the V2 primitives, you can explicitly enable and disable individual error mitigation and suppression methods, such as dynamical decoupling. For an example, see the +[Error suppression topic](configure-error-suppression#transpilation-table). In the V1 Qiskit Runtime primitives, optimization levels 2 and 3 behave identically to level 1. If you want to use more advanced optimization, use the Qiskit transpiler locally, set [`skip_transpilation=True`](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TranspilationOptions#skip_transpilation), and then pass the transpiled circuits to the primitives. For instructions see the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial. @@ -223,22 +529,11 @@ options = Options(optimization_level=1) options = Options() options.optimization_level = 1 -estimator = Estimator(backend=backend, options=options) -``` - -Turning off all optional runtime compilation steps requires a "second-level option", as follows: - -```python -from qiskit_ibm_runtime import Estimator, Options - -options = Options() -options.transpilation.skip_transpilation = True - -estimator = Estimator(backend=backend, options=options) +estimator = Estimator(session=backend, options=options) ``` For more information and a complete list of advanced transpilation options, see the Advanced transpilation options table in the -[Runtime compilation topic](./configure-error-suppression#transpilation-table). +[Configure error suppression topic](configure-error-suppression#transpilation-table). ### Error mitigation @@ -252,7 +547,7 @@ algorithm. These methods can be set through the `resilience_level` option. For With Estimator V2, you can set resilience levels 0-2 and you can also turn on and off various error mitigation settings for fine-tuning. ```python -estimator = Estimator(mode=backend) +estimator = Estimator(backend=backend) estimator.options.resilience_level = 2 estimator.options.resilience.zne_mitigation = True @@ -276,22 +571,39 @@ options = Options(resilience_level = 2) options = Options() options.resilience_level = 2 -estimator = Estimator(backend=backend, options=options) +estimator = Estimator(session=backend, options=options) ``` - -## Options classes + +## Turn off all error mitigation and error suppression + +You can turn off all error mitigation and suppression if you are, for example, doing research on your own mitigation techniques. To accomplish this, for EstimatorV2, set `resilience_level = 0` and `optimization_level = 0`. For SamplerV2, no changes are necessary because no error mitigation or suppression options are enabled by default. + +Example: + +Turn off all error mitigation and suppression in EstimatorV2. + +```python +from qiskit_ibm_runtime import EstimatorV2 as Estimator, Options, QiskitRuntimeService + +# Define the service. This allows you to access IBM Quantum systems. +service = QiskitRuntimeService() + +# Get a backend +backend = service.least_busy(operational=True, simulator=False) + +# Define Estimator +estimator = Estimator(backend) + +options = estimator.options + +# Turn off all error mitigation and suppression +options.resilience_level = 0 +options.optimization_level = 0 +``` -| Category | Description | Example | -|:-------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------:|:------------------------------------------------------| -| [Resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2) | Advanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC. Estimator only. | `estimator.options.resilience.measure_mitigation = True` | -| [Dynamical decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions) | Options for dynamical decoupling. | `estimator.options.dynamical_decoupling.enable = True` | -| [Execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2) | Primitive execution options, including whether to initialize qubits and the repetition delay. | `estimator.options.execution.init_qubits = False` | -| [Twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. | `estimator.options.twirling.enable_gates = True` | -| [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | Execution environment options such as the logging level to set and job tags to add. | `estimator.options.environment.log_level = 'ERROR'` | -| [Simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to local testing mode only. | `estimator.options.simulator.seed_simulator = 42` | ## Next steps @@ -299,7 +611,7 @@ estimator = Estimator(backend=backend, options=options) - Find more details about the `Estimator` methods in the [Estimator API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.Estimator#estimator). - Find more details about the `Sampler` methods in the [Sampler API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.Sampler#sampler). - Find all available options in the [Options API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options). - - Find details about [runtime compilation](./configure-error-suppression) and [error mitigation](configure-error-mitigation). - - Learn how to transpile locally in the [Transpile](./transpile) section. + - Find details about how to configure [error suppression](configure-error-suppression) and [error mitigation](configure-error-mitigation). + - Learn how to transpile locally in the [Transpile](./transpile/) section. - Try the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial. - + \ No newline at end of file diff --git a/public/images/optimize/resilience-2.psd b/public/images/optimize/resilience-2.psd new file mode 100644 index 0000000000000000000000000000000000000000..311d9d1c14e2ff33bd58a64deeef1bd45e33b53f GIT binary patch literal 399862 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

UB)DYHiIT?|(6hWTEQVk)VwSx0K}Odb zFb)*Wlxe=1c6nft)lUi82I)C^=ea{>XGE}<;%Zkwz}ID)qeCk`R1OY_f(yf6^r^v! z9#M^u!K8ruswq0#fJ=lM33Lu=oq3`bacPsRmwwcCvkLe)PB#m^%P2hij3#jd6gDiB zB86nWR!tw&Di#V&bW!-|!f#f!41g00&5O=6D!zwfiVZhqaTKK$@L-5_fIkTqJc|Qr zNW`g3Jgr%vD)xMo_94hZ=Ze+wC-Qg@MHJ*~@(OsouI<@e>8G2cgiiE^f?##LTA0up zB9q_@q!Kk5twy~OW5Vo3BY|V6grg^Yf}dWRqjc8fC#TnloGkGt$|MM*wAQX5uc8AI z6m6_Vdaf8ECSVqJf%timg&_S_7mS3ra$#&H@QL$5b?hW7uD0X&YRgD zU>d8(1}vkfh%AdDC7ippoZ@*(Iwd0^)PVkdvb-sOu${MlE*Q zblZUNKH(4>ljXp2ZrV!KI9_j{8cOs9z!+0BcEJki3H>-^Huy+^@LKxybpb}jKw@Dv zt!a~Y>jjmvOrm6lv>6@*tFo{Bw+f;#T`l^fgcZrks^LYP7R6GLr{UXfbCBjmkq-k( z>66iF!3iLiw2<=vut8PWH1Av>0(2=68w}|-((zwvqhSL>!G^)AY$N|s)ZO1SuN^s01DPAC38fSX4-`Bt@Xl@4JDO@F0Q8@5Tzxh_{!~P|+(bIs~?? lIOqP2;j7Bg?%zLzr(JwL`uq_GKH|Vf9QcR>{}4FvzX1_&p!fg) literal 0 HcmV?d00001 diff --git a/public/images/optimize/resilience-2.svg b/public/images/optimize/resilience-2.svg new file mode 100644 index 00000000000..efbb2f341df --- /dev/null +++ b/public/images/optimize/resilience-2.svg @@ -0,0 +1,33 @@ + + + + + + Mitigated value + Expectation value + Noise amplification factor + Exact value + Unmitigated value + Noise amplified values + From f122534ec838b0f37fe122b188bd0ebdd5e66115 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 17 Jul 2024 12:41:52 -0500 Subject: [PATCH 02/44] Jessie comments --- docs/guides/_toc.json | 16 ++++++++-------- docs/guides/configure-error-mitigation.mdx | 15 ++++++--------- docs/guides/configure-error-suppression.mdx | 17 ++++++++++------- ...-mitigation-and-suppression-techniques.ipynb | 5 ++++- docs/guides/runtime-options-overview.mdx | 7 +++---- 5 files changed, 31 insertions(+), 29 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 642a04a387b..34a8a6bad2b 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -302,20 +302,20 @@ "title": "Configure runtime options", "children": [ { - "title": "Configure error suppression", - "url": "/guides/configure-error-suppression" + "title": "Introduction to options", + "url": "/guides/runtime-options-overview" }, { - "title": "Configure runtime error mitigation", - "url": "/guides/configure-error-mitigation" + "title": "Error mitigation and suppression techniques", + "url": "/guides/error-mitigation-and-suppression-techniques" }, { - "title": "Advanced runtime options", - "url": "/guides/runtime-options-overview" + "title": "Configure error mitigation", + "url": "/guides/configure-error-mitigation" }, { - "title": "Error mitigation and suppression techniques", - "url": "/guides/error-mitigation-and-suppression-techniques" + "title": "Configure error suppression", + "url": "/guides/configure-error-suppression" } ] } diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 07316d8a89c..7e20bc45f58 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -3,7 +3,7 @@ title: Configure error mitigation description: How to configure error mitigation with Qiskit Runtime. --- -# Configure error mitigation for Qiskit Runtime +# Configure error mitigation Error mitigation techniques allow users to mitigate circuit errors by modeling the device noise at the time of execution. This typically @@ -145,7 +145,7 @@ values](https://arxiv.org/abs/2012.09738). The `Estimator` interface lets users seamlessly work with the variety of error mitigation methods to reduce error in expectation values of -observables. The following code uses Zero Noise Extrapolation by simply +observables. The following code uses Zero Noise Extrapolation and readout error mitigation by simply setting `resilience_level 2`. ```python @@ -159,11 +159,6 @@ backend = service.least_busy(operational=True, simulator=False) estimator = Estimator(backend, options={"resilience_level": 2}) ``` - - -As you increase the resilience level, you can use additional methods to improve the accuracy of your result. However, because the methods become more advanced with each level, they require additional sampling overhead (time) to generate more accurate expectation values. Note that higher resilience levels do not guarantee better quality. Higher levels only mean greater overhead. Each method has its strengths and weaknesses. For example, TREX (Twirled Readout Error eXtinction) is good for shallow circuits because of its readout error mitigation, whereas ZNE (Zero Noise Extrapolation) is good for deeper circuits. PEC can mitigate arbitrary errors but might not work in practice because of its large overhead. - - ## Configure Estimator (V1) with resilience levels @@ -469,6 +464,8 @@ For instructions to turn off all error mitigation, see the [Turn off all error s - Walk through an example that uses error mitigation in the [Cost function lesson](https://learning.quantum.ibm.com/course/variational-algorithm-design/cost-functions#primitives) in IBM Quantum Learning. - Learn more about [Q-CTRL](https://docs.q-ctrl.com/q-ctrl-embedded). - - Learn how to transpile locally in the [Transpile](./transpile/) section. - - Try the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial. + - Learn more about [error mitigation and error suppression techniques.](error-mitigation-and-suppression-techniques) + - [Configure error suppression.](configure-error-suppression) + - Explore other [options.](runtime-options-overview) + - Decide what [execution mode](execution-modes) to run your job in. \ No newline at end of file diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index c84d99d5caf..5fc0a6bef3e 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -4,11 +4,13 @@ description: How to configure error suppression in Qiskit Runtime. (Previous top --- -# Configure error suppression for Qiskit Runtime +# Configure error suppression -Runtime compilation techniques transform your circuit to minimize errors. Runtime compilation adds some classical pre-processing overhead to your overall runtime. Therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time. +Error suppression refers to techniques where you use knowledge about the undesirable effects to introduce customization that can anticipate and avoid the potential impacts of those effects. These techniques often consist of altering or adding control signals to ensure that the quantum processor returns the desired results. This typically results in quantum pre-processing overhead; therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time. -Primitives let you employ runtime compilation by choosing advanced runtime compilation options. If you don't want any processing done to minimize errors, follow the instructions in the [Turn off all error mitigation and error suppression](runtime-options-overview#no-error-mitigation) section. +V2 primitives support a number of error suppression techniques, including dynamical decoupling and Pauli twirling. See Error mitigation and suppression techniques for explanation of each. In V2 primitives, you can turn on or off individual method. See the [Advanced error suppression options](#transpilation-table) section for details. + +Estimator V2 employs error suppression and mitigation by default. If you don't want any processing done to your input circuits follow the instructions in the [Turn off all error mitigation and error suppression](runtime-options-overview#no-error-mitigation) section. To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives. See the [transpilation documentation](./transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set `optimization_level=0`. @@ -132,7 +134,7 @@ psi1_H1 = job.result() - In the V2 primitives, you can explicitly enable and disable individual error mitigation and suppression methods, such as dynamical decoupling. + In the V2 primitives, you can explicitly enable and disable individual error mitigation and suppression methods, such as dynamical decoupling. See [Advanced Qiskit Runtime options](runtime-options-overview) for information about available options. Dynamical decoupling is not supported when the input circuits are dynamic. @@ -167,7 +169,8 @@ For instructions to turn off all error suppression, see the [Turn off all error ## Next steps - - Try a tutorial that uses optimization levels, such as the [Variational quantum eigensolver](https://learning.quantum.ibm.com/tutorial/variational-quantum-eigensolver) tutorial. - - Learn how to transpile locally in the [Transpile](./transpile/) section. - - Try the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial. + - Learn more about [error mitigation and error suppression techniques.](error-mitigation-and-suppression-techniques) + - [Configure error mitigation.](configure-error-mitigation) + - Explore other [options.](runtime-options-overview) + - Decide what [execution mode](execution-modes) to run your job in. \ No newline at end of file diff --git a/docs/guides/error-mitigation-and-suppression-techniques.ipynb b/docs/guides/error-mitigation-and-suppression-techniques.ipynb index bbe1960b35c..8e60d3bdfdf 100644 --- a/docs/guides/error-mitigation-and-suppression-techniques.ipynb +++ b/docs/guides/error-mitigation-and-suppression-techniques.ipynb @@ -256,7 +256,10 @@ "## Next steps\n", "\n", "- Check out the [tutorial](https://learning.quantum.ibm.com/tutorial/combine-error-mitigation-options-with-the-estimator-primitive) on combining error mitigation options with the Estimator primitive.\n", - "- Visit the [API reference](/api/qiskit-ibm-runtime/options) to see all the options for the Qiskit Runtime primitives." + "- [Configure error mitigation.](configure-error-mitigation)\n", + "- [Configure error suppression.](configure-error-suppression)\n", + "- Explore other [options](runtime-options-overview) for the Qiskit Runtime primitives.\n", + "- Decide what [execution mode](execution-modes) to run your job in." ] } ], diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 92dfd5883ad..166fa087346 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -1,10 +1,10 @@ --- -title: Advanced Qiskit Runtime options +title: Introduction to options description: Specify options when building with Qiskit Runtime primitives --- -# Advanced Qiskit Runtime options +# Introduction to options You can pass options to primitives to customize them to meet your needs. This section focuses on Qiskit Runtime primitive options. While the interface of the primitives' `run()` method is common across all implementations, their options are not. Consult the corresponding API references for information about the [`qiskit.primitives`](/api/qiskit/primitives#primitives) and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) options. @@ -612,6 +612,5 @@ options.optimization_level = 0 - Find more details about the `Sampler` methods in the [Sampler API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.Sampler#sampler). - Find all available options in the [Options API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options). - Find details about how to configure [error suppression](configure-error-suppression) and [error mitigation](configure-error-mitigation). - - Learn how to transpile locally in the [Transpile](./transpile/) section. - - Try the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial. + - Decide what [execution mode](execution-modes) to run your job in. \ No newline at end of file From 21f5c170362713eed925bf0a0cfb19db73dbb0ce Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 17 Jul 2024 16:54:38 -0500 Subject: [PATCH 03/44] add another column to the end of the big tables --- docs/guides/runtime-options-overview.mdx | 209 +++++++++++------------ 1 file changed, 103 insertions(+), 106 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 166fa087346..28e12702fad 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -46,15 +46,15 @@ There are several ways to set options. If you set different values for the same Shots (Sampler) or precision (Estimator) set in `run()` are not considered options, but take precidence over values set for `default_shots`or `default_precision`. See the [Run() method](#run-method) section for full details. -In the following example, these values would be used for the `estimator.run` job: `shots = 128` and `optimization_level = 1`. +In the following example, these values would be used for the `estimator.run` job: `shots = 128` and `resilience_level = 1`. ``` python # Setting options during primitive initialization -estimator = Estimator(backend, options={"optimization_level": 0}) +estimator = Estimator(backend, options={'resilience_level': 2,'resilience': {'measure_mitigation': False}}) # Setting options after primitive initialization # This uses auto complete. -estimator.options.optimization_level = 1 +estimator.options.resilience.measure_mitigation = True estimator.options.default_shots = 4000 # Sample two circuits at 128 shots each. @@ -126,114 +126,112 @@ Scroll to see the full table. -| Options | Sub-options | Sub-sub-options | Choices | Default | -|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| [default_shots](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | Integer in the range[0, `backend.max_shots`] | None | -| [default_precision](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | float > 0 | `0.015625 (1 / sqrt(4096))` | -| [dynamical_decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions) | | | | | -| | enable | | `True`/`False` | `False` | -| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | -| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | -| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | -| [environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | | | | | -| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | -| | callback | |Callable function that receives Job ID and Job result. |`None` | -| | job_tags | |List of tags |`None` | -| [execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptions) | | | | | -| | init_qubits | | `True`/`False` | `True` | -| | rep_delay | | Value in the range supplied by `backend.rep_delay_range`. | Given by `backend.default_rep_delay`.| -| [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | -| [optimization_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | `0`/`1` | `1` | -| [resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptions) | | | | | -| | LayerNoiseLearning | | `True`/`False` | `True` | -| | | max_layers_to_learn | `None`/ integer >= 1 | `4` | -| | | shots_per_randomization | integer >= 1 | `128` | -| | | num_randomizations | integer >= 1 | `32` | -| | | layer_pair_depths | list[int] of 2-10 values in the range [0, 200] | `(0, 1, 2, 4, 16, 32)` | -| | measure_mitigation | | `True`/`False` | `True` | -| | measure_noise_learning | num_randomizations | integer >= 1 | `32` | -| | | shots_per_randomization | integer | 'auto' | -| | pec | max_overhead | `None`/ integer >1 | `100` | -| | | noise_gain | `auto`/ float in the range `[0, 1]` | `auto` | -| | pec_mitigation | | `True`/`False` | `False` | -| | zne_mitigation | | `True`/`False` | `False` | -| | zne | noise_factors | list of floats; each float >= 1 | `(1, 3, 5)` | -| | | amplifier | `gate_folding`, `gate_folding_front`, `gate_folding_back ` | `gate_folding` | -| | | extrapolator | one or more of `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | -| [resilience_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | `0`/`1`/`2` | `1` | -| [seed_estimator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | integer | `None` | -| [simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | | | | | -| | noise_model | | [Qiskit Aer NoiseModel](build-noise-models), or its representation | `None` | -| | seed_simulator | | integer | `None` | -| | coupling_map | | List of directed two-qubit interactions | full connectivity | -| | basis_gates | | List of basis gate names to unroll to | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | -| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | | | | | -| | enable_gates | | `True`/`False` | `False` | -| | enable_measure | | `True`/`False` | `True` | -| | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | -| | shots_per_randomization | | `auto`/ Integer no larger than `backend.max_shots`. | `'auto'` | -| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | +| Option | Sub-option | Sub-sub-option | Choices | Default | Options | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------|----------------------| +| [default_shots](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | Integer in the range[0, `backend.max_shots`]| None | default_shots | +| [default_precision](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | float > 0 | `0.015625 (1 / sqrt(4096))` | default_precision | +| [dynamical_decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions) | | | | | dynamical_decoupling | +| | enable | | `True`/`False` | `False` | | +| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | | +| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | | +| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | | +| [environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | | | | | environment | +| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | | +| | callback | |Callable function that receives Job ID and Job result. |`None` | | +| | job_tags | |List of tags |`None` | | +| [execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptions) | | | | | execution | +| | init_qubits | | `True`/`False` | `True` | | +| | rep_delay | | Value in the range supplied by `backend.rep_delay_range`. | Given by `backend.default_rep_delay`.| | +| [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | max_execution_time | +| [resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptions) | | | | | resilience | +| | LayerNoiseLearning | | `True`/`False` | `True` | | +| | | max_layers_to_learn | `None`/ integer >= 1 | `4` | | +| | | shots_per_randomization | integer >= 1 | `128` | | +| | | num_randomizations | integer >= 1 | `32` | | +| | | layer_pair_depths | list[int] of 2-10 values in the range [0, 200] | `(0, 1, 2, 4, 16, 32)` | | +| | measure_mitigation | | `True`/`False` | `True` | | +| | measure_noise_learning | num_randomizations | integer >= 1 | `32` | | +| | | shots_per_randomization | integer | 'auto' | | +| | pec | max_overhead | `None`/ integer >1 | `100` | | +| | | noise_gain | `auto`/ float in the range `[0, 1]` | `auto` | | +| | pec_mitigation | | `True`/`False` | `False` | | +| | zne_mitigation | | `True`/`False` | `False` | | +| | zne | noise_factors | list of floats; each float >= 1 | `(1, 3, 5)` | | +| | | amplifier | `gate_folding`, `gate_folding_front`, `gate_folding_back ` | `gate_folding` | | +| | | extrapolator | one or more of `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | | +| [resilience_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | `0`/`1`/`2` | `1` | resilience_level | +| [seed_estimator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | integer | `None` | seed_estimator | +| [simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | | | | | simulator | +| | noise_model | | [Qiskit Aer NoiseModel](build-noise-models), or its representation | `None` | | +| | seed_simulator | | integer | `None` | | +| | coupling_map | | List of directed two-qubit interactions | full connectivity | | +| | basis_gates | | List of basis gate names to unroll to | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | | +| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | | | | | twirling | +| | enable_gates | | `True`/`False` | `False` | | +| | enable_measure | | `True`/`False` | `True` | | +| | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | | +| | shots_per_randomization | | `auto`/ Integer no larger than `backend.max_shots`. | `'auto'` | | +| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | | -| Options | Sub-options | Sub-sub-options | Choices | Default | -|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| [default_shots](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions) | | | Integer in the range[0, `backend.max_shots`] | `4096` | -| [dynamical_decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions) | | | | | -| | enable | | `True`/`False` | `False` | -| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | -| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | -| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | -| [environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | | | | | -| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | -| | callback | |Callable function that receives Job ID and Job result. |`None` | -| | job_tags | |List of tags |`None` | -| [execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2) | | | | | -| | init_qubits | | `True`/`False` | `True` | -| | rep_delay | | Value in the range supplied by `backend.rep_delay_range`. | Given by `backend.default_rep_delay`.| -| [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | -| [simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | | | | | -| | noise_model | | [Qiskit Aer NoiseModel](build-noise-models), or its representation | `None` | -| | seed_simulator | | integer | `None` | -| | coupling_map | | List of directed two-qubit interactions | full connectivity | -| | basis_gates | | List of basis gate names to unroll to | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | -| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | | | | | -| | enable_gates | | `True`/`False` | `False` | -| | enable_measure | | `True`/`False` | `True` | -| | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | -| | shots_per_randomization | | `auto`/ Integer no larger than `backend.max_shots`. | `'auto'` | -| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | +| Option | Sub-option | Sub-sub-option | Choices | Default | Option | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------|-------------------------| +| [default_shots](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions) | | | Integer in the range[0, `backend.max_shots`] | `4096` | default_shots | +| [dynamical_decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions) | | | | | dynamical_decoupling | +| | enable | | `True`/`False` | `False` | | +| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | | +| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | | +| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | | +| [environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | | | | | | +| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | environment | +| | callback | |Callable function that receives Job ID and Job result. |`None` | | +| | job_tags | |List of tags |`None` | | +| [execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2) | | | | | | +| | init_qubits | | `True`/`False` | `True` | execution | +| | rep_delay | | Value in the range supplied by `backend.rep_delay_range`. | Given by `backend.default_rep_delay`.| | +| [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | | +| [simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | | | | | max_execution_time | +| | noise_model | | [Qiskit Aer NoiseModel](build-noise-models), or its representation | `None` | simulator | +| | seed_simulator | | integer | `None` | | +| | coupling_map | | List of directed two-qubit interactions | full connectivity | | +| | basis_gates | | List of basis gate names to unroll to | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | | +| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | | | | | | +| | enable_gates | | `True`/`False` | `False` | twirling | +| | enable_measure | | `True`/`False` | `True` | | +| | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | | +| | shots_per_randomization | | `auto`/ Integer no larger than `backend.max_shots`. | `'auto'` | | +| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | | -| Options | Sub-options | Sub-sub-options | Choices | Default | -|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| [optimization_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | `0`/`1` | `1` | -| [resilience_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | `0`/`1`/`2` | `1` | -| [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | -| [resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptions) | | | | | -| | extrapolator | | `LinearExtrapolator`/`QuadraticExtrapolator`/`CubicExtrapolator`/`QuarticExtrapolator` | `None`, or `LinearExtrapolator` if `resilience_level=2`. | -| | noise_amplifier | | | | -| | noise_factors | | Applies only for `resilience_level=2`. List of real valued noise factors. | `(1, 3, 5)` | -| [transpilation](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TranspilationOptions) | | | | | -| | skip_transpilation | | `True`/`False` | `False` | -| | initial_layout | | layout instance, dictionary, list, or None. See [qiskit.compiler.](../api/qiskit/compiler#transpile) | `None` | -| | layout_method | | `trivial`/`dense`/`noise_adaptive`/`sabre`/`none` | `None` | -| | routing_method | | `Basic`/`lookahead`/`stochastic`/`none` | | `None` -| | approximation_degree | | Float in the range 0 - 1 / `None` | `None` | -| [execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptions) | | | | | -| | init_qubits | | `True`/`False` | `True` | -| | shots | | Integer no larger than `backend.max_shots`. | 4000| -| [environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | | | | | -| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | -| | callback | |Callable function that receives Job ID and Job result. |`None` | -| | job_tags | |List of tags |`None` | -| [simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | | | | | -| | noise_model | | [Qiskit Aer NoiseModel](build-noise-models), or its representation | `None` | -| | seed_simulator | | integer | `None` | -| | coupling_map | | List of directed two-qubit interactions | full connectivity | -| | basis_gates | | List of basis gate names to unroll to | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | +| Option | Sub-option | Sub-sub-option | Choices | Default | Option | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------|---------------------------| +| [resilience_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | `0`/`1`/`2` | `1` | resilience_level | +| [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | max_execution_time | +| [resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptions) | | | | | resilience | +| | extrapolator | | `LinearExtrapolator`/`QuadraticExtrapolator`/`CubicExtrapolator`/`QuarticExtrapolator` | `None`, or `LinearExtrapolator` if `resilience_level=2`. | | +| | noise_amplifier | | | | | +| | noise_factors | | Applies only for `resilience_level=2`. List of real valued noise factors. | `(1, 3, 5)` | | +| [transpilation](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TranspilationOptions) | | | | | transpilation | +| | skip_transpilation | | `True`/`False` | `False` | | +| | initial_layout | | layout instance, dictionary, list, or None. See [qiskit.compiler.](../api/qiskit/compiler#transpile) | `None` | | +| | layout_method | | `trivial`/`dense`/`noise_adaptive`/`sabre`/`none` | `None` | | +| | routing_method | | `Basic`/`lookahead`/`stochastic`/`none` | | `None` | | +| | approximation_degree | | Float in the range 0 - 1 / `None` | `None` | | +| [execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptions) | | | | | execution | +| | init_qubits | | `True`/`False` | `True` | | +| | shots | | Integer no larger than `backend.max_shots`. | 4000| | +| [environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | | | | | environment | +| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | | +| | callback | |Callable function that receives Job ID and Job result. |`None` | | +| | job_tags | |List of tags |`None` | | +| [simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | | | | | simulator | +| | noise_model | | [Qiskit Aer NoiseModel](build-noise-models), or its representation | `None` | | +| | seed_simulator | | integer | `None` | | +| | coupling_map | | List of directed two-qubit interactions | full connectivity | | +| | basis_gates | | List of basis gate names to unroll to | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | | @@ -579,7 +577,7 @@ estimator = Estimator(session=backend, options=options) ## Turn off all error mitigation and error suppression -You can turn off all error mitigation and suppression if you are, for example, doing research on your own mitigation techniques. To accomplish this, for EstimatorV2, set `resilience_level = 0` and `optimization_level = 0`. For SamplerV2, no changes are necessary because no error mitigation or suppression options are enabled by default. +You can turn off all error mitigation and suppression if you are, for example, doing research on your own mitigation techniques. To accomplish this, for EstimatorV2, set `resilience_level = 0`. For SamplerV2, no changes are necessary because no error mitigation or suppression options are enabled by default. Example: @@ -601,7 +599,6 @@ options = estimator.options # Turn off all error mitigation and suppression options.resilience_level = 0 -options.optimization_level = 0 ``` From 322aa58dfb6396f59c81f02cf7b33278d37af052 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 18 Jul 2024 09:18:45 -0500 Subject: [PATCH 04/44] add sub option links --- docs/guides/runtime-options-overview.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 28e12702fad..3614bc46a35 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -58,7 +58,7 @@ estimator.options.resilience.measure_mitigation = True estimator.options.default_shots = 4000 # Sample two circuits at 128 shots each. -estimator.run([circuit1, circuit2], shots=128) +estimator.run([(circuit1, observable1), (circuit2, observable2)], shots=128) ``` #### Special cases @@ -90,7 +90,7 @@ estimator.options.resilience.zne_mitigation = True - - [Resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2): Advanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC. Estimator only. + - [Resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2): Advanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC. - [Dynamical decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions): Options for dynamical decoupling. - [Execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2): Primitive execution options, including whether to initialize qubits and the repetition delay. - [Twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions): Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. @@ -103,7 +103,7 @@ estimator.options.resilience.zne_mitigation = True - [Execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2): Primitive execution options, including whether to initialize qubits and the repetition delay. - [Twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions): Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. - [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions): Execution environment options such as the logging level to set and job tags to add. - - [Simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions): Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to **local testing mode only**. + - [Simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions): Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to local testing mode only. @@ -144,19 +144,19 @@ Scroll to see the full table. | | rep_delay | | Value in the range supplied by `backend.rep_delay_range`. | Given by `backend.default_rep_delay`.| | | [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | max_execution_time | | [resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptions) | | | | | resilience | -| | LayerNoiseLearning | | `True`/`False` | `True` | | +| | [layer_noise_learning](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.LayerNoiseLearningOptions) | | `True`/`False` | `True` | | | | | max_layers_to_learn | `None`/ integer >= 1 | `4` | | | | | shots_per_randomization | integer >= 1 | `128` | | | | | num_randomizations | integer >= 1 | `32` | | | | | layer_pair_depths | list[int] of 2-10 values in the range [0, 200] | `(0, 1, 2, 4, 16, 32)` | | -| | measure_mitigation | | `True`/`False` | `True` | | -| | measure_noise_learning | num_randomizations | integer >= 1 | `32` | | +| | measure_mitigation | | `True`/`False` | `True` | | +| | [measure_noise_learning](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.MeasureNoiseLearningOptions) | num_randomizations | integer >= 1 | `32` | | | | | shots_per_randomization | integer | 'auto' | | -| | pec | max_overhead | `None`/ integer >1 | `100` | | +| | [pec](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.PecOptions) | max_overhead | `None`/ integer >1 | `100` | | | | | noise_gain | `auto`/ float in the range `[0, 1]` | `auto` | | | | pec_mitigation | | `True`/`False` | `False` | | | | zne_mitigation | | `True`/`False` | `False` | | -| | zne | noise_factors | list of floats; each float >= 1 | `(1, 3, 5)` | | +| | [zne](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ZneOptions) | noise_factors | list of floats; each float >= 1 | `(1, 3, 5)` | | | | | amplifier | `gate_folding`, `gate_folding_front`, `gate_folding_back ` | `gate_folding` | | | | | extrapolator | one or more of `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | | | [resilience_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | `0`/`1`/`2` | `1` | resilience_level | From 28d437a93bba5935d431575622c6cd2651da0921 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 18 Jul 2024 11:51:45 -0500 Subject: [PATCH 05/44] add max execution time as commonly used --- docs/guides/runtime-options-overview.mdx | 73 +++++------------------- 1 file changed, 15 insertions(+), 58 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 3614bc46a35..e288836be22 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -10,7 +10,7 @@ description: Specify options when building with Qiskit Runtime primitives -To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives. See the [transpilation documentation](./transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set `optimization_level=0`. +To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the QPU (quantum processing unit) before being submitted to the Qiskit Runtime primitives. Such input is referred to as *instruction set architecture (ISA)* circuits and observables. See the [transpilation documentation](./transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set `optimization_level=0`. *Exception*: When you initialize the Qiskit Runtime Service with the Q-CTRL channel strategy (example below), abstract circuits are still supported. @@ -348,7 +348,7 @@ Example: `SamplerV2` and `EstimatorV2` have separate options classes that do not need to be instantiated. You can see the available options and update option values during or after primitive initialization. Those options will then be applied when you use `run()` to perform the calculation. Example: ```python -estimator = Estimator(backend=backend) +estimator = Estimator(mode=backend) # Setting options after primitive initialization # This uses auto complete. @@ -360,7 +360,7 @@ estimator.options.default_shots = 4000 When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Example: ```python -estimator = Estimator(session=backend, options=options) +estimator = Estimator(backend=backend, options=options) result = estimator.run(circuit, observable).result() print(f">>> Metadata: {result.metadata[0]}") ``` @@ -419,7 +419,7 @@ sampler.run([circuit1, circuit2], shots=128) You can pass any options to `run()`. Because most users will only overwrite a few options at the job level, it is not necessary to specify the options category. The code below, for example, specifies `shots=1024` instead of `execution={"shots": 1024}` (which is also valid). ```python -estimator = Estimator(session=backend, options=options) +estimator = Estimator(backend=backend, options=options) result = estimator.run(circuit, observable, shots=1024).result() print(f">>> Metadata: {result.metadata[0]}") ``` @@ -440,7 +440,7 @@ Shots (or precision) can be specified in multiple places in V2. They are priori For any Sampler pub: -1. Int-valued shots contained in the pub +1. Integer-valued shots contained in the pub 2. The `run(...,shots=val)` value 3. The `options.default_shots` value @@ -504,72 +504,29 @@ For more information about the primitive options, refer to the +### Maximum execution time -### Error suppression - -The Qiskit Runtime primitives must be called with circuits already suitable for execution on the target system. This implies that the user has already transpiled the circuits to respect the native gate set and connectivity constraints of the target system. - -In the V2 primitives, you can explicitly enable and disable individual error mitigation and suppression methods, such as dynamical decoupling. For an example, see the -[Error suppression topic](configure-error-suppression#transpilation-table). - - - In the V1 Qiskit Runtime primitives, optimization levels 2 and 3 behave identically to level 1. If you want to use more advanced optimization, use the Qiskit transpiler locally, set [`skip_transpilation=True`](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TranspilationOptions#skip_transpilation), and then pass the transpiled circuits to the primitives. For instructions see the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial. - - -The optimization level option is a "first-level option", and can be set as follows (V1 primitives only): - -```python -from qiskit_ibm_runtime import Estimator, Options - -options = Options(optimization_level=1) - -# or.. -options = Options() -options.optimization_level = 1 - -estimator = Estimator(session=backend, options=options) -``` - -For more information and a complete list of advanced transpilation options, see the Advanced transpilation options table in the -[Configure error suppression topic](configure-error-suppression#transpilation-table). - -### Error mitigation - +The maximum execution time (`max_execution_time`) limits how long a job can run. If a job exceeds this time limit, it is forcibly cancelled. This value applies to single jobs, whether they are run in job, session, or batch mode. -You might want to leverage different error mitigation methods and see how these affect the performance of your -algorithm. These methods can be set through the `resilience_level` option. For more information about error mitigation, see the -[Configure error mitigation topic](configure-error-mitigation). +The value is set in seconds, based on quantum time (not wall clock time), which is the amount of time that the QPU is dedicated to processing your job. - -With Estimator V2, you can set resilience levels 0-2 and you can also turn on and off various error mitigation settings for fine-tuning. + ```python -estimator = Estimator(backend=backend) +estimator = Estimator(mode=backend) -estimator.options.resilience_level = 2 -estimator.options.resilience.zne_mitigation = True -estimator.options.resilience.zne.noise_factors = [1, 3, 5] +estimator.options.max_execution_time = 2500 ``` + -The method selected for each level is -different for `Sampler` and `Estimator`. - -The configuration is similar to the other options: - ```python -from qiskit_ibm_runtime import Estimator, Options - -options = Options(resilience_level = 2) - -# or... - options = Options() -options.resilience_level = 2 +estimator.options.max_execution_time = 2500 -estimator = Estimator(session=backend, options=options) +estimator = Estimator(backend=backend) ``` @@ -586,7 +543,7 @@ Turn off all error mitigation and suppression in EstimatorV2. ```python from qiskit_ibm_runtime import EstimatorV2 as Estimator, Options, QiskitRuntimeService -# Define the service. This allows you to access IBM Quantum systems. +# Define the service. This allows you to access IBM QPU. service = QiskitRuntimeService() # Get a backend From d7078bc28e6275b346cbb6ec39ae041cf434ed08 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 18 Jul 2024 12:08:28 -0500 Subject: [PATCH 06/44] ignored in local mode --- docs/guides/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index e288836be22..c75aa0afcb5 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -508,7 +508,7 @@ For more information about the primitive options, refer to the The maximum execution time (`max_execution_time`) limits how long a job can run. If a job exceeds this time limit, it is forcibly cancelled. This value applies to single jobs, whether they are run in job, session, or batch mode. -The value is set in seconds, based on quantum time (not wall clock time), which is the amount of time that the QPU is dedicated to processing your job. +The value is set in seconds, based on quantum time (not wall clock time), which is the amount of time that the QPU is dedicated to processing your job. It is ignored when using local testing mode because that mode does not have quantum time. From 0b57dc669f117d910f278f7ed7cea83dcb8ecd5c Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 18 Jul 2024 15:23:11 -0500 Subject: [PATCH 07/44] reformat set options section --- docs/guides/runtime-options-overview.mdx | 67 ++++++++++++++++++------ 1 file changed, 51 insertions(+), 16 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index c75aa0afcb5..24ed1870009 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -335,9 +335,13 @@ options.execution.shots = 2048 ## Set primitive options -You can set options in an options class, when initializing the primitive, or both. +You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. -### Options class +### Primitive initialization + +You can pass in an instance of the options class (`EstimatorOptions` and `SamplerOptions` for V2 primitives, `Options` for V1 primitives), or a dictionary when initializing a primitive. + +#### Options class When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Specify the options in this format: `primitive.options.option.sub-option.sub-sub-option = choice`. For example: `estimator.options.dynamical_decoupling.enable = True` @@ -345,32 +349,37 @@ Example: - `SamplerV2` and `EstimatorV2` have separate options classes that do not need to be instantiated. You can see the available options and update option values during or after primitive initialization. Those options will then be applied when you use `run()` to perform the calculation. Example: + `SamplerV2` and `EstimatorV2` have separate options classes that do not need to be instantiated. ```python -estimator = Estimator(mode=backend) +estimator = Estimator(backend=backend) -# Setting options after primitive initialization -# This uses auto complete. -estimator.options.default_shots = 4000 +estimator.options.resilience_level = 2 +estimator.options.resilience.zne_mitigation = True +estimator.options.resilience.zne.noise_factors = [1, 3, 5] ``` -When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Example: -```python -estimator = Estimator(backend=backend, options=options) -result = estimator.run(circuit, observable).result() -print(f">>> Metadata: {result.metadata[0]}") + ```python +from qiskit_ibm_runtime import Estimator, Options + +options = Options(resilience_level = 2) + +# or... + +options = Options() +options.resilience_level = 2 + +estimator = Estimator(session=backend, options=options) ``` -### Primitive initialization - -You can specify options when initializing the primitive. +#### Dictionary +You can specify options as a dictionary when initializing the primitive. @@ -400,6 +409,33 @@ estimator = Estimator(backend, options={"resilience_level": 2}) +### Update options after initialization + + + + ```python +# Setting options after primitive initialization +# This uses auto complete. +estimator.options.default_shots = 4000 +# This does bulk update. +estimator.options.update(default_shots=4000, resilience_level=2) +``` + + + +```python +# Setting options after primitive initialization +# This uses auto complete. +options.resilience_level = 2 +estimator = Estimator(backend=backend, options=options) + +# Setting options after primitive initialization. +# This does bulk update. +estimator.set_options(shots=4000) +``` + + + ### Run() method @@ -426,7 +462,6 @@ print(f">>> Metadata: {result.metadata[0]}") - ## Commonly used options There are many available options, but the following are the most commonly used: From 7a60dc02d3970f1329c8e9996fe265c49dc6252f Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 19 Jul 2024 09:30:49 -0500 Subject: [PATCH 08/44] split out pages --- docs/guides/_toc.json | 3 + docs/guides/runtime-options-overview.mdx | 291 +-------------------- docs/guides/specify-runtime-options.mdx | 309 +++++++++++++++++++++++ 3 files changed, 314 insertions(+), 289 deletions(-) create mode 100644 docs/guides/specify-runtime-options.mdx diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 34a8a6bad2b..2fa7d3fa040 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -306,6 +306,9 @@ "url": "/guides/runtime-options-overview" }, { + "title": "Specify options", + "url": "/guides/specify-runtime-options" + },{ "title": "Error mitigation and suppression techniques", "url": "/guides/error-mitigation-and-suppression-techniques" }, diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 24ed1870009..dd3068dede0 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -1,6 +1,6 @@ --- title: Introduction to options -description: Specify options when building with Qiskit Runtime primitives +description: Available options for building with Qiskit Runtime primitives --- @@ -305,293 +305,6 @@ Due to differences in the device compilation process, certain runtime features c -## V2 changes -Options are specified differently in the V2 primitives in these ways: - -- `SamplerV2` and `EstimatorV2` now have separate options classes. You can see the available options and update option values during or after primitive initialization. -- Instead of the `set_options()` method, V2 primitive options have the `update()` method that applies changes to the `options` attribute. -- If you do not specify a value for an option, it is given a special value of `Unset` and the server defaults are used. -- For V2 primitives, the `options` attribute is the `dataclass` Python type. You can use the built-in `asdict` method to convert it to a dictionary. - -## Instantiate the Options class (V1) - -In the example below, we create an instance of the `Options` class. `optimization_level` is a first-level option and can be passed as an input parameter. Options related to the execution environment are passed using the `environment` parameter. - -```python -from qiskit_ibm_runtime import Options - -options = Options(optimization_level=1, environment={"log_level": "INFO"}) -``` - -The `Options` class supports auto-complete. Once you create an instance of the `Options` class, you can use auto-complete to see what options are available. If you choose one of the categories, you can use auto-complete again to see what options are available under that category. - -```python -from qiskit_ibm_runtime import Options - -options = Options() -options.resilience_level = 1 -options.execution.shots = 2048 -``` - -## Set primitive options - -You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. - -### Primitive initialization - -You can pass in an instance of the options class (`EstimatorOptions` and `SamplerOptions` for V2 primitives, `Options` for V1 primitives), or a dictionary when initializing a primitive. - -#### Options class - -When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Specify the options in this format: `primitive.options.option.sub-option.sub-sub-option = choice`. For example: `estimator.options.dynamical_decoupling.enable = True` - -Example: - - - - `SamplerV2` and `EstimatorV2` have separate options classes that do not need to be instantiated. - -```python -estimator = Estimator(backend=backend) - -estimator.options.resilience_level = 2 -estimator.options.resilience.zne_mitigation = True -estimator.options.resilience.zne.noise_factors = [1, 3, 5] -``` - - - - - ```python -from qiskit_ibm_runtime import Estimator, Options - -options = Options(resilience_level = 2) - -# or... - -options = Options() -options.resilience_level = 2 - -estimator = Estimator(session=backend, options=options) -``` - - - -#### Dictionary - -You can specify options as a dictionary when initializing the primitive. - - - - ```python -from qiskit_ibm_runtime import QiskitRuntimeService -from qiskit_ibm_runtime import EstimatorV2 as Estimator - -service = QiskitRuntimeService() -backend = service.least_busy(operational=True, simulator=False) - -# Setting options during primitive initialization -estimator = Estimator(backend, options={"resilience_level": 2}) -``` - - - - ```python -from qiskit_ibm_runtime import QiskitRuntimeService -from qiskit_ibm_runtime import Estimator - -service = QiskitRuntimeService() -backend = service.least_busy(operational=True, simulator=False) - -# Setting options during primitive initialization -estimator = Estimator(backend, options={"resilience_level": 2}) -``` - - - -### Update options after initialization - - - - ```python -# Setting options after primitive initialization -# This uses auto complete. -estimator.options.default_shots = 4000 -# This does bulk update. -estimator.options.update(default_shots=4000, resilience_level=2) -``` - - - -```python -# Setting options after primitive initialization -# This uses auto complete. -options.resilience_level = 2 -estimator = Estimator(backend=backend, options=options) - -# Setting options after primitive initialization. -# This does bulk update. -estimator.set_options(shots=4000) -``` - - - - -### Run() method - -The run() method accepts options in V1 only. - - - -In V2, the only values you can pass to `run()` are those defined in the interface. That is, `shots` for Sampler and `precision` for Estimator. This overwrites any value set for `default_shots` or `default_precision` for the current run. - -```python -# Sample two circuits at 128 shots each. -sampler.run([circuit1, circuit2], shots=128) -``` - - - - -You can pass any options to `run()`. Because most users will only overwrite a few options at the job level, it is not necessary to specify the options category. The code below, for example, specifies `shots=1024` instead of `execution={"shots": 1024}` (which is also valid). -```python -estimator = Estimator(backend=backend, options=options) -result = estimator.run(circuit, observable, shots=1024).result() -print(f">>> Metadata: {result.metadata[0]}") -``` - - - -## Commonly used options - -There are many available options, but the following are the most commonly used: - -### Shots -For some algorithms, setting a specific number of shots is a core part of their routines. There are several ways to set and update shots with the primitives. - - - -Shots (or precision) can be specified in multiple places in V2. They are prioritized as follows: - -For any Sampler pub: - -1. Integer-valued shots contained in the pub -2. The `run(...,shots=val)` value -3. The `options.default_shots` value - -For any Estimator pub: - -1. Float-valued precision contained in the pub -2. The `run(...,precision=val)` value -3. The `options.default_shots` value -4. The `options.default_precision` value - -Example: - -```python -from qiskit_ibm_runtime import SamplerV2 as Sampler - -# Setting shots during primitive initialization -sampler = Sampler(backend, options={"default_shots": 4096}) - -# Setting options after primitive initialization -# This uses auto complete. -sampler.options.default_shots=2000 - -# This does bulk update. The value for default_shots is overridden if you specify shots with run() or in the PUB. -sampler.options.update(default_shots=1024, dynamical_decoupling={"sequence_type": "XpXm"}) - -# Sample two circuits at 128 shots each. -sampler.run([circuit1, circuit2], shots=128) - ``` - - - -Previously, shots could be set during the call to `backend.run()`. For example, `backend.run(shots=1024)`. Now, that setting is part of the execution -options ("second level option"). This can be done during the primitive setup: - -```python -from qiskit_ibm_runtime import Estimator, Options - -options = Options() -options.execution.shots = 1024 - -estimator = Estimator(session=backend, options=options) -``` - -If you need to modify the number of shots set between iterations (primitive calls), you can set the -shots directly in the `run()` method. This overwrites the initial `shots` setting. - -```python -from qiskit_ibm_runtime import Estimator - -estimator = Estimator(session=backend) - -estimator.run(circuits=circuits, observables=observables, shots=50) - -# other logic - -estimator.run(circuits=circuits, observables=observables, shots=100) -``` - -For more information about the primitive options, refer to the -[Options class API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options). - - - -### Maximum execution time - -The maximum execution time (`max_execution_time`) limits how long a job can run. If a job exceeds this time limit, it is forcibly cancelled. This value applies to single jobs, whether they are run in job, session, or batch mode. - -The value is set in seconds, based on quantum time (not wall clock time), which is the amount of time that the QPU is dedicated to processing your job. It is ignored when using local testing mode because that mode does not have quantum time. - - - - -```python -estimator = Estimator(mode=backend) - -estimator.options.max_execution_time = 2500 -``` - - - - -```python -options = Options() -estimator.options.max_execution_time = 2500 - -estimator = Estimator(backend=backend) -``` - - - - -## Turn off all error mitigation and error suppression - -You can turn off all error mitigation and suppression if you are, for example, doing research on your own mitigation techniques. To accomplish this, for EstimatorV2, set `resilience_level = 0`. For SamplerV2, no changes are necessary because no error mitigation or suppression options are enabled by default. - -Example: - -Turn off all error mitigation and suppression in EstimatorV2. - -```python -from qiskit_ibm_runtime import EstimatorV2 as Estimator, Options, QiskitRuntimeService - -# Define the service. This allows you to access IBM QPU. -service = QiskitRuntimeService() - -# Get a backend -backend = service.least_busy(operational=True, simulator=False) - -# Define Estimator -estimator = Estimator(backend) - -options = estimator.options - -# Turn off all error mitigation and suppression -options.resilience_level = 0 -``` ## Next steps @@ -601,5 +314,5 @@ options.resilience_level = 0 - Find more details about the `Sampler` methods in the [Sampler API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.Sampler#sampler). - Find all available options in the [Options API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options). - Find details about how to configure [error suppression](configure-error-suppression) and [error mitigation](configure-error-mitigation). - - Decide what [execution mode](execution-modes) to run your job in. + - Learn how to [specify options](specify-runtime-options). \ No newline at end of file diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx new file mode 100644 index 00000000000..68990ed78a4 --- /dev/null +++ b/docs/guides/specify-runtime-options.mdx @@ -0,0 +1,309 @@ +--- +title: Specify options +description: Specify options when building with Qiskit Runtime primitives + +--- + +# Specify options + +You can use options to customize the Estimator and Sampler primitives. This section focuses on how top specify Qiskit Runtime primitive options. While the interface of the primitives' `run()` method is common across all implementations, their options are not. Consult the corresponding API references for information about the [`qiskit.primitives`](/api/qiskit/primitives#primitives) and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) options. + +## V2 primitives + +Options are specified differently in the V2 primitives in these ways: + +- `SamplerV2` and `EstimatorV2` have separate options classes. You can see the available options and update option values during or after primitive initialization. +- Instead of the `set_options()` method, V2 primitive options have the `update()` method that applies changes to the `options` attribute. +- If you do not specify a value for an option, it is given a special value of `Unset` and the server defaults are used. +- For V2 primitives, the `options` attribute is the `dataclass` Python type. You can use the built-in `asdict` method to convert it to a dictionary. + +## Instantiate the Options class (V1) + +When using V1 primitives, you must Instantiate the options class before you can set the options. In the example below, we create an instance of the `Options` class. `optimization_level` is a first-level option and can be passed as an input parameter. Options related to the execution environment are passed using the `environment` parameter. + +```python +from qiskit_ibm_runtime import Options + +options = Options(optimization_level=1, environment={"log_level": "INFO"}) +``` + +The `Options` class supports auto-complete. Once you create an instance of the `Options` class, you can use auto-complete to see what options are available. If you choose one of the categories, you can use auto-complete again to see what options are available under that category. + +```python +from qiskit_ibm_runtime import Options + +options = Options() +options.resilience_level = 1 +options.execution.shots = 2048 +``` + +## Set primitive options + +You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. + +### Primitive initialization + +You can pass in an instance of the options class or a dictionary when initializing a primitive. + +#### Options class + +When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Specify the options in this format: `primitive.options.option.sub-option.sub-sub-option = choice`. For example: `estimator.options.dynamical_decoupling.enable = True` + +Example: + + + + `SamplerV2` and `EstimatorV2` have separate options classes ([`EstimatorOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) and [`SamplerOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions)) that do not need to be instantiated. + +```python +estimator = Estimator(backend=backend) + +estimator.options.resilience_level = 2 +estimator.options.resilience.zne_mitigation = True +estimator.options.resilience.zne.noise_factors = [1, 3, 5] +``` + + + + + ```python +from qiskit_ibm_runtime import Estimator, Options + +options = Options(resilience_level = 2) + +# or... + +options = Options() +options.resilience_level = 2 + +estimator = Estimator(session=backend, options=options) +``` + + + +#### Dictionary + +You can specify options as a dictionary when initializing the primitive. + + + + ```python +from qiskit_ibm_runtime import QiskitRuntimeService +from qiskit_ibm_runtime import EstimatorV2 as Estimator + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) + +# Setting options during primitive initialization +estimator = Estimator(backend, options={"resilience_level": 2}) +``` + + + + ```python +from qiskit_ibm_runtime import QiskitRuntimeService +from qiskit_ibm_runtime import Estimator + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) + +# Setting options during primitive initialization +estimator = Estimator(backend, options={"resilience_level": 2}) +``` + + + +### Update options after initialization + + + + ```python +# Setting options after primitive initialization +# This uses auto complete. +estimator.options.default_shots = 4000 +# This does bulk update. +estimator.options.update(default_shots=4000, resilience_level=2) +``` + + + +```python +# Setting options after primitive initialization +# This uses auto complete. +options.resilience_level = 2 +estimator = Estimator(backend=backend, options=options) + +# Setting options after primitive initialization. +# This does bulk update. +estimator.set_options(shots=4000) +``` + + + + +### Run() method + +The run() method accepts options in V1 only. + + + +In V2, the only values you can pass to `run()` are those defined in the interface. That is, `shots` for Sampler and `precision` for Estimator. This overwrites any value set for `default_shots` or `default_precision` for the current run. + +```python +# Sample two circuits at 128 shots each. +sampler.run([circuit1, circuit2], shots=128) +``` + + + + +You can pass any options to `run()`. Because most users will only overwrite a few options at the job level, it is not necessary to specify the options category. The code below, for example, specifies `shots=1024` instead of `execution={"shots": 1024}` (which is also valid). +```python +estimator = Estimator(backend=backend, options=options) +result = estimator.run(circuit, observable, shots=1024).result() +print(f">>> Metadata: {result.metadata[0]}") +``` + + + +## Commonly used options + +There are many available options, but the following are the most commonly used: + +### Shots +For some algorithms, setting a specific number of shots is a core part of their routines. There are several ways to set and update shots with the primitives. + + + +Shots (or precision) can be specified in multiple places in V2. They are prioritized as follows: + +For any Sampler pub: + +1. Integer-valued shots contained in the pub +2. The `run(...,shots=val)` value +3. The `options.default_shots` value + +For any Estimator pub: + +1. Float-valued precision contained in the pub +2. The `run(...,precision=val)` value +3. The `options.default_shots` value +4. The `options.default_precision` value + +Example: + +```python +from qiskit_ibm_runtime import SamplerV2 as Sampler + +# Setting shots during primitive initialization +sampler = Sampler(backend, options={"default_shots": 4096}) + +# Setting options after primitive initialization +# This uses auto complete. +sampler.options.default_shots=2000 + +# This does bulk update. The value for default_shots is overridden if you specify shots with run() or in the PUB. +sampler.options.update(default_shots=1024, dynamical_decoupling={"sequence_type": "XpXm"}) + +# Sample two circuits at 128 shots each. +sampler.run([circuit1, circuit2], shots=128) + ``` + + + +Previously, shots could be set during the call to `backend.run()`. For example, `backend.run(shots=1024)`. Now, that setting is part of the execution +options ("second level option"). This can be done during the primitive setup: + +```python +from qiskit_ibm_runtime import Estimator, Options + +options = Options() +options.execution.shots = 1024 + +estimator = Estimator(session=backend, options=options) +``` + +If you need to modify the number of shots set between iterations (primitive calls), you can set the +shots directly in the `run()` method. This overwrites the initial `shots` setting. + +```python +from qiskit_ibm_runtime import Estimator + +estimator = Estimator(session=backend) + +estimator.run(circuits=circuits, observables=observables, shots=50) + +# other logic + +estimator.run(circuits=circuits, observables=observables, shots=100) +``` + +For more information about the primitive options, refer to the +[Options class API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options). + + + +### Maximum execution time + +The maximum execution time (`max_execution_time`) limits how long a job can run. If a job exceeds this time limit, it is forcibly cancelled. This value applies to single jobs, whether they are run in job, session, or batch mode. + +The value is set in seconds, based on quantum time (not wall clock time), which is the amount of time that the QPU is dedicated to processing your job. It is ignored when using local testing mode because that mode does not have quantum time. + + + + +```python +estimator = Estimator(mode=backend) + +estimator.options.max_execution_time = 2500 +``` + + + + +```python +options = Options() +estimator.options.max_execution_time = 2500 + +estimator = Estimator(backend=backend) +``` + + + + +## Turn off all error mitigation and error suppression + +You can turn off all error mitigation and suppression if you are, for example, doing research on your own mitigation techniques. To accomplish this, for EstimatorV2, set `resilience_level = 0`. For SamplerV2, no changes are necessary because no error mitigation or suppression options are enabled by default. + +Example: + +Turn off all error mitigation and suppression in EstimatorV2. + +```python +from qiskit_ibm_runtime import EstimatorV2 as Estimator, Options, QiskitRuntimeService + +# Define the service. This allows you to access IBM QPU. +service = QiskitRuntimeService() + +# Get a backend +backend = service.least_busy(operational=True, simulator=False) + +# Define Estimator +estimator = Estimator(backend) + +options = estimator.options + +# Turn off all error mitigation and suppression +options.resilience_level = 0 +``` + + +## Next steps + + + - Find more details about the `Estimator` methods in the [Estimator API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.Estimator#estimator). + - Find more details about the `Sampler` methods in the [Sampler API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.Sampler#sampler). + - Find all available options in the [Options API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options). + - Find details about how to configure [error suppression](configure-error-suppression) and [error mitigation](configure-error-mitigation). + - Decide what [execution mode](execution-modes) to run your job in. + \ No newline at end of file From 05ac00718b5a0215b00ea69ad5751a2d3451c27b Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 19 Jul 2024 10:33:07 -0500 Subject: [PATCH 09/44] Update qiskit_bot.yaml --- qiskit_bot.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index d4a11931ff5..05208c404ef 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -189,6 +189,8 @@ notifications: - "`@kevinsung`" "docs/guides/specify-observables-pauli": - "@Cryoris" + "docs/guides/specify-runtime-options": + - "@beckyd" "docs/guides/synthesize-unitary-operators": - "@Cryoris" "docs/guides/qpu-information": From 53560a9f8b7a9f03ff102c08dcf60142f1cf4471 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 19 Jul 2024 10:38:33 -0500 Subject: [PATCH 10/44] Update execute-on-hardware.mdx --- docs/guides/execute-on-hardware.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/guides/execute-on-hardware.mdx b/docs/guides/execute-on-hardware.mdx index 4b0f44b05cf..5f69273acfa 100644 --- a/docs/guides/execute-on-hardware.mdx +++ b/docs/guides/execute-on-hardware.mdx @@ -32,9 +32,10 @@ expectation values of observables corresponding to physical quantities or cost f * [Primitives with REST API](./primitives-rest-api) ### Configure runtime options -* [Configure runtime compilation](./configure-error-suppression) -* [Configure runtime error mitigation](./configure-error-mitigation) -* [Advanced runtime options](./runtime-options-overview) +* [Overview](./runtime-options-overview) +* [Specify options](./specify-runtime-options) +* [Configure error suppression](./configure-error-suppression) +* [Configure error mitigation](./configure-error-mitigation) * [Error mitigation and suppression techniques](./error-mitigation-and-suppression-techniques) ### Execution modes From e14675d20553bc297dd7a528d1bdaa3e542d719c Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 19 Jul 2024 10:57:15 -0500 Subject: [PATCH 11/44] fix links --- docs/guides/configure-error-mitigation.mdx | 2 +- docs/guides/configure-error-suppression.mdx | 2 +- docs/guides/runtime-options-overview.mdx | 6 ++---- docs/guides/specify-runtime-options.mdx | 2 +- 4 files changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 7e20bc45f58..945d04daa88 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -457,7 +457,7 @@ psi1_H1 = job.result() ## Turn off all error mitigation -For instructions to turn off all error mitigation, see the [Turn off all error suppression and mitigation](runtime-options-overview#no-error-mitigation) section. +For instructions to turn off all error mitigation, see the [Turn off all error suppression and mitigation](specify-runtime-options#no-error-mitigation) section. ## Next steps diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index 5fc0a6bef3e..94fa8ca93a7 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -164,7 +164,7 @@ print(f">>> dynamical decoupling sequence to use: {sampler.options.dynamical_dec ## Turn off all error suppression -For instructions to turn off all error suppression, see the [Turn off all error suppression and mitigation](runtime-options-overview#no-error-mitigation) section. +For instructions to turn off all error suppression, see the [Turn off all error suppression and mitigation](specify-runtime-options#no-error-mitigation) section. ## Next steps diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index dd3068dede0..46205294495 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -24,7 +24,7 @@ service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl") ### Structure -When calling the primitives, you can pass in options by using an options class or a dictionary. In the options classes, commonly used options, such as `resilience_level`, are at the first level. Other options are grouped into different categories, such as `execution`. See the [Set primitive options](#pass-options) section for full details. +When calling the primitives, you can pass in options by using an options class or a dictionary. In the options classes, commonly used options, such as `resilience_level`, are at the first level. Other options are grouped into different categories, such as `execution`. See the [Set primitive options](specify-runtime-options) topic for full details. ### Defaults @@ -43,7 +43,7 @@ There are several ways to set options. If you set different values for the same 2. Any options set during primitive initialization. -Shots (Sampler) or precision (Estimator) set in `run()` are not considered options, but take precidence over values set for `default_shots`or `default_precision`. See the [Run() method](#run-method) section for full details. +Shots (Sampler) or precision (Estimator) set in `run()` are not considered options, but take precidence over values set for `default_shots`or `default_precision`. See the [Run() method](specify-runtime-options#run-method) section for full details. In the following example, these values would be used for the `estimator.run` job: `shots = 128` and `resilience_level = 1`. @@ -305,8 +305,6 @@ Due to differences in the device compilation process, certain runtime features c - - ## Next steps diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index 68990ed78a4..1f893aa7112 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -39,7 +39,7 @@ options.execution.shots = 2048 ## Set primitive options -You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. +You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. See the [precidence rules](runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places. ### Primitive initialization From a6de355fe17f122a5ccaf45310cf7a31fb137518 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 19 Jul 2024 11:48:27 -0500 Subject: [PATCH 12/44] link --- docs/guides/configure-error-suppression.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index 94fa8ca93a7..9a2796681d7 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -10,7 +10,7 @@ Error suppression refers to techniques where you use knowledge about the undesir V2 primitives support a number of error suppression techniques, including dynamical decoupling and Pauli twirling. See Error mitigation and suppression techniques for explanation of each. In V2 primitives, you can turn on or off individual method. See the [Advanced error suppression options](#transpilation-table) section for details. -Estimator V2 employs error suppression and mitigation by default. If you don't want any processing done to your input circuits follow the instructions in the [Turn off all error mitigation and error suppression](runtime-options-overview#no-error-mitigation) section. +Estimator V2 employs error suppression and mitigation by default. If you don't want any processing done to your input circuits follow the instructions in the [Turn off all error mitigation and error suppression](specify-runtime-options#no-error-mitigation) section. To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives. See the [transpilation documentation](./transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set `optimization_level=0`. From df31a3b2a92cc670f8e7d14fba758ea66ecc8241 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 19 Jul 2024 12:02:02 -0500 Subject: [PATCH 13/44] add a few more links --- docs/guides/configure-error-mitigation.mdx | 10 +++------- docs/guides/configure-error-suppression.mdx | 2 +- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 945d04daa88..569e5607be7 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -11,13 +11,9 @@ results in quantum pre-processing overhead related to model training and classical post-processing overhead to mitigate errors in the raw results by using the generated model. -The error mitigation techniques built in to primitives are advanced -resilience options. To specify these options, use the `resilience_level` -option when submitting your job. +Primitives support several error mitigation techniques, including TREX, [ZNE](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#zne), and [PEC](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#pec). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for explanation of each. In V2 primitives, you can turn on or off individual methods. See the [Custom error settings](#advanced-error) section for details. -Sampler V2 does not support specifying resilience levels. However, you can turn on or off individual error mitigation / suppression methods. See the [Custom error settings](#advanced-error) section for details. - -The resilience level specifies how much resilience to build against +Estimator V2 also supports `resilience_level`. The resilience level specifies how much resilience to build against errors. Higher levels generate more accurate results, at the expense of longer processing times. Resilience levels can be used to configure the cost/accuracy trade-off when applying error mitigation to your primitive @@ -364,7 +360,7 @@ sampler = Sampler(backend, options=options) ## Custom error settings (V2 primitives) -With the V2 primitives, you can turn on and off individual error mitigation and suppression methods, including dynamical decoupling, gate and measurement twirling, measurement error mitigation, and ZNE. +With the V2 primitives, you can turn on and off individual error mitigation and suppression methods, including dynamical decoupling, gate and measurement twirling, measurement error mitigation, and ZNE. See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. - Not all options are available for both primitives. See the [API reference](/api/qiskit-ibm-runtime/options) for the list of available options. diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index 9a2796681d7..29db405fcce 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -8,7 +8,7 @@ description: How to configure error suppression in Qiskit Runtime. (Previous top Error suppression refers to techniques where you use knowledge about the undesirable effects to introduce customization that can anticipate and avoid the potential impacts of those effects. These techniques often consist of altering or adding control signals to ensure that the quantum processor returns the desired results. This typically results in quantum pre-processing overhead; therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time. -V2 primitives support a number of error suppression techniques, including dynamical decoupling and Pauli twirling. See Error mitigation and suppression techniques for explanation of each. In V2 primitives, you can turn on or off individual method. See the [Advanced error suppression options](#transpilation-table) section for details. +V2 primitives support a number of error suppression techniques, including dynamical decoupling and Pauli twirling. See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. In V2 primitives, you can turn on or off individual method. See the [Advanced error suppression options](#transpilation-table) section for details. Estimator V2 employs error suppression and mitigation by default. If you don't want any processing done to your input circuits follow the instructions in the [Turn off all error mitigation and error suppression](specify-runtime-options#no-error-mitigation) section. From 330751afc87d5f074f8de12091fa2054ee918616 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 19 Jul 2024 12:34:27 -0500 Subject: [PATCH 14/44] Add yet more links! --- docs/guides/configure-error-mitigation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 569e5607be7..b0f9f07d7a0 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -11,7 +11,7 @@ results in quantum pre-processing overhead related to model training and classical post-processing overhead to mitigate errors in the raw results by using the generated model. -Primitives support several error mitigation techniques, including TREX, [ZNE](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#zne), and [PEC](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#pec). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for explanation of each. In V2 primitives, you can turn on or off individual methods. See the [Custom error settings](#advanced-error) section for details. +Primitives support several error mitigation techniques, including [TREX](https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#measure_mitigation), [ZNE](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#zne), and [PEC](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#pec). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for explanation of each. In V2 primitives, you can turn on or off individual methods. See the [Custom error settings](#advanced-error) section for details. Estimator V2 also supports `resilience_level`. The resilience level specifies how much resilience to build against errors. Higher levels generate more accurate results, at the expense of From eac273d92d3914ad746fcef1cb6fbe8a4779b0b0 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 19 Jul 2024 12:40:10 -0500 Subject: [PATCH 15/44] move over code --- docs/guides/specify-runtime-options.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index 1f893aa7112..9b882e71ebd 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -65,8 +65,7 @@ estimator.options.resilience.zne.noise_factors = [1, 3, 5] - - ```python +```python from qiskit_ibm_runtime import Estimator, Options options = Options(resilience_level = 2) @@ -117,7 +116,7 @@ estimator = Estimator(backend, options={"resilience_level": 2}) - ```python +```python # Setting options after primitive initialization # This uses auto complete. estimator.options.default_shots = 4000 From dec839485b2acbf824a05d67dd6eab5f01cf617e Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 19 Jul 2024 12:43:43 -0500 Subject: [PATCH 16/44] typos --- docs/guides/configure-error-mitigation.mdx | 2 +- docs/guides/specify-runtime-options.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index b0f9f07d7a0..cef46e1dc44 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -11,7 +11,7 @@ results in quantum pre-processing overhead related to model training and classical post-processing overhead to mitigate errors in the raw results by using the generated model. -Primitives support several error mitigation techniques, including [TREX](https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#measure_mitigation), [ZNE](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#zne), and [PEC](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#pec). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for explanation of each. In V2 primitives, you can turn on or off individual methods. See the [Custom error settings](#advanced-error) section for details. +Primitives support several error mitigation techniques, including [TREX](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#measure_mitigation), [ZNE](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#zne), and [PEC](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#pec). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for explanation of each. In V2 primitives, you can turn on or off individual methods. See the [Custom error settings](#advanced-error) section for details. Estimator V2 also supports `resilience_level`. The resilience level specifies how much resilience to build against errors. Higher levels generate more accurate results, at the expense of diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index 9b882e71ebd..be2f9ab6c82 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -6,7 +6,7 @@ description: Specify options when building with Qiskit Runtime primitives # Specify options -You can use options to customize the Estimator and Sampler primitives. This section focuses on how top specify Qiskit Runtime primitive options. While the interface of the primitives' `run()` method is common across all implementations, their options are not. Consult the corresponding API references for information about the [`qiskit.primitives`](/api/qiskit/primitives#primitives) and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) options. +You can use options to customize the Estimator and Sampler primitives. This section focuses on how to specify Qiskit Runtime primitive options. While the interface of the primitives' `run()` method is common across all implementations, their options are not. Consult the corresponding API references for information about the [`qiskit.primitives`](/api/qiskit/primitives#primitives) and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) options. ## V2 primitives From a6b9152543972ca27f0b129de95b3f14ab84dcda Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 19 Jul 2024 12:44:58 -0500 Subject: [PATCH 17/44] expand intro --- docs/guides/specify-runtime-options.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index be2f9ab6c82..3f0ead853b9 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -8,6 +8,8 @@ description: Specify options when building with Qiskit Runtime primitives You can use options to customize the Estimator and Sampler primitives. This section focuses on how to specify Qiskit Runtime primitive options. While the interface of the primitives' `run()` method is common across all implementations, their options are not. Consult the corresponding API references for information about the [`qiskit.primitives`](/api/qiskit/primitives#primitives) and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) options. +Options are specified differently depending on whether you are using the V1 or V2 interface. + ## V2 primitives Options are specified differently in the V2 primitives in these ways: From f1bec8d7c55c05a9655dd25e97b638d2c220f402 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 19 Jul 2024 13:01:33 -0500 Subject: [PATCH 18/44] code bug --- docs/guides/specify-runtime-options.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index 3f0ead853b9..ca570b4b982 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -117,7 +117,7 @@ estimator = Estimator(backend, options={"resilience_level": 2}) ### Update options after initialization - + ```python # Setting options after primitive initialization # This uses auto complete. @@ -125,9 +125,9 @@ estimator.options.default_shots = 4000 # This does bulk update. estimator.options.update(default_shots=4000, resilience_level=2) ``` - + - + ```python # Setting options after primitive initialization # This uses auto complete. @@ -138,7 +138,7 @@ estimator = Estimator(backend=backend, options=options) # This does bulk update. estimator.set_options(shots=4000) ``` - + From e9d0dfa89ed8a0e0b4f7bd0022035e6626ce55ad Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 23 Jul 2024 13:29:49 -0500 Subject: [PATCH 19/44] Jessie comments --- docs/guides/configure-error-mitigation.mdx | 4 ++-- docs/guides/configure-error-suppression.mdx | 4 ++-- docs/guides/runtime-options-overview.mdx | 4 ++-- docs/guides/specify-runtime-options.mdx | 24 +++++++++++++++------ 4 files changed, 24 insertions(+), 12 deletions(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index cef46e1dc44..49c74ea52fa 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -360,10 +360,10 @@ sampler = Sampler(backend, options=options) ## Custom error settings (V2 primitives) -With the V2 primitives, you can turn on and off individual error mitigation and suppression methods, including dynamical decoupling, gate and measurement twirling, measurement error mitigation, and ZNE. See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. +With the V2 primitives, you can turn on and off individual error mitigation and suppression methods, including dynamical decoupling, gate and measurement twirling, measurement error mitigation, PEC, and ZNE. See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. -- Not all options are available for both primitives. See the [API reference](/api/qiskit-ibm-runtime/options) for the list of available options. +- Not all options are available for both primitives. See the [available options](runtime-options-overview#options-table) table for the list of available options. - Dynamical decoupling is not supported when the input circuits are dynamic. diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index 29db405fcce..a0e5b8f8b90 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -8,7 +8,7 @@ description: How to configure error suppression in Qiskit Runtime. (Previous top Error suppression refers to techniques where you use knowledge about the undesirable effects to introduce customization that can anticipate and avoid the potential impacts of those effects. These techniques often consist of altering or adding control signals to ensure that the quantum processor returns the desired results. This typically results in quantum pre-processing overhead; therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time. -V2 primitives support a number of error suppression techniques, including dynamical decoupling and Pauli twirling. See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. In V2 primitives, you can turn on or off individual method. See the [Advanced error suppression options](#transpilation-table) section for details. +V2 primitives support a number of error suppression techniques, including [dynamical decoupling](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions#dynamicaldecouplingoptions) and Pauli [twirling](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. In V2 primitives, you can turn on or off individual method. See the [Advanced error suppression options](#transpilation-table) section for details. Estimator V2 employs error suppression and mitigation by default. If you don't want any processing done to your input circuits follow the instructions in the [Turn off all error mitigation and error suppression](specify-runtime-options#no-error-mitigation) section. @@ -134,7 +134,7 @@ psi1_H1 = job.result() - In the V2 primitives, you can explicitly enable and disable individual error mitigation and suppression methods, such as dynamical decoupling. See [Advanced Qiskit Runtime options](runtime-options-overview) for information about available options. + In the V2 primitives, you can explicitly enable and disable individual error mitigation and suppression methods, such as dynamical decoupling. See [available options](runtime-options-overview#options-table) table for a list of available options. Dynamical decoupling is not supported when the input circuits are dynamic. diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 46205294495..7aac73d3e6e 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -46,7 +46,7 @@ There are several ways to set options. If you set different values for the same Shots (Sampler) or precision (Estimator) set in `run()` are not considered options, but take precidence over values set for `default_shots`or `default_precision`. See the [Run() method](specify-runtime-options#run-method) section for full details. -In the following example, these values would be used for the `estimator.run` job: `shots = 128` and `resilience_level = 1`. +In the following example, these values would be used for the `estimator.run` job: `shots = 128` and `measure_mitigation = True`. ``` python # Setting options during primitive initialization @@ -152,9 +152,9 @@ Scroll to see the full table. | | measure_mitigation | | `True`/`False` | `True` | | | | [measure_noise_learning](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.MeasureNoiseLearningOptions) | num_randomizations | integer >= 1 | `32` | | | | | shots_per_randomization | integer | 'auto' | | +| | pec_mitigation | | `True`/`False` | `False` | | | | [pec](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.PecOptions) | max_overhead | `None`/ integer >1 | `100` | | | | | noise_gain | `auto`/ float in the range `[0, 1]` | `auto` | | -| | pec_mitigation | | `True`/`False` | `False` | | | | zne_mitigation | | `True`/`False` | `False` | | | | [zne](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ZneOptions) | noise_factors | list of floats; each float >= 1 | `(1, 3, 5)` | | | | | amplifier | `gate_folding`, `gate_folding_front`, `gate_folding_back ` | `gate_folding` | | diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index ca570b4b982..665e7709029 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -49,20 +49,26 @@ You can pass in an instance of the options class or a dictionary when initializi #### Options class -When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Specify the options in this format: `primitive.options.option.sub-option.sub-sub-option = choice`. For example: `estimator.options.dynamical_decoupling.enable = True` +When creating an instance of the `Estimator` or `Sampler` class, you can pass in an instance of the options class. Those options will then be applied when you use `run()` to perform the calculation. Specify the options in this format: `primitive.options.option.sub-option.sub-sub-option = choice`. For example: `estimator.options.dynamical_decoupling.enable = True` Example: - `SamplerV2` and `EstimatorV2` have separate options classes ([`EstimatorOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) and [`SamplerOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions)) that do not need to be instantiated. + `SamplerV2` and `EstimatorV2` have separate options classes ([`EstimatorOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) and [`SamplerOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions)) that do not need to be instantiated, but they can be if you want to pass them in during primitive initialization. ```python -estimator = Estimator(backend=backend) +from qiskit_ibm_runtime.options import EstimatorOptions + +options = EstimatorOptions(resilience_level=2, resilience={"zne_mitigation": True, "zne": {"noise_factors": [1, 3, 5]}}) +# or... +options = EstimatorOptions() estimator.options.resilience_level = 2 -estimator.options.resilience.zne_mitigation = True -estimator.options.resilience.zne.noise_factors = [1, 3, 5] +options.resilience.zne_mitigation = True +options.resilience.zne.noise_factors = [1, 3, 5] + +estimator = Estimator(mode=backend, options=options) ``` @@ -116,6 +122,8 @@ estimator = Estimator(backend, options={"resilience_level": 2}) ### Update options after initialization +You can specify the options in this format: `primitive.options.option.sub-option.sub-sub-option = choice` to take advantage of auto complete, or use the `update()` method to make bulk updates. + ```python @@ -123,7 +131,7 @@ estimator = Estimator(backend, options={"resilience_level": 2}) # This uses auto complete. estimator.options.default_shots = 4000 # This does bulk update. -estimator.options.update(default_shots=4000, resilience_level=2) +estimator.options.update(default_shots=4000, resilience={"zne_mitigation": True}) ``` @@ -153,6 +161,10 @@ In V2, the only values you can pass to `run()` are those defined in the interfac ```python # Sample two circuits at 128 shots each. sampler.run([circuit1, circuit2], shots=128) + +# Sample two circuits with different numbers of shots. +# 100 shots is used for circuit1 and 200 for circuit2. +sampler.run([(circuit1, None, 100), (circuit2, None, 200)]) ``` From cbda0a3b9a5496f5855f8015135508cd50237f81 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 24 Jul 2024 14:49:28 -0500 Subject: [PATCH 20/44] Update docs/guides/specify-runtime-options.mdx Co-authored-by: Jessie Yu --- docs/guides/specify-runtime-options.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index 665e7709029..538dcee251e 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -49,7 +49,7 @@ You can pass in an instance of the options class or a dictionary when initializi #### Options class -When creating an instance of the `Estimator` or `Sampler` class, you can pass in an instance of the options class. Those options will then be applied when you use `run()` to perform the calculation. Specify the options in this format: `primitive.options.option.sub-option.sub-sub-option = choice`. For example: `estimator.options.dynamical_decoupling.enable = True` +When creating an instance of the `Estimator` or `Sampler` class, you can pass in an instance of the options class. Those options will then be applied when you use `run()` to perform the calculation. Specify the options in this format: `options.option.sub-option.sub-sub-option = choice`. For example: `options.dynamical_decoupling.enable = True` Example: From 272d8fee107d26e153493f16ba13d77a51ca4528 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 24 Jul 2024 14:59:57 -0500 Subject: [PATCH 21/44] Update docs/guides/specify-runtime-options.mdx Co-authored-by: Jessie Yu --- docs/guides/specify-runtime-options.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index 538dcee251e..b003a3ed91a 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -64,7 +64,7 @@ options = EstimatorOptions(resilience_level=2, resilience={"zne_mitigation": Tr # or... options = EstimatorOptions() -estimator.options.resilience_level = 2 +options.resilience_level = 2 options.resilience.zne_mitigation = True options.resilience.zne.noise_factors = [1, 3, 5] From b355e03f094ec6bdc8b25072e1f062dece97337b Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 24 Jul 2024 15:12:51 -0500 Subject: [PATCH 22/44] Update docs/guides/specify-runtime-options.mdx Co-authored-by: Jessie Yu --- docs/guides/specify-runtime-options.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index b003a3ed91a..0f7fd71ba31 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -102,7 +102,7 @@ service = QiskitRuntimeService() backend = service.least_busy(operational=True, simulator=False) # Setting options during primitive initialization -estimator = Estimator(backend, options={"resilience_level": 2}) +estimator = Estimator(backend, options={"resilience_level": 2, "resilience": {"zne_mitigation": True, "zne": {"noise_factors": [1, 3, 5]}}}) ``` From 1536d647803eefdc5a3b88fe52d4ffa58f1af6e9 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 24 Jul 2024 15:13:32 -0500 Subject: [PATCH 23/44] jessie comments --- docs/guides/configure-error-mitigation.mdx | 2 +- docs/guides/runtime-options-overview.mdx | 2 +- docs/guides/specify-runtime-options.mdx | 33 +++++++++++++++++++++- 3 files changed, 34 insertions(+), 3 deletions(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 49c74ea52fa..d3cae85e054 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -364,7 +364,7 @@ With the V2 primitives, you can turn on and off individual error mitigation and - Not all options are available for both primitives. See the [available options](runtime-options-overview#options-table) table for the list of available options. -- Dynamical decoupling is not supported when the input circuits are dynamic. +- Not all methods work together on all types of circuits. See the [options compatibility](runtime-options-overview#options-compatibility-table) table for details. diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 7aac73d3e6e..8eb564e4f5d 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -24,7 +24,7 @@ service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl") ### Structure -When calling the primitives, you can pass in options by using an options class or a dictionary. In the options classes, commonly used options, such as `resilience_level`, are at the first level. Other options are grouped into different categories, such as `execution`. See the [Set primitive options](specify-runtime-options) topic for full details. +When calling the primitives, you can pass in options by using an options class or a dictionary. Commonly used options, such as `resilience_level`, are at the first level. Other options are grouped into different categories, such as `execution`. See the [Set primitive options](specify-runtime-options) topic for full details. ### Defaults diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index b003a3ed91a..044aeb7f6b3 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -59,6 +59,11 @@ Example: ```python from qiskit_ibm_runtime.options import EstimatorOptions +from qiskit_ibm_runtime import QiskitRuntimeService +from qiskit_ibm_runtime import EstimatorV2 as Estimator + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) options = EstimatorOptions(resilience_level=2, resilience={"zne_mitigation": True, "zne": {"noise_factors": [1, 3, 5]}}) @@ -127,6 +132,14 @@ You can specify the options in this format: `primitive.options.option.sub-option ```python +from qiskit_ibm_runtime import QiskitRuntimeService +from qiskit_ibm_runtime import EstimatorV2 as Estimator + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) + +estimator = Estimator(mode=backend) + # Setting options after primitive initialization # This uses auto complete. estimator.options.default_shots = 4000 @@ -159,6 +172,13 @@ The run() method accepts options in V1 only. In V2, the only values you can pass to `run()` are those defined in the interface. That is, `shots` for Sampler and `precision` for Estimator. This overwrites any value set for `default_shots` or `default_precision` for the current run. ```python +from qiskit_ibm_runtime import QiskitRuntimeService +from qiskit_ibm_runtime import SamplerV2 as Sampler + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) + +sampler = Sampler(mode=backend) # Sample two circuits at 128 shots each. sampler.run([circuit1, circuit2], shots=128) @@ -207,9 +227,13 @@ Example: ```python from qiskit_ibm_runtime import SamplerV2 as Sampler +from qiskit_ibm_runtime import QiskitRuntimeService + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) # Setting shots during primitive initialization -sampler = Sampler(backend, options={"default_shots": 4096}) +sampler = Sampler(mode=backend, options={"default_shots": 4096}) # Setting options after primitive initialization # This uses auto complete. @@ -242,6 +266,7 @@ shots directly in the `run()` method. This overwrites the initial `shots` settin ```python from qiskit_ibm_runtime import Estimator + estimator = Estimator(session=backend) estimator.run(circuits=circuits, observables=observables, shots=50) @@ -266,6 +291,12 @@ The value is set in seconds, based on quantum time (not wall clock time), which ```python +from qiskit_ibm_runtime import QiskitRuntimeService +from qiskit_ibm_runtime import EstimatorV2 as Estimator + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) + estimator = Estimator(mode=backend) estimator.options.max_execution_time = 2500 From 7a18a9f49efdf967f1477c3c70f8feb4871a5adf Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 26 Jul 2024 12:28:10 -0500 Subject: [PATCH 24/44] Ian comments --- docs/guides/runtime-options-overview.mdx | 74 ++++++++++++++---------- docs/guides/specify-runtime-options.mdx | 4 +- 2 files changed, 44 insertions(+), 34 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 03ff1c12ccf..36323f3346c 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -35,55 +35,65 @@ For V1 primitives, if you do not specify a value for an option, the Qiskit Runti The tables in the [Options classes summary](#options-classes) section lists the default values. -### Precedence rules +## Set options -There are several ways to set options. If you set different values for the same option in multiple places, this is the order of precedence: +Options can be defined before a primitive is constructed and passed to the primitive, which will make a copy of them. As shown below, this can be done either as a nested dictionary, or by using the options classes. However, this is not necessary, because after the primitive is constructed, the options that it owns can be changed. You can choose the workflow that works best for your application. -1. Any options set after primitive initialization. -2. Any options set during primitive initialization. +``` python +from qiskit_ibm_runtime.options import EstimatorOptions - -Shots (Sampler) or precision (Estimator) set in `run()` are not considered options, but take precidence over values set for `default_shots`or `default_precision`. See the [Run() method](specify-runtime-options#run-method) section for full details. - +# Set options during primitive initialization with a nested dictionary +estimator1 = Estimator(backend, options={"twirling": {"enable_gates": True}}) -In the following example, these values would be used for the `estimator.run` job: `shots = 128` and `measure_mitigation = True`. +# Update the options after intialization +estimator1.options.twirling.num_randomizations = 100 -``` python -# Setting options during primitive initialization -estimator = Estimator(backend, options={'resilience_level': 2,'resilience': {'measure_mitigation': False}}) +# Set options during primitive initialization with an options class +options = EstimatorOptions() +options.twirling.enable_gates = True +estimator2 = Estimator(backend, options=options) + +# Update the options after intialization +estimator2.options.twirling.num_randomizations = 100 -# Setting options after primitive initialization -# This uses auto complete. -estimator.options.resilience.measure_mitigation = True -estimator.options.default_shots = 4000 +# Keep all default options during primitive initialization +estimator3 = Estimator(backend) -# Sample two circuits at 128 shots each. -estimator.run([(circuit1, observable1), (circuit2, observable2)], shots=128) +# Update the options after intialization +estimator3.options.twirling.enable_gates = True +estimator3.options.twirling.num_randomizations = 100 ``` -#### Special cases +### Special cases -The `default_shots` and `resilience_level` options require special consideration: +#### Resilience level (Estimator only) -If you set `default_shots` in an estimator, it overrides any value set for `default_precision`. +The resilience level is not actually an option, but is a specification of a base set of curated options to build off of. In general, level 0 turns off all error mitigation, level 1 turns on options for measurement error mitigation, and level 2 turns on options for gate and measurement error mitigation. -The `resilience_level` is used to set a base configuration on any relevant options, and then any other user-specified options override that configuration. So it would be possible to undo the effect of setting the resilience level by reversing all of its settings manually. +Any options you manually specify in addition to the resilience level are applied on top of the base set of options defined by the resilience level. So in principle, you could set the resilience level to 1, but then turn off measurement mitigation, although this is not advised. -In the following example, setting the resilience level to 0 does not turn off `zne_mitigation` because `estimator.options.resilience.zne_mitigation = True` overrides the relevent setup from `estimator.options.resilience_level = 0`. +### Shots (Sampler only) -``` python -from qiskit_ibm_runtime import EstimatorV2, QiskitRuntimeService -from qiskit import QuantumCircuit +The `SamplerV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for shots, and a shots keyword argument. These shot values are a part of the Sampler execution interface, and are independent of the Runtime Estimator's options. They take precedence over any values specified as options in order to comply with the Sampler abstraction. -service = QiskitRuntimeService() -backend = service.backend("ibm_auckland") +However, if `shots` is not specified by any PUB or in the run keyword argument (equivalently, if they are all `None`), then the shots value from the options is used, most notably `default_shots`. To sumarize, this is the the order of precedence for specifying shots in the Sampler, for any particular PUB: -estimator = EstimatorV2(backend) +1. If the PUB specifies shots, use that value. +2. If the shots keyword argument is specified in `run`, use that value. +3. If `sampler.options.default_shots` is specified, use that value. -estimator.options.default_shots = 100 -estimator.options.resilience_level = 0 -estimator.options.resilience.zne_mitigation = True -``` +For example, if shots are specified in all three places, the one with highest precedence (shots specified in the PUB) is used. + +### Precision (Estimator only) + +Precision is analogous to shots, described in the previous section, except that the options contains both `default_shots` and `default_precision`. Specifically, for any particular Estimator PUB: + +1. If the PUB specifies precision, use that value. +2. If the precision keyword argument is specified in `run`, use that value. +3. If `estimator.options.default_shots` is specified, use that value to control the amount of data. +4. If `estimator.options.default_precision` is specified, use that value. + +For example, if precision is specified in all four places, the one with highest precedence (precision specified in the PUB) is used. ## Options classes summary diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index ec20c388a3c..4b8fa7baaef 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -58,9 +58,9 @@ Example: `SamplerV2` and `EstimatorV2` have separate options classes ([`EstimatorOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) and [`SamplerOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions)) that do not need to be instantiated, but they can be if you want to pass them in during primitive initialization. ```python -from qiskit_ibm_runtime.options import EstimatorOptions from qiskit_ibm_runtime import QiskitRuntimeService from qiskit_ibm_runtime import EstimatorV2 as Estimator +from qiskit_ibm_runtime.options import EstimatorOptions service = QiskitRuntimeService() backend = service.least_busy(operational=True, simulator=False) @@ -226,8 +226,8 @@ For any Estimator pub: Example: ```python -from qiskit_ibm_runtime import SamplerV2 as Sampler from qiskit_ibm_runtime import QiskitRuntimeService +from qiskit_ibm_runtime import SamplerV2 as Sampler service = QiskitRuntimeService() backend = service.least_busy(operational=True, simulator=False) From 6f0a121cab2e41d8e51d892dd84fcdfed0b9cce5 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 26 Jul 2024 13:06:42 -0500 Subject: [PATCH 25/44] spellcheck --- docs/guides/runtime-options-overview.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 36323f3346c..2ec15a59c46 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -45,7 +45,7 @@ from qiskit_ibm_runtime.options import EstimatorOptions # Set options during primitive initialization with a nested dictionary estimator1 = Estimator(backend, options={"twirling": {"enable_gates": True}}) -# Update the options after intialization +# Update the options after initialization estimator1.options.twirling.num_randomizations = 100 # Set options during primitive initialization with an options class @@ -53,13 +53,13 @@ options = EstimatorOptions() options.twirling.enable_gates = True estimator2 = Estimator(backend, options=options) -# Update the options after intialization +# Update the options after initialization estimator2.options.twirling.num_randomizations = 100 # Keep all default options during primitive initialization estimator3 = Estimator(backend) -# Update the options after intialization +# Update the options after initialization estimator3.options.twirling.enable_gates = True estimator3.options.twirling.num_randomizations = 100 ``` @@ -76,7 +76,7 @@ Any options you manually specify in addition to the resilience level are applied The `SamplerV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for shots, and a shots keyword argument. These shot values are a part of the Sampler execution interface, and are independent of the Runtime Estimator's options. They take precedence over any values specified as options in order to comply with the Sampler abstraction. -However, if `shots` is not specified by any PUB or in the run keyword argument (equivalently, if they are all `None`), then the shots value from the options is used, most notably `default_shots`. To sumarize, this is the the order of precedence for specifying shots in the Sampler, for any particular PUB: +However, if `shots` is not specified by any PUB or in the run keyword argument (equivalently, if they are all `None`), then the shots value from the options is used, most notably `default_shots`. To summarize, this is the the order of precedence for specifying shots in the Sampler, for any particular PUB: 1. If the PUB specifies shots, use that value. 2. If the shots keyword argument is specified in `run`, use that value. From 4f283c197042beccf999597d9fa65ac2afaad9b0 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 26 Jul 2024 14:38:11 -0500 Subject: [PATCH 26/44] V2 --- docs/guides/runtime-options-overview.mdx | 25 +++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 2ec15a59c46..6f2350d9826 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -37,9 +37,12 @@ The tables in the [Options classes summary](#options-classes) section lists the ## Set options -Options can be defined before a primitive is constructed and passed to the primitive, which will make a copy of them. As shown below, this can be done either as a nested dictionary, or by using the options classes. However, this is not necessary, because after the primitive is constructed, the options that it owns can be changed. You can choose the workflow that works best for your application. +Options can be defined before a primitive is constructed and passed to the primitive, which will make a copy of them. This can be done either as a nested dictionary, or by using the options classes. Additionally, after the primitive is constructed, its options can be changed. Use the workflow that works best for your application. + +Example: ``` python +from qiskit_ibm_runtime import EstimatorV2 as Estimator from qiskit_ibm_runtime.options import EstimatorOptions # Set options during primitive initialization with a nested dictionary @@ -64,14 +67,30 @@ estimator3.options.twirling.enable_gates = True estimator3.options.twirling.num_randomizations = 100 ``` -### Special cases +### Special cases (V2 only) #### Resilience level (Estimator only) -The resilience level is not actually an option, but is a specification of a base set of curated options to build off of. In general, level 0 turns off all error mitigation, level 1 turns on options for measurement error mitigation, and level 2 turns on options for gate and measurement error mitigation. +The resilience level is not actually an option, but specifies a base set of curated options to build off of. In general, level 0 turns off all error mitigation, level 1 turns on options for measurement error mitigation, and level 2 turns on options for gate and measurement error mitigation. Any options you manually specify in addition to the resilience level are applied on top of the base set of options defined by the resilience level. So in principle, you could set the resilience level to 1, but then turn off measurement mitigation, although this is not advised. +In the following example, setting the resilience level to 0 initially turns off `zne_mitigation`, but `estimator.options.resilience.zne_mitigation = True` overrides the relevent setup from `estimator.options.resilience_level = 0`. + +``` python +from qiskit_ibm_runtime import EstimatorV2, QiskitRuntimeService +from qiskit import QuantumCircuit + +service = QiskitRuntimeService() +backend = service.backend("ibm_auckland") + +estimator = EstimatorV2(backend) + +estimator.options.default_shots = 100 +estimator.options.resilience_level = 0 +estimator.options.resilience.zne_mitigation = True +``` + ### Shots (Sampler only) The `SamplerV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for shots, and a shots keyword argument. These shot values are a part of the Sampler execution interface, and are independent of the Runtime Estimator's options. They take precedence over any values specified as options in order to comply with the Sampler abstraction. From 5a645d4b6f285ba4a8720284ba1a06fbf42e24a7 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 26 Jul 2024 14:47:18 -0500 Subject: [PATCH 27/44] Shuffle instructions to set options --- docs/guides/runtime-options-overview.mdx | 75 +----------------------- docs/guides/specify-runtime-options.mdx | 47 +++++++++++++++ 2 files changed, 48 insertions(+), 74 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 6f2350d9826..3194de3a40c 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -37,82 +37,9 @@ The tables in the [Options classes summary](#options-classes) section lists the ## Set options -Options can be defined before a primitive is constructed and passed to the primitive, which will make a copy of them. This can be done either as a nested dictionary, or by using the options classes. Additionally, after the primitive is constructed, its options can be changed. Use the workflow that works best for your application. +Options can be defined before a primitive is constructed and passed to the primitive, which will make a copy of them. This can be done either as a nested dictionary, or by using the options classes. Additionally, after the primitive is constructed, its options can be changed. Use the workflow that works best for your application. See [Specify options](specify-runtime-options) for full details. -Example: -``` python -from qiskit_ibm_runtime import EstimatorV2 as Estimator -from qiskit_ibm_runtime.options import EstimatorOptions - -# Set options during primitive initialization with a nested dictionary -estimator1 = Estimator(backend, options={"twirling": {"enable_gates": True}}) - -# Update the options after initialization -estimator1.options.twirling.num_randomizations = 100 - -# Set options during primitive initialization with an options class -options = EstimatorOptions() -options.twirling.enable_gates = True -estimator2 = Estimator(backend, options=options) - -# Update the options after initialization -estimator2.options.twirling.num_randomizations = 100 - -# Keep all default options during primitive initialization -estimator3 = Estimator(backend) - -# Update the options after initialization -estimator3.options.twirling.enable_gates = True -estimator3.options.twirling.num_randomizations = 100 -``` - -### Special cases (V2 only) - -#### Resilience level (Estimator only) - -The resilience level is not actually an option, but specifies a base set of curated options to build off of. In general, level 0 turns off all error mitigation, level 1 turns on options for measurement error mitigation, and level 2 turns on options for gate and measurement error mitigation. - -Any options you manually specify in addition to the resilience level are applied on top of the base set of options defined by the resilience level. So in principle, you could set the resilience level to 1, but then turn off measurement mitigation, although this is not advised. - -In the following example, setting the resilience level to 0 initially turns off `zne_mitigation`, but `estimator.options.resilience.zne_mitigation = True` overrides the relevent setup from `estimator.options.resilience_level = 0`. - -``` python -from qiskit_ibm_runtime import EstimatorV2, QiskitRuntimeService -from qiskit import QuantumCircuit - -service = QiskitRuntimeService() -backend = service.backend("ibm_auckland") - -estimator = EstimatorV2(backend) - -estimator.options.default_shots = 100 -estimator.options.resilience_level = 0 -estimator.options.resilience.zne_mitigation = True -``` - -### Shots (Sampler only) - -The `SamplerV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for shots, and a shots keyword argument. These shot values are a part of the Sampler execution interface, and are independent of the Runtime Estimator's options. They take precedence over any values specified as options in order to comply with the Sampler abstraction. - -However, if `shots` is not specified by any PUB or in the run keyword argument (equivalently, if they are all `None`), then the shots value from the options is used, most notably `default_shots`. To summarize, this is the the order of precedence for specifying shots in the Sampler, for any particular PUB: - -1. If the PUB specifies shots, use that value. -2. If the shots keyword argument is specified in `run`, use that value. -3. If `sampler.options.default_shots` is specified, use that value. - -For example, if shots are specified in all three places, the one with highest precedence (shots specified in the PUB) is used. - -### Precision (Estimator only) - -Precision is analogous to shots, described in the previous section, except that the options contains both `default_shots` and `default_precision`. Specifically, for any particular Estimator PUB: - -1. If the PUB specifies precision, use that value. -2. If the precision keyword argument is specified in `run`, use that value. -3. If `estimator.options.default_shots` is specified, use that value to control the amount of data. -4. If `estimator.options.default_precision` is specified, use that value. - -For example, if precision is specified in all four places, the one with highest precedence (precision specified in the PUB) is used. ## Options classes summary diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index 4b8fa7baaef..4934eaa011a 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -199,6 +199,53 @@ print(f">>> Metadata: {result.metadata[0]}") +### Special cases (V2 only) + +#### Resilience level (Estimator only) + +The resilience level is not actually an option, but specifies a base set of curated options to build off of. In general, level 0 turns off all error mitigation, level 1 turns on options for measurement error mitigation, and level 2 turns on options for gate and measurement error mitigation. + +Any options you manually specify in addition to the resilience level are applied on top of the base set of options defined by the resilience level. So in principle, you could set the resilience level to 1, but then turn off measurement mitigation, although this is not advised. + +In the following example, setting the resilience level to 0 initially turns off `zne_mitigation`, but `estimator.options.resilience.zne_mitigation = True` overrides the relevent setup from `estimator.options.resilience_level = 0`. + +``` python +from qiskit_ibm_runtime import EstimatorV2, QiskitRuntimeService +from qiskit import QuantumCircuit + +service = QiskitRuntimeService() +backend = service.backend("ibm_auckland") + +estimator = EstimatorV2(backend) + +estimator.options.default_shots = 100 +estimator.options.resilience_level = 0 +estimator.options.resilience.zne_mitigation = True +``` + +### Shots (Sampler only) + +The `SamplerV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for shots, and a shots keyword argument. These shot values are a part of the Sampler execution interface, and are independent of the Runtime Estimator's options. They take precedence over any values specified as options in order to comply with the Sampler abstraction. + +However, if `shots` is not specified by any PUB or in the run keyword argument (equivalently, if they are all `None`), then the shots value from the options is used, most notably `default_shots`. To summarize, this is the the order of precedence for specifying shots in the Sampler, for any particular PUB: + +1. If the PUB specifies shots, use that value. +2. If the shots keyword argument is specified in `run`, use that value. +3. If `sampler.options.default_shots` is specified, use that value. + +For example, if shots are specified in all three places, the one with highest precedence (shots specified in the PUB) is used. + +### Precision (Estimator only) + +Precision is analogous to shots, described in the previous section, except that the options contains both `default_shots` and `default_precision`. Specifically, for any particular Estimator PUB: + +1. If the PUB specifies precision, use that value. +2. If the precision keyword argument is specified in `run`, use that value. +3. If `estimator.options.default_shots` is specified, use that value to control the amount of data. +4. If `estimator.options.default_precision` is specified, use that value. + +For example, if precision is specified in all four places, the one with highest precedence (precision specified in the PUB) is used. + ## Commonly used options There are many available options, but the following are the most commonly used: From 8cf5bba95ff2fda2b5a80c59cdcca4fa09dbc41d Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 26 Jul 2024 17:17:31 -0500 Subject: [PATCH 28/44] edits --- docs/guides/runtime-options-overview.mdx | 2 +- docs/guides/specify-runtime-options.mdx | 20 +++++++++++--------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 3194de3a40c..9a2c6d51b42 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -37,7 +37,7 @@ The tables in the [Options classes summary](#options-classes) section lists the ## Set options -Options can be defined before a primitive is constructed and passed to the primitive, which will make a copy of them. This can be done either as a nested dictionary, or by using the options classes. Additionally, after the primitive is constructed, its options can be changed. Use the workflow that works best for your application. See [Specify options](specify-runtime-options) for full details. +Options can be defined before a primitive is constructed and passed to the primitive, which makes a copy of them. This can be done either as a nested dictionary, or by using the options classes. Additionally, after the primitive is constructed, its options can be changed. Use the workflow that works best for your application. See [Specify options](specify-runtime-options) for full details. diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index 4934eaa011a..3eac7e244df 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -41,11 +41,11 @@ options.execution.shots = 2048 ## Set primitive options -You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. See the [precidence rules](runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places. +You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. See the [precidence rules](runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places. Thus, changing the original dictionary or options instance doesn't affect the options owned by the primitives. ### Primitive initialization -You can pass in an instance of the options class or a dictionary when initializing a primitive. +You can pass in an instance of the options class or a dictionary when initializing a primitive, which then makes a copy of those options. #### Options class @@ -179,6 +179,8 @@ service = QiskitRuntimeService() backend = service.least_busy(operational=True, simulator=False) sampler = Sampler(mode=backend) +# Default shots to use if not specified in run() +sampler.options.default_shots = 500 # Sample two circuits at 128 shots each. sampler.run([circuit1, circuit2], shots=128) @@ -203,7 +205,7 @@ print(f">>> Metadata: {result.metadata[0]}") #### Resilience level (Estimator only) -The resilience level is not actually an option, but specifies a base set of curated options to build off of. In general, level 0 turns off all error mitigation, level 1 turns on options for measurement error mitigation, and level 2 turns on options for gate and measurement error mitigation. +The resilience level is not actually an option that directly impacts the primitive query, but specifies a base set of curated options to build off of. In general, level 0 turns off all error mitigation, level 1 turns on options for measurement error mitigation, and level 2 turns on options for gate and measurement error mitigation. Any options you manually specify in addition to the resilience level are applied on top of the base set of options defined by the resilience level. So in principle, you could set the resilience level to 1, but then turn off measurement mitigation, although this is not advised. @@ -225,7 +227,7 @@ estimator.options.resilience.zne_mitigation = True ### Shots (Sampler only) -The `SamplerV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for shots, and a shots keyword argument. These shot values are a part of the Sampler execution interface, and are independent of the Runtime Estimator's options. They take precedence over any values specified as options in order to comply with the Sampler abstraction. +The `SamplerV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for shots, and a shots keyword argument. These shot values are a part of the Sampler execution interface, and are independent of the Runtime Sampler's options. They take precedence over any values specified as options in order to comply with the Sampler abstraction. However, if `shots` is not specified by any PUB or in the run keyword argument (equivalently, if they are all `None`), then the shots value from the options is used, most notably `default_shots`. To summarize, this is the the order of precedence for specifying shots in the Sampler, for any particular PUB: @@ -237,7 +239,7 @@ For example, if shots are specified in all three places, the one with highest pr ### Precision (Estimator only) -Precision is analogous to shots, described in the previous section, except that the options contains both `default_shots` and `default_precision`. Specifically, for any particular Estimator PUB: +Precision is analogous to shots, described in the previous section, except that the Estimator options contains both `default_shots` and `default_precision`. Specifically, for any particular Estimator PUB: 1. If the PUB specifies precision, use that value. 2. If the precision keyword argument is specified in `run`, use that value. @@ -257,15 +259,15 @@ For some algorithms, setting a specific number of shots is a core part of their Shots (or precision) can be specified in multiple places in V2. They are prioritized as follows: -For any Sampler pub: +For any Sampler PUB: -1. Integer-valued shots contained in the pub +1. Integer-valued shots contained in the PUB 2. The `run(...,shots=val)` value 3. The `options.default_shots` value -For any Estimator pub: +For any Estimator PUB: -1. Float-valued precision contained in the pub +1. Float-valued precision contained in the PUB 2. The `run(...,precision=val)` value 3. The `options.default_shots` value 4. The `options.default_precision` value From e9435b14097283e7b541822a9129517f447c1216 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Mon, 29 Jul 2024 14:09:07 -0500 Subject: [PATCH 29/44] clarifications --- docs/guides/runtime-options-overview.mdx | 2 -- docs/guides/specify-runtime-options.mdx | 4 ++-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 9a2c6d51b42..b34b58ef49e 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -39,8 +39,6 @@ The tables in the [Options classes summary](#options-classes) section lists the Options can be defined before a primitive is constructed and passed to the primitive, which makes a copy of them. This can be done either as a nested dictionary, or by using the options classes. Additionally, after the primitive is constructed, its options can be changed. Use the workflow that works best for your application. See [Specify options](specify-runtime-options) for full details. - - ## Options classes summary diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index 3eac7e244df..4091e6a583f 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -41,11 +41,11 @@ options.execution.shots = 2048 ## Set primitive options -You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. See the [precidence rules](runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places. Thus, changing the original dictionary or options instance doesn't affect the options owned by the primitives. +You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. See the [precidence rules](runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places. ### Primitive initialization -You can pass in an instance of the options class or a dictionary when initializing a primitive, which then makes a copy of those options. +You can pass in an instance of the options class or a dictionary when initializing a primitive, which then makes a copy of those options. Thus, changing the original dictionary or options instance doesn't affect the options owned by the primitives. #### Options class From 213871e9f96dc221ecc4341dc8434e9e3f429752 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 30 Jul 2024 12:02:33 -0500 Subject: [PATCH 30/44] move sentence --- docs/guides/specify-runtime-options.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index 4091e6a583f..88c05a0c76c 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -55,7 +55,7 @@ Example: - `SamplerV2` and `EstimatorV2` have separate options classes ([`EstimatorOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) and [`SamplerOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions)) that do not need to be instantiated, but they can be if you want to pass them in during primitive initialization. + `SamplerV2` and `EstimatorV2` have separate options classes ([`EstimatorOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) and [`SamplerOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions)). ```python from qiskit_ibm_runtime import QiskitRuntimeService @@ -131,6 +131,7 @@ You can specify the options in this format: `primitive.options.option.sub-option + The `SamplerV2` and `EstimatorV2` options classes ([`EstimatorOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) and [`SamplerOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions)) do not need to be instantiated if you are setting options after initializing the primtiive. ```python from qiskit_ibm_runtime import QiskitRuntimeService from qiskit_ibm_runtime import EstimatorV2 as Estimator From 68d6cd839fa7d606e7bca070978e2f3dbe497677 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 31 Jul 2024 13:27:43 -0500 Subject: [PATCH 31/44] Final edits --- docs/guides/configure-error-suppression.mdx | 9 ++++---- docs/guides/specify-runtime-options.mdx | 23 ++------------------- 2 files changed, 7 insertions(+), 25 deletions(-) diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index e0c27d32a8d..19e7a78c166 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -134,11 +134,12 @@ psi1_H1 = job.result() - In the V2 primitives, you can explicitly enable and disable individual error mitigation and suppression methods, such as dynamical decoupling. See [available options](runtime-options-overview#options-table) table for a list of available options. + In the V2 primitives, you can explicitly enable and disable individual error mitigation and suppression methods, such as dynamical decoupling. - - Dynamical decoupling is not supported when the input circuits are dynamic. - + +- Not all options are available for both primitives. See the [available options](runtime-options-overview#options-table) table for the list of available options. +- Not all methods work together on all types of circuits. See the [options compatibility](runtime-options-overview#options-compatibility-table) table for details. + ```python from qiskit_ibm_runtime import QiskitRuntimeService diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx index 88c05a0c76c..e589411a840 100644 --- a/docs/guides/specify-runtime-options.mdx +++ b/docs/guides/specify-runtime-options.mdx @@ -19,25 +19,6 @@ Options are specified differently in the V2 primitives in these ways: - If you do not specify a value for an option, it is given a special value of `Unset` and the server defaults are used. - For V2 primitives, the `options` attribute is the `dataclass` Python type. You can use the built-in `asdict` method to convert it to a dictionary. -## Instantiate the Options class (V1) - -When using V1 primitives, you must Instantiate the options class before you can set the options. In the example below, we create an instance of the `Options` class. `optimization_level` is a first-level option and can be passed as an input parameter. Options related to the execution environment are passed using the `environment` parameter. - -```python -from qiskit_ibm_runtime import Options - -options = Options(optimization_level=1, environment={"log_level": "INFO"}) -``` - -The `Options` class supports auto-complete. Once you create an instance of the `Options` class, you can use auto-complete to see what options are available. If you choose one of the categories, you can use auto-complete again to see what options are available under that category. - -```python -from qiskit_ibm_runtime import Options - -options = Options() -options.resilience_level = 1 -options.execution.shots = 2048 -``` ## Set primitive options @@ -226,7 +207,7 @@ estimator.options.resilience_level = 0 estimator.options.resilience.zne_mitigation = True ``` -### Shots (Sampler only) +#### Shots (Sampler only) The `SamplerV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for shots, and a shots keyword argument. These shot values are a part of the Sampler execution interface, and are independent of the Runtime Sampler's options. They take precedence over any values specified as options in order to comply with the Sampler abstraction. @@ -238,7 +219,7 @@ However, if `shots` is not specified by any PUB or in the run keyword argument ( For example, if shots are specified in all three places, the one with highest precedence (shots specified in the PUB) is used. -### Precision (Estimator only) +#### Precision (Estimator only) Precision is analogous to shots, described in the previous section, except that the Estimator options contains both `default_shots` and `default_precision`. Specifically, for any particular Estimator PUB: From b2ec1e2828d266dbeef6581cbe79ec1d5729365f Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 13:43:06 -0500 Subject: [PATCH 32/44] Update docs/guides/configure-error-mitigation.mdx Co-authored-by: abbycross --- docs/guides/configure-error-mitigation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index d3cae85e054..3c900a71d33 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -11,7 +11,7 @@ results in quantum pre-processing overhead related to model training and classical post-processing overhead to mitigate errors in the raw results by using the generated model. -Primitives support several error mitigation techniques, including [TREX](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#measure_mitigation), [ZNE](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#zne), and [PEC](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#pec). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for explanation of each. In V2 primitives, you can turn on or off individual methods. See the [Custom error settings](#advanced-error) section for details. +Primitives support several error mitigation techniques, including [TREX](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#measure_mitigation), [ZNE](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#zne), and [PEC](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#pec). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. In V2 primitives, you can turn on or off individual methods. See the [Custom error settings](#advanced-error) section for details. Estimator V2 also supports `resilience_level`. The resilience level specifies how much resilience to build against errors. Higher levels generate more accurate results, at the expense of From f117a2c108d2eccb660dc10fb801208800d8f66e Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 13:43:18 -0500 Subject: [PATCH 33/44] Update docs/guides/configure-error-mitigation.mdx Co-authored-by: abbycross --- docs/guides/configure-error-mitigation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 3c900a71d33..90a06ee6ed5 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -31,7 +31,7 @@ which levels and corresponding methods are available for each of the primitives. -Error mitigation is task specific, so the techniques you are able to +Error mitigation is task-specific, so the techniques you can apply vary based whether you are sampling a distribution or generating expectation values. From 94b73e8c8993976996a6e54e0a20eae6efedcb76 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 13:46:27 -0500 Subject: [PATCH 34/44] Update docs/guides/configure-error-mitigation.mdx Co-authored-by: abbycross --- docs/guides/configure-error-mitigation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 90a06ee6ed5..592f65ae31a 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -363,7 +363,7 @@ sampler = Sampler(backend, options=options) With the V2 primitives, you can turn on and off individual error mitigation and suppression methods, including dynamical decoupling, gate and measurement twirling, measurement error mitigation, PEC, and ZNE. See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. -- Not all options are available for both primitives. See the [available options](runtime-options-overview#options-table) table for the list of available options. +- Not all options are available for both primitives. See the [available options table](runtime-options-overview#options-table) for the list of available options. - Not all methods work together on all types of circuits. See the [options compatibility](runtime-options-overview#options-compatibility-table) table for details. From 200a7e84a02658f223ef1da83b917835485e700e Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 13:46:39 -0500 Subject: [PATCH 35/44] Update docs/guides/configure-error-mitigation.mdx Co-authored-by: abbycross --- docs/guides/configure-error-mitigation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 592f65ae31a..dd4488562bb 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -364,7 +364,7 @@ With the V2 primitives, you can turn on and off individual error mitigation and - Not all options are available for both primitives. See the [available options table](runtime-options-overview#options-table) for the list of available options. -- Not all methods work together on all types of circuits. See the [options compatibility](runtime-options-overview#options-compatibility-table) table for details. +- Not all methods work together on all types of circuits. See the [options compatibility table](runtime-options-overview#options-compatibility-table) for details. From 0c4e9b6e95095a6816654759ed00b6f1a43f9a7e Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 13:54:42 -0500 Subject: [PATCH 36/44] Update docs/guides/configure-error-suppression.mdx --- docs/guides/configure-error-suppression.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index 19e7a78c166..3ec88e292de 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -1,6 +1,7 @@ --- title: Configure error suppression -description: How to configure error suppression in Qiskit Runtime. (Previous topic - runtime compilation) +description: How to configure error suppression in Qiskit Runtime. (Former title: Runtime + compilation) --- From 2f45555d23d1862532ffffd886b7619411721df8 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 31 Jul 2024 13:57:44 -0500 Subject: [PATCH 37/44] update title spacing --- docs/guides/configure-error-suppression.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index 3ec88e292de..d7838b3b489 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -1,7 +1,6 @@ --- title: Configure error suppression -description: How to configure error suppression in Qiskit Runtime. (Former title: Runtime - compilation) +description: How to configure error suppression in Qiskit Runtime. (Former title: Runtime compilation) --- From 19c3b9dab8bbdca58890531e90016fa3e1fa3a17 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 14:02:54 -0500 Subject: [PATCH 38/44] Apply suggestions from code review Co-authored-by: abbycross --- docs/guides/configure-error-suppression.mdx | 4 ++-- docs/guides/primitives.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index d7838b3b489..b0bcbc84d43 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -8,9 +8,9 @@ description: How to configure error suppression in Qiskit Runtime. (Former title Error suppression refers to techniques where you use knowledge about the undesirable effects to introduce customization that can anticipate and avoid the potential impacts of those effects. These techniques often consist of altering or adding control signals to ensure that the quantum processor returns the desired results. This typically results in quantum pre-processing overhead; therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time. -V2 primitives support a number of error suppression techniques, including [dynamical decoupling](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions#dynamicaldecouplingoptions) and Pauli [twirling](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. In V2 primitives, you can turn on or off individual method. See the [Advanced error suppression options](#transpilation-table) section for details. +V2 primitives support a number of error suppression techniques, including [dynamical decoupling](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions#dynamicaldecouplingoptions) and [Pauli twirling](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. In V2 primitives, you can turn on or off individual methods. See the [Advanced error suppression options](#transpilation-table) section for details. -Estimator V2 employs error suppression and mitigation by default. If you don't want any processing done to your input circuits follow the instructions in the [Turn off all error mitigation and error suppression](specify-runtime-options#no-error-mitigation) section. +Estimator V2 employs error suppression and mitigation by default. If you don't want any processing done to your input circuits, follow the instructions in the [Turn off all error mitigation and error suppression](specify-runtime-options#no-error-mitigation) section. To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the QPU (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives. See the [transpilation documentation](./transpile) for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set `optimization_level=0`. diff --git a/docs/guides/primitives.mdx b/docs/guides/primitives.mdx index 7c77ad1abe9..37d31cfefb8 100644 --- a/docs/guides/primitives.mdx +++ b/docs/guides/primitives.mdx @@ -68,7 +68,7 @@ Version 2 (available with `qiskit-ibm-runtime` 0.21.0 and later) is the first ma * You can **turn on or off individual error mitigation and suppression methods**. * You can choose to **get counts or per-shot measurements** instead of quasi-probabilities from Sampler V2. * Due to scaling issues, Sampler V2 does not support specifying a resilience level, and Estimator V2 supports only levels 0 - 2. -* To reduce the total execution time, v2 primitives only support ISA circuits. You can use the [Qiskit transpiler](./transpile) (manually) or the [AI-driven transpilation service (premium users)](./qiskit-transpiler-service) to transform the circuits before making the queries to the primitives. +* To reduce the total execution time, V2 primitives only support ISA circuits. You can use the [Qiskit transpiler](./transpile) (manually) or the [AI-driven transpilation service (for Premium Plan users)](./qiskit-transpiler-service) to transform the circuits before making queries to the primitives. See the [EstimatorV2 API reference](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.EstimatorV2) and [SamplerV2 API reference](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.SamplerV2) for full details. From 522df10d9092e6ea026376026f915019f95feba8 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 14:13:55 -0500 Subject: [PATCH 39/44] Update docs/guides/primitives.mdx --- docs/guides/primitives.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/primitives.mdx b/docs/guides/primitives.mdx index 37d31cfefb8..f4ace343029 100644 --- a/docs/guides/primitives.mdx +++ b/docs/guides/primitives.mdx @@ -51,7 +51,7 @@ service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl") ## Benefits of Qiskit primitives -For Qiskit users, primitives let you write quantum code for a specific system without having to explicitly +For Qiskit users, primitives let you write quantum code for a specific QPU without having to explicitly manage every detail. Also, because of the additional layer of abstraction, you might be able to more easily access advanced hardware capabilities of a given provider. For example, with Qiskit Runtime primitives, you can leverage the latest advancements in error mitigation and suppression by toggling options such as `resilience_level`, rather than building your own implementation of these techniques. From 37e1b4f207f890890e2c5abe77ad82e1e8a25657 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 14:14:42 -0500 Subject: [PATCH 40/44] Update docs/guides/configure-error-suppression.mdx --- docs/guides/configure-error-suppression.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index b0bcbc84d43..25eb90caccf 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -1,6 +1,6 @@ --- title: Configure error suppression -description: How to configure error suppression in Qiskit Runtime. (Former title: Runtime compilation) +description: How to configure error suppression in Qiskit Runtime. (Former title - Runtime compilation) --- From 5f190eac0bd1768f77f893d29c4c576afa049932 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 14:17:12 -0500 Subject: [PATCH 41/44] Update docs/guides/runtime-options-overview.mdx Co-authored-by: abbycross --- docs/guides/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index b34b58ef49e..bcfef58de4f 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -30,7 +30,7 @@ When calling the primitives, you can pass in options by using an options class o ### Defaults For V2 primitives, if you do not specify a value for an option, it is given a special value of `Unset` and the server default value is used. Thus, the default value will be the same regardless of your code version. -For V1 primitives, if you do not specify a value for an option, the Qiskit Runtime client's default value is used. In V1, the default value is dependant on the code version. +For V1 primitives, if you do not specify a value for an option, the Qiskit Runtime client's default value is used. In V1, the default value is dependent on the code version. The tables in the [Options classes summary](#options-classes) section lists the default values. From 26163415287af06c54fa53c4c8cab986a6992f37 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 14:17:25 -0500 Subject: [PATCH 42/44] Update docs/guides/runtime-options-overview.mdx Co-authored-by: abbycross --- docs/guides/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index bcfef58de4f..c1d4577b1ad 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -48,7 +48,7 @@ Options can be defined before a primitive is constructed and passed to the primi - [Dynamical decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions): Options for dynamical decoupling. - [Execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2): Primitive execution options, including whether to initialize qubits and the repetition delay. - [Twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions): Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. - - [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions): Execution environment options such as the logging level to set and job tags to add. + - [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions): Execution environment options, such as the logging level to set and job tags to add. - [Simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions): Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to local testing mode only. From ccea93f78c36e94a931bb342f17a785c99d56f1e Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 14:17:41 -0500 Subject: [PATCH 43/44] Update docs/guides/runtime-options-overview.mdx Co-authored-by: abbycross --- docs/guides/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index c1d4577b1ad..5020e2d97b3 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -56,7 +56,7 @@ Options can be defined before a primitive is constructed and passed to the primi - [Dynamical decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions): Options for dynamical decoupling. - [Execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2): Primitive execution options, including whether to initialize qubits and the repetition delay. - [Twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions): Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. - - [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions): Execution environment options such as the logging level to set and job tags to add. + - [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions): Execution environment options, such as the logging level to set and job tags to add. - [Simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions): Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to local testing mode only. From 508660204c12efa535c8f36274583b7ebc8cd14f Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Wed, 31 Jul 2024 14:17:53 -0500 Subject: [PATCH 44/44] Update docs/guides/runtime-options-overview.mdx Co-authored-by: abbycross --- docs/guides/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 5020e2d97b3..fe5cf9a7980 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -65,7 +65,7 @@ Options can be defined before a primitive is constructed and passed to the primi - [Dynamical decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions): Options for dynamical decoupling. - [Execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptions): Primitive execution options, including whether to initialize qubits and the repetition delay. - [Twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions): Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. - - [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions): Execution environment options such as the logging level to set and job tags to add. + - [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions): Execution environment options, such as the logging level to set and job tags to add. - [Simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions): Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to **local testing mode only**.