From 759616238636840d1229727db46d3c87c3bf047c Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 5 Jun 2024 11:25:27 -0500 Subject: [PATCH 01/63] rename files and update links --- .../qiskit-quantum-instance.mdx | 8 ++--- .../qiskit-runtime-examples.mdx | 26 +++++++------- .../qiskit-runtime-options.mdx | 4 +-- .../qiskit-runtime-use-case.mdx | 14 ++++---- docs/run/_toc.json | 12 +++---- ...on.mdx => configure-error-suppression.mdx} | 0 docs/run/minimize-time.mdx | 2 +- docs/run/primitives-examples.mdx | 2 +- docs/run/primitives.mdx | 36 +++++++++---------- ...tions.mdx => runtime-options-overview.mdx} | 6 ++-- .../defaults-and-configuration-options.ipynb | 2 +- docs/transpile/index.mdx | 4 +-- scripts/patterns-reorg/redirects.json | 4 +-- 13 files changed, 60 insertions(+), 60 deletions(-) rename docs/run/{configure-runtime-compilation.mdx => configure-error-suppression.mdx} (100%) rename docs/run/{advanced-runtime-options.mdx => runtime-options-overview.mdx} (97%) diff --git a/docs/api/migration-guides/qiskit-quantum-instance.mdx b/docs/api/migration-guides/qiskit-quantum-instance.mdx index 1b9cdef1560..9a5a7501e0d 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 @@ -122,8 +122,8 @@ primitives expose a similar setting through their interface: | Measurement error mitigation: `measurement_error_mitigation_cls`, `cals_matrix_refresh_period`, | No | No | Sampler default > M3 (*) | No | | Job management: `job_callback`, `max_job_retries`, `timeout`, `wait` | Does not apply | Does not apply | Sessions, callback (**) | No | -(\*) For more information on error mitigation and setting options on Qiskit Runtime Primitives, see -[Advanced Runtime Options](../../run/advanced-runtime-options). +(\*) For more information on error mitigation and setting options on Qiskit Runtime Primitives, see the Qiskit Runtime options +[overview](../../run/runtime-options-overview). (\*\*) For more information on Runtime sessions, see [About Sessions](../../run/sessions). diff --git a/docs/api/migration-guides/qiskit-runtime-examples.mdx b/docs/api/migration-guides/qiskit-runtime-examples.mdx index 5a35dfab840..5d706e635e5 100644 --- a/docs/api/migration-guides/qiskit-runtime-examples.mdx +++ b/docs/api/migration-guides/qiskit-runtime-examples.mdx @@ -60,7 +60,7 @@ service = QiskitRuntimeService() # Get a backend backend = service.least_busy(operational=True, simulator=False) -# Define Estimator +# Define Estimator estimator = Estimator(backend) # Run an expectation value calculation @@ -77,10 +77,10 @@ from qiskit_ibm_runtime.fake_provider import FakeManilaV2 # Run the sampler job locally using FakeManilaV2 fake_manila = FakeManilaV2() -# You can use a fixed seed to get fixed results. +# You can use a fixed seed to get fixed results. options = {"simulator": {"seed_simulator": 42}} -# Define Estimator +# Define Estimator estimator = Estimator(backend=fake_manila, options=options) # Run an expectation value calculation @@ -225,7 +225,7 @@ 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 @@ -256,7 +256,7 @@ expectation: -1.065734058826613 -## Use Sampler to design an algorithm +## Use Sampler to design an algorithm The Sampler primitive is used to design an algorithm that samples circuits and extracts probability distributions. @@ -286,7 +286,7 @@ difference is the format of the output: `backend.run()` outputs # Run result = backend.run(isa_circuits) ``` - + @@ -334,10 +334,10 @@ from qiskit_ibm_runtime.fake_provider import FakeManilaV2 # Run the sampler job locally using FakeManilaV2 fake_manila = FakeManilaV2() -# You can use a fixed seed to get fixed results. +# You can use a fixed seed to get fixed results. options = {"simulator": {"seed_simulator": 42}} -# Define Sampler +# Define Sampler sampler = Sampler(backend=fake_manila, options=options) # Run calculation @@ -366,7 +366,7 @@ When using the `Sampler` primitive, the circuit **must contain measurements**. ``` python from qiskit_ibm_runtime import SamplerV2 as Sampler - + # Define a local backend from qiskit_ibm_runtime.fake_provider import FakeManilaV2 backend = FakeManilaV2() @@ -438,11 +438,11 @@ result = job.result() # Get results for the first (and only) PUB pub_result = result[0] -# Get counts from the classical register "meas". +# Get counts from the classical register "meas". print(f" >> Meas output register counts: {pub_result.data.meas.get_counts()}") ->> Meas output register counts: {'0001': 210, '0010': 305, '0000': 282, '0011': 201, '0101': 2, '1010': 6, '0110': 5, '0100': 6, '1000': 3, '0111': 1, '1001': 2, '1011': 1} -``` +>> Meas output register counts: {'0001': 210, '0010': 305, '0000': 282, '0011': 201, '0101': 2, '1010': 6, '0110': 5, '0100': 6, '1000': 3, '0111': 1, '1001': 2, '1011': 1} +``` @@ -502,7 +502,7 @@ to the following: - [Common use cases](qiskit-runtime-use-case) - [Migrate `backend.run` options to primitive options](qiskit-runtime-options) -- [Setting execution options](../../run/advanced-runtime-options) +- [Qiskit Runtime options overview](../../run/runtime-options-overview) - [Primitive execution options API reference](../qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) - [How to run a session](../../run/run-jobs-in-session) - [Qiskit Runtime local testing mode](../../verify/local-testing-mode) diff --git a/docs/api/migration-guides/qiskit-runtime-options.mdx b/docs/api/migration-guides/qiskit-runtime-options.mdx index 6d5f076c44c..896b3b3bb6e 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](../../run/advanced-runtime-options) 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 [Qiskit Runtime options overview](../../run/runtime-options-overview) for more information about specifying V2 primitives options. | backend.run options | V2 Primitive options | Notes | |---------------------|-----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| @@ -43,4 +43,4 @@ All `backend.run` options are now available through the Qiskit Runtime primitive One of the advantages of the primitives is that they abstract away the circuit execution setup so that algorithm developers can focus on the pure algorithmic components. However, sometimes, to get the most out of -an algorithm, you might want to tune certain primitive options. For details, see [Advanced runtime options.](../../run/advanced-runtime-options) +an algorithm, you might want to tune certain primitive options. For details, see the [Qiskit Runtime options overview.](../../run/runtime-options-overview) diff --git a/docs/api/migration-guides/qiskit-runtime-use-case.mdx b/docs/api/migration-guides/qiskit-runtime-use-case.mdx index 22a0e3a5199..c116f2c01ec 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. @@ -45,7 +45,7 @@ result = job.result() ## Specifying options -All options that were available with `backend.run` are available in the Qiskit Runtime primitives, but they are specified differently. For more information, see [Migrate options](qiskit-runtime-options) and [Advanced Qiskit Runtime options.](../../run/advanced-runtime-options) +All options that were available with `backend.run` are available in the Qiskit Runtime primitives, but they are specified differently. For more information, see [Migrate options](qiskit-runtime-options) and the [Qiskit Runtime options overview.](../../run/runtime-options-overview) @@ -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/run/_toc.json b/docs/run/_toc.json index 842a6234db4..6e0f5650064 100644 --- a/docs/run/_toc.json +++ b/docs/run/_toc.json @@ -27,16 +27,16 @@ "title": "Configure runtime options", "children": [ { - "title": "Configure runtime compilation", - "url": "/run/configure-runtime-compilation" + "title": "Overview", + "url": "/run/runtime-options-overview" }, { - "title": "Configure runtime error mitigation", - "url": "/run/configure-error-mitigation" + "title": "Configure runtime error suppression", + "url": "/run/configure-error-suppression" }, { - "title": "Advanced runtime options", - "url": "/run/advanced-runtime-options" + "title": "Configure runtime error mitigation", + "url": "/run/configure-error-mitigation" } ] }, diff --git a/docs/run/configure-runtime-compilation.mdx b/docs/run/configure-error-suppression.mdx similarity index 100% rename from docs/run/configure-runtime-compilation.mdx rename to docs/run/configure-error-suppression.mdx diff --git a/docs/run/minimize-time.mdx b/docs/run/minimize-time.mdx index 0517623227c..b867a800f69 100644 --- a/docs/run/minimize-time.mdx +++ b/docs/run/minimize-time.mdx @@ -12,7 +12,7 @@ There are several ways you can limit the amount of quantum time spent processing - Set limits on execution time: You can limit how long each job or session runs. For details, see [Maximum execution time for a Qiskit Runtime job or session](max-execution-time). -- Use only the necessary settings for error suppression, error mitigation, and optimization, because higher values can cause your jobs to run longer. See [Algorithm tuning options](advanced-runtime-options), [Configure runtime compilation](configure-runtime-compilation), and [Configure error mitigation](configure-error-mitigation) for details. +- Use only the necessary settings for error suppression, error mitigation, and optimization, because higher values can cause your jobs to run longer. See the [Qiskit Runtime options overview](runtime-options-overview), [Configure error suppression](configure-error-suppression), and [Configure error mitigation](configure-error-mitigation) for details. ## Next steps diff --git a/docs/run/primitives-examples.mdx b/docs/run/primitives-examples.mdx index 0c018cd97e4..d93d8a2b6b7 100644 --- a/docs/run/primitives-examples.mdx +++ b/docs/run/primitives-examples.mdx @@ -766,7 +766,7 @@ print(f" > Quasi-probability distribution job 2: {another_result.quasi_dists}") - Read [Migrate to V2 primitives](/api/migration-guides/v2-primitives). - - [Specify advanced runtime options.](advanced-runtime-options) + - [Specify advanced runtime options.](runtime-options-overview) - 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. diff --git a/docs/run/primitives.mdx b/docs/run/primitives.mdx index 10383d3e5bc..41feeaceb48 100644 --- a/docs/run/primitives.mdx +++ b/docs/run/primitives.mdx @@ -61,17 +61,17 @@ best capabilities. 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: -* The **new interface** lets you specify a single circuit and multiple observables (if using Estimator) and parameter value sets for that circuit. +* 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](advanced-runtime-options#runtime-compilation) (manually) or the [AI-driven transpilation service (premium users)](../transpile/qiskit-transpiler-service) to transform the circuits before making the queries to the primitives. +* 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)](../transpile/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. ### Interface changes -The updated interface uses a *primitive unified bloc* (PUB) for input. Each PUB is a tuple that contains a circuit and the data broadcasted to it. This greatly simplifies your ability to send complex data to a circuit. Previously, you had to specify the same circuit multiple times to match the size of the data to be combined. A summary of the changes to each primitive follows. +The updated interface uses a *primitive unified bloc* (PUB) for input. Each PUB is a tuple that contains a circuit and the data broadcasted to it. This greatly simplifies your ability to send complex data to a circuit. Previously, you had to specify the same circuit multiple times to match the size of the data to be combined. A summary of the changes to each primitive follows. #### Estimator V1 @@ -80,7 +80,7 @@ The updated interface uses a *primitive unified bloc* (PUB) for input. Each PUB * The length of the parameters must match. * Elements from each are aggregated. -Example: +Example: ```python estimator.run([circuit1, circuit2, ...],[observable1, observable2, ...], @@ -90,10 +90,10 @@ estimator.run([circuit1, circuit2, ...],[observable1, observable2, ...], #### Estimator V2 * The `run()` method takes an array of PUBs. Each PUB is in the format (``, ``, ``, ``), where the optional `parameter values` can be a list or a single parameter. -* Combines elements from observables and parameter values by following NumPy broadcasting rules as described below. +* Combines elements from observables and parameter values by following NumPy broadcasting rules as described below. * Each input PUB has a corresponding PubResult that contains both data and metadata. -Example: +Example: ```python estimator.run([(circuit1, observable1, param_values1),(circuit2, observable2, param_values2)]) @@ -106,8 +106,8 @@ Estimator V2 aggregates elements from multiple arrays (observables and parameter Rules: -* Input arrays do not need to have the same number of dimensions. - * The resulting array will have the same number of dimensions as the input array with the largest dimension. +* Input arrays do not need to have the same number of dimensions. + * The resulting array will have the same number of dimensions as the input array with the largest dimension. * The size of each dimension is the largest size of the corresponding dimension. * Missing dimensions are assumed to have size one. * Shape comparisons start with the rightmost dimension and continue to the left. @@ -130,13 +130,13 @@ Examples of array pairs that do not broadcast: ```text A1 (1d array): 5 -A2 (1d array): 3 +A2 (1d array): 3 A1 (2d array): 2 x 1 A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5. ``` -`EstimatorV2` returns one expectation value estimate for each element of the broadcasted shape. +`EstimatorV2` returns one expectation value estimate for each element of the broadcasted shape. Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows: @@ -192,7 +192,7 @@ list2 = [SparsePauliOp("XX"), SparsePauliOp("XY"), SparsePauliOp("IZ")] # shape * The length of the parameters must match. * Elements from each are aggregated. -Example: +Example: ```python sampler.run([circuit1, circuit2, ...],[observable1, observable2, ...],[param_values1, param_values2, ...] ) @@ -202,7 +202,7 @@ sampler.run([circuit1, circuit2, ...],[observable1, observable2, ...],[param_val * Takes one parameter: PUBs in the format (``, ``, ``), where there can be multiple `parameter values` items, and each item can be either an array or a single parameter, depending on the chosen circuit. * Elements from each are aggregated. For example, each array of parameter values in the PUB is applied to the PUB's circuit. -* Obeys program outputs. Typically this is a bit array but can also be an array of complex numbers (measurement level 1). +* Obeys program outputs. Typically this is a bit array but can also be an array of complex numbers (measurement level 1). * Returns raw data type. Data from each shot is returned (analogous to `memory=True` in the `backend.run` interface), and post-processing is done by using convenience methods. * Output data is grouped by output registers. You need the classical register name to get the results. By default, it is named `meas` if you use `measure_all()`. You can find the classical register name by running `.cregs`. For example, `qc.cregs`. * Supports circuits with classical feedforward and control flow (dynamic circuits). @@ -210,7 +210,7 @@ sampler.run([circuit1, circuit2, ...],[observable1, observable2, ...],[param_val Dynamic circuits do not support dynamical decoupling. -Example: +Example: ```python sampler.run([ @@ -221,7 +221,7 @@ sampler.run([ ## Estimator -The Estimator behaves differently, depending on what version you are using. +The Estimator behaves differently, depending on what version you are using. @@ -242,12 +242,12 @@ can be parametrized, as long as the parameter values are also provided as input ## Sampler -The Sampler behaves differently, depending on what version you are using. +The Sampler behaves differently, depending on what version you are using. - Sampler V2 is simplified to focus on its core task of sampling the output register from execution of quantum circuits. It returns the samples, whose type is defined by the program, without weights and therefore does not support resilience levels. The result class, however, has methods to return weighted samples, such as counts. - + Sampler V2 is simplified to focus on its core task of sampling the output register from execution of quantum circuits. It returns the samples, whose type is defined by the program, without weights and therefore does not support resilience levels. The result class, however, has methods to return weighted samples, such as counts. + It receives one or more PUBs as the inputs and returns counts or per-shot measurements, as `PubResult`s. The circuits can be parametrized, as long as the parameter values are also provided as input to the primitive. diff --git a/docs/run/advanced-runtime-options.mdx b/docs/run/runtime-options-overview.mdx similarity index 97% rename from docs/run/advanced-runtime-options.mdx rename to docs/run/runtime-options-overview.mdx index 3c812dfe9cd..9a64ca935d7 100644 --- a/docs/run/advanced-runtime-options.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -209,7 +209,7 @@ The Qiskit Runtime primitives expect to be called with circuits already suitable The Qiskit Runtime primitives may perform additional runtime compilation to optimize circuits, with the degree of optimization controlled by an optimization level option. The optimization level you choose affects the compilation strategy, with higher levels invoking more expensive or aggressive optimizations. See the Optimization level table in the -[Runtime compilation topic](configure-runtime-compilation#set-the-optimization-level) for further details. +[Configure error suppression topic](configure-error-suppression#set-the-optimization-level) for further details. @@ -258,7 +258,7 @@ 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-runtime-compilation#transpilation-table). +[Configure error suppression topic](configure-error-suppression#transpilation-table). @@ -321,7 +321,7 @@ estimator = Estimator(session=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-runtime-compilation) and [error mitigation](configure-error-mitigation). + - 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. diff --git a/docs/transpile/defaults-and-configuration-options.ipynb b/docs/transpile/defaults-and-configuration-options.ipynb index 6ea17400233..a82e8b009a6 100644 --- a/docs/transpile/defaults-and-configuration-options.ipynb +++ b/docs/transpile/defaults-and-configuration-options.ipynb @@ -238,7 +238,7 @@ "\n", " - Learn how to [Set the optimization level](set-optimization).\n", " - Review more [Commonly used parameters](common-parameters).\n", - " - Learn how to [Set the optimization level when using Qiskit Runtime.](../run/advanced-runtime-options)\n", + " - Learn how to [Set the optimization level when using Qiskit Runtime.](../run/runtime-options-overview)\n", " - Visit the [Transpile with pass managers](transpile-with-pass-managers) topic.\n", " - For examples, see [Representing quantum computers.](representing_quantum_computers)\n", " - Try the [Submit transpiled circuits](https://learning.quantum.ibm.com/tutorial/submit-transpiled-circuits) tutorial.\n", diff --git a/docs/transpile/index.mdx b/docs/transpile/index.mdx index 0202dad6e8f..0ee92ead1b0 100644 --- a/docs/transpile/index.mdx +++ b/docs/transpile/index.mdx @@ -7,7 +7,7 @@ description: Introduction to transpiling quantum circuits in the Qiskit SDK. # Introduction to transpilation -Transpilation is the process of rewriting a given input circuit to match the topology of a specific quantum device, and optimize the circuit instructions for execution on noisy quantum systems. This documentation covers the tooling and workflows for local transpilation available to all Qiskit users, as well as for the cloud-based [Qiskit transpiler service](qiskit-transpiler-service) available to Premium Plan users. If you're using primitives and are only interested in the default transpilation options provided by the Qiskit Runtime service, read the [Configure runtime compilation for Qiskit Runtime](../run/configure-runtime-compilation) topic. +Transpilation is the process of rewriting a given input circuit to match the topology of a specific quantum device, and optimize the circuit instructions for execution on noisy quantum systems. This documentation covers the tooling and workflows for local transpilation available to all Qiskit users, as well as for the cloud-based [Qiskit transpiler service](qiskit-transpiler-service) available to Premium Plan users. If you're using primitives and are only interested in the default transpilation options provided by the Qiskit Runtime service, read the [Configure error suppression for Qiskit Runtime](../run/configure-error-suppression) topic. The process of transpilation takes circuit that contains your instructions: @@ -28,7 +28,7 @@ In addition to reducing the depth and complexity of quantum circuits, the transp - If you perform transpilation locally and submit the transpiled circuits to the Qiskit Runtime Estimator primitive, the service tries to apply additional optimizations by default, corresponding to `optimization_level=1` described [here](/run/configure-runtime-compilation#set-the-optimization-level). If you do not want the circuits further transformed, set the `optimization_level` to 0. + If you perform transpilation locally and submit the transpiled circuits to the Qiskit Runtime Estimator primitive, the service tries to apply additional optimizations by default, corresponding to `optimization_level=1` described in the [Configure error suppression](/run/configure-error-suppression#set-the-optimization-level) topic. If you do not want the circuits further transformed, set the `optimization_level` to 0. diff --git a/scripts/patterns-reorg/redirects.json b/scripts/patterns-reorg/redirects.json index edb106cd788..42ac177f414 100644 --- a/scripts/patterns-reorg/redirects.json +++ b/scripts/patterns-reorg/redirects.json @@ -40,9 +40,9 @@ "run/primitives": "primitives", "run/primitives-get-started": "get-started-with-primitives", "run/primitives-examples": "primitives-examples", - "run/configure-runtime-compilation": "configure-runtime-compilation", + "run/configure-runtime-compilation": "configure-error-suppression", "run/configure-error-mitigation": "configure-error-mitigation", - "run/advanced-runtime-options": "advanced-runtime-options", + "run/advanced-runtime-options": "runtime-options-overview", "run/execution-modes": "execution-modes", "run/sessions": "sessions", "run/run-jobs-in-session": "run-jobs-session", From 40f516b37df369cfe5c23de33ee40bdd184e546d Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 5 Jun 2024 12:21:19 -0500 Subject: [PATCH 02/63] update table --- docs/run/runtime-options-overview.mdx | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 9a64ca935d7..9b60fed7aa0 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -306,15 +306,20 @@ estimator = Estimator(session=backend, options=options) ## Options classes -| 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` | - +| Category | Description | +|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| [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 From dbc738d2370d8e0f86e86c29caacf80c13413954 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 5 Jun 2024 13:53:55 -0500 Subject: [PATCH 03/63] Add new sections --- docs/run/runtime-options-overview.mdx | 118 +++++++++++++++++++++----- 1 file changed, 96 insertions(+), 22 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 9b60fed7aa0..65d6ee1435e 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/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 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. + 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`. @@ -18,10 +19,100 @@ 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. - + +## 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`. + + +## Defaults + +client default (Unset) and where to find server defaults + + +## Precedence rules + +option precedence rules + + +## Options classes + + + +| Category | Description | +|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| [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` | + + + + +| Category | Description | +|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| [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` | + + + + +| Category | Description | +|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| [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**. | +| | `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.ExecutionOptions) | 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` | + + + + +| Category | Description | +|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| [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**. | +| | `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.ExecutionOptions) | 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` | + + + + + + + + ## V2 changes Options are specified differently in the V2 primitives in these ways: @@ -303,23 +394,6 @@ estimator = Estimator(session=backend, options=options) - -## Options classes - -| Category | Description | -|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| -| [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 From 7c9652002db39365167986686d3cc3508a7ed4f6 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 6 Jun 2024 11:13:39 -0500 Subject: [PATCH 04/63] update file names in entries.py --- scripts/patterns-reorg/entries.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/scripts/patterns-reorg/entries.py b/scripts/patterns-reorg/entries.py index 79bd44eea46..7b62a2dfcfe 100644 --- a/scripts/patterns-reorg/entries.py +++ b/scripts/patterns-reorg/entries.py @@ -342,9 +342,9 @@ "Configure runtime options", children=( Entry( - "Configure runtime compilation", - slug="/configure-runtime-compilation", - from_file="run/configure-runtime-compilation.mdx", + "Configure error suppression", + slug="/configure-error-suppression", + from_file="run/configure-error-suppression.mdx", ), Entry( "Configure runtime error mitigation", @@ -352,9 +352,9 @@ from_file="run/configure-error-mitigation.mdx", ), Entry( - "Advanced runtime options", - slug="/advanced-runtime-options", - from_file="run/advanced-runtime-options.mdx", + "Qiskit Runtime options overview", + slug="/runtime-options-overview", + from_file="run/runtime-options-overview.mdx", ), ), ), From 2d4c33fe80cfe18ed0552be52812a9e5efd3eac1 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 6 Jun 2024 11:21:29 -0500 Subject: [PATCH 05/63] change IDs to appease spell check --- docs/run/runtime-options-overview.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 65d6ee1435e..6e3484616c8 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -38,7 +38,7 @@ option precedence rules ## Options classes - + | Category | Description | |---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| | [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**. | @@ -56,7 +56,7 @@ option precedence rules - + | Category | Description | |---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| | [Dynamical decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions) | Options for dynamical decoupling. | @@ -72,7 +72,7 @@ option precedence rules - + | Category | Description | |---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| | [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**. | @@ -90,7 +90,7 @@ option precedence rules - + | Category | Description | |---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| | [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**. | From dd3679c535d122a4ae7dadcaa1ab4bedfa47461f Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 6 Jun 2024 11:29:42 -0500 Subject: [PATCH 06/63] Update qiskit_bot.yaml --- qiskit_bot.yaml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 0101f80a3f1..caceb68265c 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -157,7 +157,12 @@ notifications: - "@beckykd" - "@abbycross" - "`@blakejohnson`" - "docs/run/advanced-runtime-options": + "docs/run/configure-error-suppression": + - "@jyu00" + - "@beckykd" + - "@abbycross" + - "`@blakejohnson`" + "docs/run/runtime-options-overview": - "@jyu00" - "@beckykd" - "@abbycross" From 23b84818cf6b1f36c7f8b5e4a6e453a1532a0134 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 6 Jun 2024 11:47:42 -0500 Subject: [PATCH 07/63] update structure --- docs/run/configure-error-mitigation.mdx | 28 +----------- docs/run/configure-error-suppression.mdx | 5 ++- docs/run/runtime-options-overview.mdx | 56 ++++++++++++++++-------- 3 files changed, 43 insertions(+), 46 deletions(-) diff --git a/docs/run/configure-error-mitigation.mdx b/docs/run/configure-error-mitigation.mdx index 5fdb7529002..66850ea5f77 100644 --- a/docs/run/configure-error-mitigation.mdx +++ b/docs/run/configure-error-mitigation.mdx @@ -471,33 +471,9 @@ job = estimator.run(circuits=[psi1], observables=[H1], parameter_values=[theta1] psi1_H1 = job.result() ``` - -## Turn off all error mitigation and error suppression +## Turn off all error mitigation -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 -``` +For instructions to turn off all error mitigation, see the [Turn off all error suppression and mitigation](runtime-options-overivew#no-error-mitigation) section. ## Next steps diff --git a/docs/run/configure-error-suppression.mdx b/docs/run/configure-error-suppression.mdx index 2ea60ce348c..34b3eb764db 100644 --- a/docs/run/configure-error-suppression.mdx +++ b/docs/run/configure-error-suppression.mdx @@ -8,7 +8,7 @@ description: How to configure runtime compilation in Qiskit Runtime. Runtime compilation techniques optimize and 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 and, for Estimator V2, by setting the optimization level (`optimization_level`) option. If you don't want any processing done to minimize errors, follow the instructions in the [Turn off all error mitigation and error suppression](configure-error-mitigation#no-error-mitigation) section. +Primitives let you employ runtime compilation by choosing advanced runtime compilation options and, for Estimator V2, by setting the optimization level (`optimization_level`) option. 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. Estimator V2 supports optimization levels 0 and 1 only. Sampler V2 does not support setting the optimization level. @@ -164,6 +164,9 @@ 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-overivew#no-error-mitigation) section. ## Next steps diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 6e3484616c8..c95b1bbc382 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -19,18 +19,20 @@ service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl") ``` +## Overview + -## Structure +### 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`. -## Defaults +### Defaults client default (Unset) and where to find server defaults -## Precedence rules +### Precedence rules option precedence rules @@ -293,11 +295,11 @@ For more information about the primitive options, refer to the -### Runtime compilation +### Error suppression 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. -The Qiskit Runtime primitives may perform additional runtime compilation to optimize circuits, with the degree of optimization controlled by an optimization level option. The optimization level you choose affects the compilation strategy, with higher levels invoking more expensive or aggressive optimizations. +The Qiskit Runtime primitives may perform additional error suppression to optimize circuits, with the degree of optimization controlled by an optimization level option. The optimization level you choose affects the error suppression strategy, with higher levels invoking more expensive or aggressive optimizations. See the Optimization level table in the [Configure error suppression topic](configure-error-suppression#set-the-optimization-level) for further details. @@ -314,13 +316,11 @@ estimator = Estimator(session=backend, options={"optimization_level": 1}) # or.. estimator.options.optimization_level = 1 ``` - -To turn off all optional runtime compilation steps, you must set `optimization_level=0`. V2 primitives do not support any advanced transpilation options. - In the currently deployed 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. + In original (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: @@ -337,17 +337,6 @@ options.optimization_level = 1 estimator = Estimator(session=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(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). @@ -394,6 +383,35 @@ 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. + +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 +``` + + ## Next steps From af0b8677875df2c207d5fc1f09f5a51f0e4095eb Mon Sep 17 00:00:00 2001 From: Arnau Casau Date: Thu, 6 Jun 2024 21:17:28 +0200 Subject: [PATCH 08/63] change order ToC --- scripts/patterns-reorg/entries.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/scripts/patterns-reorg/entries.py b/scripts/patterns-reorg/entries.py index 7b62a2dfcfe..42e0ea55b83 100644 --- a/scripts/patterns-reorg/entries.py +++ b/scripts/patterns-reorg/entries.py @@ -341,6 +341,11 @@ Entry( "Configure runtime options", children=( + Entry( + "Qiskit Runtime options overview", + slug="/runtime-options-overview", + from_file="run/runtime-options-overview.mdx", + ), Entry( "Configure error suppression", slug="/configure-error-suppression", @@ -351,11 +356,6 @@ slug="/configure-error-mitigation", from_file="run/configure-error-mitigation.mdx", ), - Entry( - "Qiskit Runtime options overview", - slug="/runtime-options-overview", - from_file="run/runtime-options-overview.mdx", - ), ), ), ) From 1257967ffe4d0e7cd018dca0448051cffc9921e7 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Mon, 10 Jun 2024 13:33:46 -0500 Subject: [PATCH 09/63] two versions --- docs/run/_toc.json | 5 + docs/run/runtime-options-overview 2.mdx | 444 ++++++++++++++++++++++++ docs/run/runtime-options-overview.mdx | 160 ++++++--- 3 files changed, 555 insertions(+), 54 deletions(-) create mode 100644 docs/run/runtime-options-overview 2.mdx diff --git a/docs/run/_toc.json b/docs/run/_toc.json index 46aac91aac0..cfd55ea5ea9 100644 --- a/docs/run/_toc.json +++ b/docs/run/_toc.json @@ -30,6 +30,10 @@ "title": "Overview", "url": "/run/runtime-options-overview" }, + { + "title": "Overview2", + "url": "/run/runtime-options-overview2" + }, { "title": "Configure runtime error suppression", "url": "/run/configure-error-suppression" @@ -37,6 +41,7 @@ { "title": "Configure runtime error mitigation", "url": "/run/configure-error-mitigation" + }, { "title": "Error mitigation techniques", "url": "/run/error-mitigation-explanation" diff --git a/docs/run/runtime-options-overview 2.mdx b/docs/run/runtime-options-overview 2.mdx new file mode 100644 index 00000000000..8c2456d1bf0 --- /dev/null +++ b/docs/run/runtime-options-overview 2.mdx @@ -0,0 +1,444 @@ +--- +title: Advanced Qiskit Runtime options 2 +description: Specify options when building with Qiskit Runtime primitives + +--- + +# Advanced Qiskit Runtime options 2 + + You can pass options to primitives to customize them to meet your needs. 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. + + + +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`. + +*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") +``` + + +## 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`. + + +### Defaults + +client default (Unset) and where to find server defaults + + +### Precedence rules + +option precedence rules + + +## Options classes + + + + - [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**. + + + - [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**. + + + + +Specify options as follows: `primitive.options.option.sub-option.sub-sub-option = choice` + +Example: `estimator.options.dynamical_decoupling.enable = True` + +### option = resilience + + + +| Sub-options | Sub-sub-options | Choices | Default | +|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| measure_mitigation | | `True`/`False` | `True` | +| measure_noise_learning | num_randomizations | | `32` | +| | shots_per_randomization | | 'auto' | +| zne_mitigation | | `True`/`False` | `False` | +| zne | noise_factors | | `(1, 3, 5)` | +| | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | + + +| Sub-options | Sub-sub-options | Choices | Default | +|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| measure_mitigation | | `True`/`False` | `True` | +| measure_noise_learning | num_randomizations | | `32` | +| | shots_per_randomization | | 'auto' | +| zne_mitigation | | `True`/`False` | `False` | +| zne | noise_factors | | `(1, 3, 5)` | +| | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | + + +| Sub-options | Sub-sub-options | Choices | Default | +|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| measure_mitigation | | `True`/`False` | `True` | +| measure_noise_learning | num_randomizations | | `32` | +| | shots_per_randomization | | 'auto' | +| zne_mitigation | | `True`/`False` | `False` | +| zne | noise_factors | | `(1, 3, 5)` | +| | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | + + +| Sub-options | Sub-sub-options | Choices | Default | +|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| measure_mitigation | | `True`/`False` | `True` | +| measure_noise_learning | num_randomizations | | `32` | +| | shots_per_randomization | | 'auto' | +| zne_mitigation | | `True`/`False` | `False` | +| zne | noise_factors | | `(1, 3, 5)` | +| | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | + + + + +### option = default_shots + +### option = resilience_level + +### option = dynamical_decoupling + +### option = twirling + + + +## 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 +``` +## Pass options to 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. 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) + +# Setting options after primitive initialization +# This uses auto complete. +estimator.options.optimization_level = 1 +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) +result = estimator.run(circuit, observable).result() +print(f">>> Metadata: {result.metadata[0]}") +``` + + + +### Primitive initialization + +You can specify options 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}) +``` + + + +### 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. + + + +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. +```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(session=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. + + + + ```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). + + + + + + +### Error suppression + +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. + +The Qiskit Runtime primitives may perform additional error suppression to optimize circuits, with the degree of optimization controlled by an optimization level option. The optimization level you choose affects the error suppression strategy, with higher levels invoking more expensive or aggressive optimizations. + +See the Optimization level table in the +[Configure error suppression topic](configure-error-suppression#set-the-optimization-level) for further details. + + + + The optimization level option is a "first-level option". Sampler V2 does not currently support `optimization_level`. + +```python +from qiskit_ibm_runtime import EstimatorV2 as Estimator + +estimator = Estimator(session=backend, options={"optimization_level": 1}) + +# or.. +estimator.options.optimization_level = 1 +``` + + + + + In original (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: + +```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 + + +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). + + + +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.options.resilience_level = 2 +estimator.options.resilience.zne_mitigation = True +estimator.options.resilience.zne.noise_factors = [1, 3, 5] +``` + + + +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 = 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. + +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 +``` + + +## 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). + - 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. + diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index c95b1bbc382..010074c31ef 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -41,72 +41,124 @@ option precedence rules -| Category | Description | -|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| -| [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` | + - [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**. + + + - [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**. + + + +Specify options as follows: `primitive.options.option.sub-option.sub-sub-option = choice` + +Example: `estimator.options.dynamical_decoupling.enable = True` + + + +| Options | Sub-options | Sub-sub-options | Choices | Default | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| default_shots | | | | `4096` | +| optimization_level | | | `0`/`1` | `1` | +| resilience_level | | | `0`/`1`/`2` | `1` | +| dynamical_decoupling | enable | |`True`/`False` |`False` | +| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | +| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | +| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | +| resilience | measure_mitigation | | `True`/`False` | `True` | +| | measure_noise_learning | num_randomizations | | `32` | +| | | shots_per_randomization | | 'auto' | +| | zne_mitigation | | `True`/`False` | `False` | +| | zne | noise_factors | | `(1, 3, 5)` | +| | | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | +| twirling | enable_gates | | `True`/`False` | `False` | +| | enable_measure | | `True`/`False` | `True` | +| | num_randomizations | | | `'auto'` | +| | shots_per_randomization | | | `'auto'` | +| | strategy | | `'active'`/
`'active-circuit'`/
`'active-accum'`/
`'all'` | `'active-accum'` | -| Category | Description | -|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| -| [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` | +| Options | Sub-options | Sub-sub-options | Choices | Default | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| default_shots | | | | `4096` | +| optimization_level | | | `0`/`1` | `1` | +| dynamical_decoupling | enable | |`True`/`False` |`False` | +| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | +| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | +| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | +| twirling | enable_gates | | `True`/`False` | `False` | +| | enable_measure | | `True`/`False` | `True` | +| | num_randomizations | | | `'auto'` | +| | shots_per_randomization | | | `'auto'` | +| | strategy | | `'active'`/
`'active-circuit'`/
`'active-accum'`/
`'all'` | `'active-accum'` | -| Category | Description | -|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| -| [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**. | -| | `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.ExecutionOptions) | 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` | +| Options | Sub-options | Sub-sub-options | Choices | Default | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| default_shots | | | | `4096` | +| optimization_level | | | `0`/`1` | `1` | +| resilience_level | | | `0`/`1`/`2` | `1` | +| dynamical_decoupling | enable | |`True`/`False` |`False` | +| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | +| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | +| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | +| resilience | measure_mitigation | | `True`/`False` | `True` | +| | measure_noise_learning | num_randomizations | | `32` | +| | | shots_per_randomization | | 'auto' | +| | zne_mitigation | | `True`/`False` | `False` | +| | zne | noise_factors | | `(1, 3, 5)` | +| | | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | +| twirling | enable_gates | | `True`/`False` | `False` | +| | enable_measure | | `True`/`False` | `True` | +| | num_randomizations | | | `'auto'` | +| | shots_per_randomization | | | `'auto'` | +| | strategy | | `'active'`/
`'active-circuit'`/
`'active-accum'`/
`'all'` | `'active-accum'` | -| Category | Description | -|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| -| [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**. | -| | `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.ExecutionOptions) | 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` | +| Options | Sub-options | Sub-sub-options | Choices | Default | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| default_shots | | | | `4096` | +| optimization_level | | | `0`/`1` | `1` | +| dynamical_decoupling | enable | |`True`/`False` |`False` | +| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | +| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | +| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | +| twirling | enable_gates | | `True`/`False` | `False` | +| | enable_measure | | `True`/`False` | `True` | +| | num_randomizations | | | `'auto'` | +| | shots_per_randomization | | | `'auto'` | +| | strategy | | `'active'`/
`'active-circuit'`/
`'active-accum'`/
`'all'` | `'active-accum'` | From b6653fcb43857c4aafa45fcd72796d2903dd5622 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Mon, 10 Jun 2024 15:03:40 -0500 Subject: [PATCH 10/63] make build happy --- docs/run/_toc.json | 2 +- qiskit_bot.yaml | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/run/_toc.json b/docs/run/_toc.json index cfd55ea5ea9..911aba5fd20 100644 --- a/docs/run/_toc.json +++ b/docs/run/_toc.json @@ -32,7 +32,7 @@ }, { "title": "Overview2", - "url": "/run/runtime-options-overview2" + "url": "/run/runtime-options-overview 2" }, { "title": "Configure runtime error suppression", diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index ee03b38053e..8976e8b3b6a 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -167,6 +167,11 @@ notifications: - "@beckykd" - "@abbycross" - "`@blakejohnson`" + "docs/run/runtime-options-overview 2": + - "@jyu00" + - "@beckykd" + - "@abbycross" + - "`@blakejohnson`" "docs/run/error-mitigation-explanation": - "@kevinsung" "docs/run/sessions": From 34e1909a610d75f4104e8155d5bcd96abc526932 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Mon, 10 Jun 2024 15:14:11 -0500 Subject: [PATCH 11/63] links --- docs/run/configure-error-mitigation.mdx | 2 +- docs/run/configure-error-suppression.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/run/configure-error-mitigation.mdx b/docs/run/configure-error-mitigation.mdx index 66850ea5f77..bdfe71fec76 100644 --- a/docs/run/configure-error-mitigation.mdx +++ b/docs/run/configure-error-mitigation.mdx @@ -473,7 +473,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-overivew#no-error-mitigation) section. +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/run/configure-error-suppression.mdx b/docs/run/configure-error-suppression.mdx index 34b3eb764db..006a04a2d91 100644 --- a/docs/run/configure-error-suppression.mdx +++ b/docs/run/configure-error-suppression.mdx @@ -166,7 +166,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-overivew#no-error-mitigation) section. +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 From c2915fab3bcdb77a4c4e9dd46dea04be6d3dd161 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Mon, 10 Jun 2024 15:50:10 -0500 Subject: [PATCH 12/63] fix link --- docs/run/configure-error-suppression.mdx | 6 +++--- docs/run/primitives.mdx | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/run/configure-error-suppression.mdx b/docs/run/configure-error-suppression.mdx index 006a04a2d91..ce436332e8d 100644 --- a/docs/run/configure-error-suppression.mdx +++ b/docs/run/configure-error-suppression.mdx @@ -1,10 +1,10 @@ --- -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 optimize and 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. diff --git a/docs/run/primitives.mdx b/docs/run/primitives.mdx index 41feeaceb48..4da71430151 100644 --- a/docs/run/primitives.mdx +++ b/docs/run/primitives.mdx @@ -65,7 +65,7 @@ Version 2 (available with qiskit-ibm-runtime 0.21.0) is the first major interfac * 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)](../transpile/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/transpile-with-pass-managers) (manually) or the [AI-driven transpilation service (premium users)](../transpile/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. From 1976beb4333c7b592ccb4d14673cffe31e5edf6f Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Mon, 10 Jun 2024 16:00:45 -0500 Subject: [PATCH 13/63] trying something else for the br tags --- docs/run/runtime-options-overview.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 010074c31ef..089349d83d3 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -96,12 +96,12 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | | | shots_per_randomization | | 'auto' | | | zne_mitigation | | `True`/`False` | `False` | | | zne | noise_factors | | `(1, 3, 5)` | -| | | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | +| | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | | twirling | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | | `'auto'` | | | shots_per_randomization | | | `'auto'` | -| | strategy | | `'active'`/
`'active-circuit'`/
`'active-accum'`/
`'all'` | `'active-accum'` | +| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | @@ -117,7 +117,7 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | | `'auto'` | | | shots_per_randomization | | | `'auto'` | -| | strategy | | `'active'`/
`'active-circuit'`/
`'active-accum'`/
`'all'` | `'active-accum'` | +| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | @@ -136,12 +136,12 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | | | shots_per_randomization | | 'auto' | | | zne_mitigation | | `True`/`False` | `False` | | | zne | noise_factors | | `(1, 3, 5)` | -| | | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | +| | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | | twirling | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | | `'auto'` | | | shots_per_randomization | | | `'auto'` | -| | strategy | | `'active'`/
`'active-circuit'`/
`'active-accum'`/
`'all'` | `'active-accum'` | +| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | @@ -158,7 +158,7 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | | `'auto'` | | | shots_per_randomization | | | `'auto'` | -| | strategy | | `'active'`/
`'active-circuit'`/
`'active-accum'`/
`'all'` | `'active-accum'` | +| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | From 799c7fb7a303c962170210af4c04baf2112caeae Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Mon, 10 Jun 2024 16:03:47 -0500 Subject: [PATCH 14/63] fix all the br tags --- docs/run/runtime-options-overview 2.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/run/runtime-options-overview 2.mdx b/docs/run/runtime-options-overview 2.mdx index 8c2456d1bf0..d6967b8e1dd 100644 --- a/docs/run/runtime-options-overview 2.mdx +++ b/docs/run/runtime-options-overview 2.mdx @@ -91,7 +91,7 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | | shots_per_randomization | | 'auto' | | zne_mitigation | | `True`/`False` | `False` | | zne | noise_factors | | `(1, 3, 5)` | -| | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | +| | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | | Sub-options | Sub-sub-options | Choices | Default | @@ -101,7 +101,7 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | | shots_per_randomization | | 'auto' | | zne_mitigation | | `True`/`False` | `False` | | zne | noise_factors | | `(1, 3, 5)` | -| | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | +| | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | | Sub-options | Sub-sub-options | Choices | Default | @@ -111,7 +111,7 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | | shots_per_randomization | | 'auto' | | zne_mitigation | | `True`/`False` | `False` | | zne | noise_factors | | `(1, 3, 5)` | -| | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | +| | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | | Sub-options | Sub-sub-options | Choices | Default | @@ -121,7 +121,7 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | | shots_per_randomization | | 'auto' | | zne_mitigation | | `True`/`False` | `False` | | zne | noise_factors | | `(1, 3, 5)` | -| | extrapolator | `'exponential'`/
`'linear'`/
`'double_exponential'`/
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | +| | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | From dc6daf9fe3778d5f76bb470ed075fc957bee8de4 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Mon, 10 Jun 2024 16:06:56 -0500 Subject: [PATCH 15/63] change formatting --- docs/run/runtime-options-overview 2.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview 2.mdx b/docs/run/runtime-options-overview 2.mdx index d6967b8e1dd..1c223a11e30 100644 --- a/docs/run/runtime-options-overview 2.mdx +++ b/docs/run/runtime-options-overview 2.mdx @@ -93,6 +93,7 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | zne | noise_factors | | `(1, 3, 5)` | | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | + | Sub-options | Sub-sub-options | Choices | Default | |--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| @@ -103,7 +104,8 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | zne | noise_factors | | `(1, 3, 5)` | | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | - + + | Sub-options | Sub-sub-options | Choices | Default | |--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| | measure_mitigation | | `True`/`False` | `True` | @@ -113,6 +115,7 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | zne | noise_factors | | `(1, 3, 5)` | | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | + | Sub-options | Sub-sub-options | Choices | Default | |--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| From 06cfacf72696378e853a6d3a95d46894d6105ec3 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Mon, 10 Jun 2024 17:06:34 -0500 Subject: [PATCH 16/63] no space --- docs/run/_toc.json | 2 +- ...me-options-overview 2.mdx => runtime-options-overview-2.mdx} | 0 qiskit_bot.yaml | 2 +- 3 files changed, 2 insertions(+), 2 deletions(-) rename docs/run/{runtime-options-overview 2.mdx => runtime-options-overview-2.mdx} (100%) diff --git a/docs/run/_toc.json b/docs/run/_toc.json index 911aba5fd20..1bd988ae075 100644 --- a/docs/run/_toc.json +++ b/docs/run/_toc.json @@ -32,7 +32,7 @@ }, { "title": "Overview2", - "url": "/run/runtime-options-overview 2" + "url": "/run/runtime-options-overview-2" }, { "title": "Configure runtime error suppression", diff --git a/docs/run/runtime-options-overview 2.mdx b/docs/run/runtime-options-overview-2.mdx similarity index 100% rename from docs/run/runtime-options-overview 2.mdx rename to docs/run/runtime-options-overview-2.mdx diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 8976e8b3b6a..9df0268939f 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -167,7 +167,7 @@ notifications: - "@beckykd" - "@abbycross" - "`@blakejohnson`" - "docs/run/runtime-options-overview 2": + "docs/run/runtime-options-overview-2": - "@jyu00" - "@beckykd" - "@abbycross" From 72b1477f1d98b233328461bf997a142aac22f05b Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 11 Jun 2024 16:00:30 -0500 Subject: [PATCH 17/63] estimatorV2 table --- docs/run/_toc.json | 4 - docs/run/runtime-options-overview-2.mdx | 447 ------------------------ docs/run/runtime-options-overview.mdx | 56 ++- qiskit_bot.yaml | 5 - 4 files changed, 44 insertions(+), 468 deletions(-) delete mode 100644 docs/run/runtime-options-overview-2.mdx diff --git a/docs/run/_toc.json b/docs/run/_toc.json index 1bd988ae075..6a081258993 100644 --- a/docs/run/_toc.json +++ b/docs/run/_toc.json @@ -30,10 +30,6 @@ "title": "Overview", "url": "/run/runtime-options-overview" }, - { - "title": "Overview2", - "url": "/run/runtime-options-overview-2" - }, { "title": "Configure runtime error suppression", "url": "/run/configure-error-suppression" diff --git a/docs/run/runtime-options-overview-2.mdx b/docs/run/runtime-options-overview-2.mdx deleted file mode 100644 index 1c223a11e30..00000000000 --- a/docs/run/runtime-options-overview-2.mdx +++ /dev/null @@ -1,447 +0,0 @@ ---- -title: Advanced Qiskit Runtime options 2 -description: Specify options when building with Qiskit Runtime primitives - ---- - -# Advanced Qiskit Runtime options 2 - - You can pass options to primitives to customize them to meet your needs. 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. - - - -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`. - -*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") -``` - - -## 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`. - - -### Defaults - -client default (Unset) and where to find server defaults - - -### Precedence rules - -option precedence rules - - -## Options classes - - - - - [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**. - - - - [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**. - - - - -Specify options as follows: `primitive.options.option.sub-option.sub-sub-option = choice` - -Example: `estimator.options.dynamical_decoupling.enable = True` - -### option = resilience - - - -| Sub-options | Sub-sub-options | Choices | Default | -|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| measure_mitigation | | `True`/`False` | `True` | -| measure_noise_learning | num_randomizations | | `32` | -| | shots_per_randomization | | 'auto' | -| zne_mitigation | | `True`/`False` | `False` | -| zne | noise_factors | | `(1, 3, 5)` | -| | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | - - - -| Sub-options | Sub-sub-options | Choices | Default | -|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| measure_mitigation | | `True`/`False` | `True` | -| measure_noise_learning | num_randomizations | | `32` | -| | shots_per_randomization | | 'auto' | -| zne_mitigation | | `True`/`False` | `False` | -| zne | noise_factors | | `(1, 3, 5)` | -| | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | - - - -| Sub-options | Sub-sub-options | Choices | Default | -|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| measure_mitigation | | `True`/`False` | `True` | -| measure_noise_learning | num_randomizations | | `32` | -| | shots_per_randomization | | 'auto' | -| zne_mitigation | | `True`/`False` | `False` | -| zne | noise_factors | | `(1, 3, 5)` | -| | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | - - - -| Sub-options | Sub-sub-options | Choices | Default | -|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| measure_mitigation | | `True`/`False` | `True` | -| measure_noise_learning | num_randomizations | | `32` | -| | shots_per_randomization | | 'auto' | -| zne_mitigation | | `True`/`False` | `False` | -| zne | noise_factors | | `(1, 3, 5)` | -| | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | - - - - -### option = default_shots - -### option = resilience_level - -### option = dynamical_decoupling - -### option = twirling - - - -## 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 -``` -## Pass options to 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. 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) - -# Setting options after primitive initialization -# This uses auto complete. -estimator.options.optimization_level = 1 -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) -result = estimator.run(circuit, observable).result() -print(f">>> Metadata: {result.metadata[0]}") -``` - - - -### Primitive initialization - -You can specify options 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}) -``` - - - -### 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. - - - -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. -```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(session=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. - - - - ```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). - - - - - - -### Error suppression - -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. - -The Qiskit Runtime primitives may perform additional error suppression to optimize circuits, with the degree of optimization controlled by an optimization level option. The optimization level you choose affects the error suppression strategy, with higher levels invoking more expensive or aggressive optimizations. - -See the Optimization level table in the -[Configure error suppression topic](configure-error-suppression#set-the-optimization-level) for further details. - - - - The optimization level option is a "first-level option". Sampler V2 does not currently support `optimization_level`. - -```python -from qiskit_ibm_runtime import EstimatorV2 as Estimator - -estimator = Estimator(session=backend, options={"optimization_level": 1}) - -# or.. -estimator.options.optimization_level = 1 -``` - - - - - In original (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: - -```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 - - -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). - - - -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.options.resilience_level = 2 -estimator.options.resilience.zne_mitigation = True -estimator.options.resilience.zne.noise_factors = [1, 3, 5] -``` - - - -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 = 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. - -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 -``` - - -## 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). - - 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. - diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 089349d83d3..ba62653f29b 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -26,18 +26,26 @@ service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl") 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`. + + + ### Defaults -client default (Unset) and where to find server defaults +The tables in the [Options classes summary section](#options-classes) lists the default values. + +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. ### Precedence rules option precedence rules +**Some settings override other settings. For example; if you set default_shots, it overrides any value set for default_precision. Do we want to get into that much detail? ** + -## Options classes +## Options classes summary @@ -76,27 +84,51 @@ option precedence rules -Specify options as follows: `primitive.options.option.sub-option.sub-sub-option = choice` - -Example: `estimator.options.dynamical_decoupling.enable = True` + +Scroll to see the full table. + | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| | default_shots | | | | `4096` | -| optimization_level | | | `0`/`1` | `1` | -| resilience_level | | | `0`/`1`/`2` | `1` | -| dynamical_decoupling | enable | |`True`/`False` |`False` | +| default_precision | | | | `0.015625 (1 / sqrt(4096))` | +| dynamical_decoupling | | | | `FieldInfo(annotation=Union[DynamicalDecouplingOptions, Dict], required=False, default_factory=DynamicalDecouplingOptions)` | +| | enable | | `True`/`False` | `False` | | | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | | | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | | | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | -| resilience | measure_mitigation | | `True`/`False` | `True` | +| environment | | | | | +| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | +| | callback | |Callable function that recieves Job ID and Job result. |`None` | +| | job_tags | |List of tags |`None` | +| 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 | | | | `Unset` | +| optimization_level | | | `0`/`1` | `1` | +| resilience | LayerNoiseLearning | | `True`/`False` | `True` | +| | | max_layers_to_learn | `None`/ integer | `4` | +| | | shots_per_randomization | integer | `128` | +| | | num_randomizations | integer | `32` | +| | | layer_pair_depths | | `(0, 1, 2, 4, 16, 32)` | +| | measure_mitigation | | `True`/`False` | `True` | | | measure_noise_learning | num_randomizations | | `32` | | | | shots_per_randomization | | 'auto' | +| | pec | max_overhead | `None`/ integer | `100` | +| | | noise_gain | `auto`/ float in the range `[0, 1)` | `auto` | +| | pec_mitigation | | `True`/`False` | `False` | | | zne_mitigation | | `True`/`False` | `False` | | | zne | noise_factors | | `(1, 3, 5)` | | | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | +| resilience_level | | | `0`/`1`/`2` | `1` | +| seed_estimator | | | | `Unset` | +| SimulatorOptions | | | | | +| | noise_model | | | `Unset` | +| | seed_simulator | | | `Unset` | +| | coupling_map | | | `Unset` | +| | basis_gates | | | `Unset` | | twirling | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | | `'auto'` | @@ -124,7 +156,6 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| default_shots | | | | `4096` | | optimization_level | | | `0`/`1` | `1` | | resilience_level | | | `0`/`1`/`2` | `1` | | dynamical_decoupling | enable | |`True`/`False` |`False` | @@ -148,7 +179,6 @@ Example: `estimator.options.dynamical_decoupling.enable = True` | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| default_shots | | | | `4096` | | optimization_level | | | `0`/`1` | `1` | | dynamical_decoupling | enable | |`True`/`False` |`False` | | | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | @@ -199,7 +229,9 @@ options.execution.shots = 2048 ### 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: diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 9df0268939f..ee03b38053e 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -167,11 +167,6 @@ notifications: - "@beckykd" - "@abbycross" - "`@blakejohnson`" - "docs/run/runtime-options-overview-2": - - "@jyu00" - - "@beckykd" - - "@abbycross" - - "`@blakejohnson`" "docs/run/error-mitigation-explanation": - "@kevinsung" "docs/run/sessions": From b96c3b5628d064c592677683b9048a1a711c4087 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 12 Jun 2024 10:23:07 -0500 Subject: [PATCH 18/63] edit --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index ba62653f29b..82265a4d742 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -124,7 +124,7 @@ Scroll to see the full table. | | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | | resilience_level | | | `0`/`1`/`2` | `1` | | seed_estimator | | | | `Unset` | -| SimulatorOptions | | | | | +| simulator | | | | | | | noise_model | | | `Unset` | | | seed_simulator | | | `Unset` | | | coupling_map | | | `Unset` | From 07a7980b5b0539d0b35fa3ccb37ed60cfe139254 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 12 Jun 2024 12:25:52 -0500 Subject: [PATCH 19/63] Update runtime-options-overview.mdx Add more details --- docs/run/runtime-options-overview.mdx | 57 +++++++++++++++++++-------- 1 file changed, 41 insertions(+), 16 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 82265a4d742..c94d45d9208 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -24,25 +24,43 @@ 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`. - - - +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 [Pass options to a primitive](#pass-options) section for full details. ### Defaults -The tables in the [Options classes summary section](#options-classes) lists the default values. +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 was dependant on the code version. -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. +The tables in the [Options classes summary section](#options-classes) lists the default values. ### Precedence rules -option 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 in `run()` are used for that execution. See the [Run() method](#run-method) section for full details. +2. Any options set after primitive initialization. +3. Any options set during primitive initialization. -**Some settings override other settings. For example; if you set default_shots, it overrides any value set for default_precision. Do we want to get into that much detail? ** +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) +``` + + +Some settings override other settings. For example; if you set `default_shots`, it overrides any value set for `default_precision`. See the [API documentation](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options) for the details about every option. + ## Options classes summary @@ -106,7 +124,7 @@ Scroll to see the full table. | 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 | | | | `Unset` | +| max_execution_time | | | integer number of seconds in the range (0, 5000] | `10800` (3 hours) | | optimization_level | | | `0`/`1` | `1` | | resilience | LayerNoiseLearning | | `True`/`False` | `True` | | | | max_layers_to_learn | `None`/ integer | `4` | @@ -114,8 +132,8 @@ Scroll to see the full table. | | | num_randomizations | integer | `32` | | | | layer_pair_depths | | `(0, 1, 2, 4, 16, 32)` | | | measure_mitigation | | `True`/`False` | `True` | -| | measure_noise_learning | num_randomizations | | `32` | -| | | shots_per_randomization | | 'auto' | +| | measure_noise_learning | num_randomizations | integer | `32` | +| | | shots_per_randomization | integer | 'auto' | | | pec | max_overhead | `None`/ integer | `100` | | | | noise_gain | `auto`/ float in the range `[0, 1)` | `auto` | | | pec_mitigation | | `True`/`False` | `False` | @@ -127,12 +145,17 @@ Scroll to see the full table. | simulator | | | | | | | noise_model | | | `Unset` | | | seed_simulator | | | `Unset` | -| | coupling_map | | | `Unset` | -| | basis_gates | | | `Unset` | +| | coupling_map | | List where each entry specifies a directed two-qubit interaction, for example: [[0, 1], [0, 3], [1, 2], [1, 5], [2, 5], [4, 1], [5, 3]] | `Unset` | +| | basis_gates | | Set of single- and two-qubit gates that provide a universal gates set, meaning that any quantum operation can be decomposed into those gates. Example: `['ecr', 'x', 'sx', 'rz']` | Click the appropriate system on the [Systems page](https://quantum.ibm.com/services/resources) to open its details page. | +| transpilation | skip_transpilation | | `True`/`False` | `False` | +| | initial_layout | | | | +| | layout_method | | `trivial`/`dense`/`noise_adaptive`/`sabre` | `Unset` | +| | routing_method | | `basic`/`lookahead`/`stochastic`/`sabre`/`none` | `Unset` | +| | approximation_degree | | float in the range [0, 1] | `Unset` | | twirling | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | -| | num_randomizations | | | `'auto'` | -| | shots_per_randomization | | | `'auto'` | +| | num_randomizations | | `auto`/ integer | `'auto'` | +| | shots_per_randomization | | `auto`/ integer | `'auto'` | | | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | @@ -225,6 +248,7 @@ options = Options() options.resilience_level = 1 options.execution.shots = 2048 ``` + ## Pass options to a primitive ### Options class @@ -291,6 +315,7 @@ 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. From 8f07ea6182e974fd1026cdc2a7f6951280db0ecd Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 12 Jun 2024 17:42:00 -0500 Subject: [PATCH 20/63] spelling --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index c94d45d9208..4e0f5279fb2 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -119,7 +119,7 @@ Scroll to see the full table. | | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | | environment | | | | | | | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | -| | callback | |Callable function that recieves Job ID and Job result. |`None` | +| | callback | |Callable function that receives Job ID and Job result. |`None` | | | job_tags | |List of tags |`None` | | execution | | | | | | | init_qubits | | `True`/`False` | `True` | From 5720489043ffe54c883d941253e18cf7ed06ce7e Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 12 Jun 2024 17:44:30 -0500 Subject: [PATCH 21/63] fix link --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 4e0f5279fb2..9e3da3f6646 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -59,7 +59,7 @@ estimator.run([circuit1, circuit2], shots=128) ``` -Some settings override other settings. For example; if you set `default_shots`, it overrides any value set for `default_precision`. See the [API documentation](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options) for the details about every option. +Some settings override other settings. For example; if you set `default_shots`, it overrides any value set for `default_precision`. See the [API documentation](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) for the details about every option. From 5a618c0af09198b655424e057f3524fcab84b228 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 12 Jun 2024 17:57:12 -0500 Subject: [PATCH 22/63] updates from jessie --- docs/run/runtime-options-overview.mdx | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 9e3da3f6646..7a0afd08fc3 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -141,17 +141,14 @@ Scroll to see the full table. | | zne | noise_factors | | `(1, 3, 5)` | | | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | | resilience_level | | | `0`/`1`/`2` | `1` | -| seed_estimator | | | | `Unset` | +| seed_estimator | | | integer | `None` | | simulator | | | | | -| | noise_model | | | `Unset` | -| | seed_simulator | | | `Unset` | -| | coupling_map | | List where each entry specifies a directed two-qubit interaction, for example: [[0, 1], [0, 3], [1, 2], [1, 5], [2, 5], [4, 1], [5, 3]] | `Unset` | -| | basis_gates | | Set of single- and two-qubit gates that provide a universal gates set, meaning that any quantum operation can be decomposed into those gates. Example: `['ecr', 'x', 'sx', 'rz']` | Click the appropriate system on the [Systems page](https://quantum.ibm.com/services/resources) to open its details page. | +| | noise_model | | [Qiskit Aer NoiseModel](../verify/building_noise_models), or its representation | `None` | +| | seed_simulator | | integer | `None` | +| | coupling_map | | List where each entry specifies a directed two-qubit interaction, for example: [[0, 1], [0, 3], [1, 2], [1, 5], [2, 5], [4, 1], [5, 3]] | full connectivity | +| | basis_gates | | Set of single- and two-qubit gates that provide a universal gates set, meaning that any quantum operation can be decomposed into those gates. Example: `['ecr', 'x', 'sx', 'rz']` | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | | transpilation | skip_transpilation | | `True`/`False` | `False` | | | initial_layout | | | | -| | layout_method | | `trivial`/`dense`/`noise_adaptive`/`sabre` | `Unset` | -| | routing_method | | `basic`/`lookahead`/`stochastic`/`sabre`/`none` | `Unset` | -| | approximation_degree | | float in the range [0, 1] | `Unset` | | twirling | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | `auto`/ integer | `'auto'` | From 2b5f9ccc871f32395f18cdeaa4c691b0e0b87f4b Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 13 Jun 2024 11:20:50 -0500 Subject: [PATCH 23/63] add more info --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 7a0afd08fc3..ddb842306a7 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -110,7 +110,7 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| default_shots | | | | `4096` | +| default_shots | | | integer in the range[0, `backend.max_shots`] | `4096` | | default_precision | | | | `0.015625 (1 / sqrt(4096))` | | dynamical_decoupling | | | | `FieldInfo(annotation=Union[DynamicalDecouplingOptions, Dict], required=False, default_factory=DynamicalDecouplingOptions)` | | | enable | | `True`/`False` | `False` | From 88ed74136d6bc51e291666553585a80915026582 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 13 Jun 2024 12:28:03 -0500 Subject: [PATCH 24/63] precedence --- docs/run/runtime-options-overview.mdx | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index ddb842306a7..de2692c7f05 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -58,9 +58,29 @@ estimator.options.default_shots = 4000 estimator.run([circuit1, circuit2], shots=128) ``` - -Some settings override other settings. For example; if you set `default_shots`, it overrides any value set for `default_precision`. See the [API documentation](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) for the details about every option. - +#### Special cases + +The `default_shots` and `resilience_level` options require special consideration: + +If you set `default_shots`, it overrides any value set for `default_precision`. + +The `resilience_level` is used to set a base configuration on any relevant options, and than 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 From 330ee6c7a06c3e679cc86ecdd5dc9ed197e159d6 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 13 Jun 2024 12:42:51 -0500 Subject: [PATCH 25/63] further organization --- docs/run/runtime-options-overview.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index de2692c7f05..8fe4e39e4c8 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/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 [Pass options to a primitive](#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](#pass-options) section for full details. ### Defaults @@ -150,7 +150,7 @@ Scroll to see the full table. | | | max_layers_to_learn | `None`/ integer | `4` | | | | shots_per_randomization | integer | `128` | | | | num_randomizations | integer | `32` | -| | | layer_pair_depths | | `(0, 1, 2, 4, 16, 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 | `32` | | | | shots_per_randomization | integer | 'auto' | @@ -266,7 +266,9 @@ options.resilience_level = 1 options.execution.shots = 2048 ``` -## Pass options to a primitive +## Set primitive options + +You can set optitons in an options class, when initializing the primitive, when calling the `run()` method, or any combination of those. ### Options class @@ -419,8 +421,6 @@ For more information about the primitive options, refer to the - - ### Error suppression 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. From 7b74f8eb7aa86a0a85b479ed04d074480e1efee9 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 14 Jun 2024 11:22:36 -0500 Subject: [PATCH 26/63] finish updating the table for Estimator V2 --- docs/run/runtime-options-overview.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 8fe4e39e4c8..0a5d4736210 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -131,7 +131,7 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| | default_shots | | | integer in the range[0, `backend.max_shots`] | `4096` | -| default_precision | | | | `0.015625 (1 / sqrt(4096))` | +| default_precision | | | float > 0 | `0.015625 (1 / sqrt(4096))` | | dynamical_decoupling | | | | `FieldInfo(annotation=Union[DynamicalDecouplingOptions, Dict], required=False, default_factory=DynamicalDecouplingOptions)` | | | enable | | `True`/`False` | `False` | | | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | @@ -147,18 +147,18 @@ Scroll to see the full table. | max_execution_time | | | integer number of seconds in the range (0, 5000] | `10800` (3 hours) | | optimization_level | | | `0`/`1` | `1` | | resilience | LayerNoiseLearning | | `True`/`False` | `True` | -| | | max_layers_to_learn | `None`/ integer | `4` | -| | | shots_per_randomization | integer | `128` | -| | | num_randomizations | integer | `32` | +| | | 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 | `32` | +| | measure_noise_learning | num_randomizations | integer >= 1 (Note that this value strongly influences execution time.) | `32` | | | | shots_per_randomization | integer | 'auto' | -| | pec | max_overhead | `None`/ integer | `100` | +| | 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 | | `(1, 3, 5)` | +| | zne | noise_factors | list of floats; each float >= 1 | `(1, 3, 5)` | | | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | | resilience_level | | | `0`/`1`/`2` | `1` | | seed_estimator | | | integer | `None` | @@ -171,8 +171,8 @@ Scroll to see the full table. | | initial_layout | | | | | twirling | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | -| | num_randomizations | | `auto`/ integer | `'auto'` | -| | shots_per_randomization | | `auto`/ integer | `'auto'` | +| | num_randomizations | | `auto`/ integer >= 1 (Note that this value strongly influences execution time.) | `'auto'` | +| | shots_per_randomization | | `auto`/ integer >= 1. The maximum depends on the maximum shots allowed by the system. To find this value, run `backend.max_shots`. | `'auto'` | | | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | From ac608d13d587886b6351951f2d66cc00e3bbc8e6 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 14 Jun 2024 12:16:44 -0500 Subject: [PATCH 27/63] table first draft --- docs/run/runtime-options-overview.mdx | 22 +++++++++++++++++++ .../runtime-options-overview/checkmark.svg | 3 +++ .../runtime-options-overview/close--large.svg | 3 +++ .../run/runtime-options-overview/error.svg | 3 +++ .../misuse--outline.svg | 3 +++ .../runtime-options-overview/warning--alt.svg | 3 +++ 6 files changed, 37 insertions(+) create mode 100644 public/images/run/runtime-options-overview/checkmark.svg create mode 100644 public/images/run/runtime-options-overview/close--large.svg create mode 100644 public/images/run/runtime-options-overview/error.svg create mode 100644 public/images/run/runtime-options-overview/misuse--outline.svg create mode 100644 public/images/run/runtime-options-overview/warning--alt.svg diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 0a5d4736210..577a55c698e 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -122,6 +122,9 @@ estimator.options.resilience.zne_mitigation = True + +### Available options + Scroll to see the full table. @@ -236,7 +239,26 @@ Scroll to see the full table. + +### Options compatibility + +Due to differences in the device compilation process, certain runtime features cannot be used together in a single job. See the following table for details on which features are compatible with each other: + +Key: +- ![Incompatible](/images/run/runtime-options-overview/error.svg) - These features cannot be used together. +- ![Compatible](/images/run/runtime-options-overview/checkmark.svg) - These features can be used together. +- ![Limitations](/images/run/runtime-options-overview/warning.svg) - - These features can be used together but with limitations. +| | fractional gates | dynamic circuits | Gate-folding ZNE | PEA | PEC | dynamical decoupling | pulse gates (Eagle only) | gate twirling | +|--------------------------|------------------|-----------------------------------------------------------------|------------------------------------|-----|-----------------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| +| fractional gates | | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ✅ IH comment | 🚫 | 🚫 | ✅ | ✅ | 🚫 | +| dynamic circuits | 🚫 | | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | ✅ (non conditional gates only) | +| Gate-folding ZNE | ✅ | 🚫 | | 🚫 | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Limitations](/images/run/runtime-options-overview/warning.svg) - Might not work with custom gates | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | +| PEA | 🚫 | 🚫 | 🚫 | | 🚫 | ✅ | 🚫 | ✅ | +| PEC | 🚫 | 🚫 | 🚫 | 🚫 | | ✅ | 🚫 | ✅ | +| dynamical decoupling | ✅ | 🚫 | ✅ | ✅ | ✅ | | ✅ | ✅ | +| pulse gates (Eagle only) | ✅ | 🚫 | ⚠️ (may not work with custom gates) | 🚫 | 🚫 | ✅ | | ~✅ IH comment~

⚠️ (does not work with non-Clifford entanglers) | +| gate twirling | 🚫 | ✅ (non conditional gates only) | ✅ | ✅ | ✅ | ✅ | ⚠️ (does not work with non-Clifford entanglers) | | ## V2 changes Options are specified differently in the V2 primitives in these ways: diff --git a/public/images/run/runtime-options-overview/checkmark.svg b/public/images/run/runtime-options-overview/checkmark.svg new file mode 100644 index 00000000000..3cc1d6fbd1b --- /dev/null +++ b/public/images/run/runtime-options-overview/checkmark.svg @@ -0,0 +1,3 @@ + + + diff --git a/public/images/run/runtime-options-overview/close--large.svg b/public/images/run/runtime-options-overview/close--large.svg new file mode 100644 index 00000000000..7913c8a2220 --- /dev/null +++ b/public/images/run/runtime-options-overview/close--large.svg @@ -0,0 +1,3 @@ + + + diff --git a/public/images/run/runtime-options-overview/error.svg b/public/images/run/runtime-options-overview/error.svg new file mode 100644 index 00000000000..789d493125b --- /dev/null +++ b/public/images/run/runtime-options-overview/error.svg @@ -0,0 +1,3 @@ + + + diff --git a/public/images/run/runtime-options-overview/misuse--outline.svg b/public/images/run/runtime-options-overview/misuse--outline.svg new file mode 100644 index 00000000000..0e764bb3360 --- /dev/null +++ b/public/images/run/runtime-options-overview/misuse--outline.svg @@ -0,0 +1,3 @@ + + + diff --git a/public/images/run/runtime-options-overview/warning--alt.svg b/public/images/run/runtime-options-overview/warning--alt.svg new file mode 100644 index 00000000000..854d608453b --- /dev/null +++ b/public/images/run/runtime-options-overview/warning--alt.svg @@ -0,0 +1,3 @@ + + + From 2c24c703aa228786501f1ae60ba0575c74b1ad07 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 14 Jun 2024 12:17:45 -0500 Subject: [PATCH 28/63] spelling --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 577a55c698e..5f69f178a69 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -290,7 +290,7 @@ options.execution.shots = 2048 ## Set primitive options -You can set optitons in an options class, when initializing the primitive, when calling the `run()` method, or any combination of those. +You can set options in an options class, when initializing the primitive, when calling the `run()` method, or any combination of those. ### Options class From 6c16c7db16f7f06bd7420bb3c6ecd182744db740 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 14 Jun 2024 15:15:14 -0500 Subject: [PATCH 29/63] link to image --- docs/run/runtime-options-overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 5f69f178a69..e7cbeb0137f 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -247,13 +247,13 @@ Due to differences in the device compilation process, certain runtime features c Key: - ![Incompatible](/images/run/runtime-options-overview/error.svg) - These features cannot be used together. - ![Compatible](/images/run/runtime-options-overview/checkmark.svg) - These features can be used together. -- ![Limitations](/images/run/runtime-options-overview/warning.svg) - - These features can be used together but with limitations. +- ![Limitations](/images/run/runtime-options-overview/warning--alt.svg) - - These features can be used together but with limitations. | | fractional gates | dynamic circuits | Gate-folding ZNE | PEA | PEC | dynamical decoupling | pulse gates (Eagle only) | gate twirling | |--------------------------|------------------|-----------------------------------------------------------------|------------------------------------|-----|-----------------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| | fractional gates | | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ✅ IH comment | 🚫 | 🚫 | ✅ | ✅ | 🚫 | | dynamic circuits | 🚫 | | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | ✅ (non conditional gates only) | -| Gate-folding ZNE | ✅ | 🚫 | | 🚫 | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Limitations](/images/run/runtime-options-overview/warning.svg) - Might not work with custom gates | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | +| Gate-folding ZNE | ✅ | 🚫 | | 🚫 | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Limitations](/images/run/runtime-options-overview/warning--alt.svg) - Might not work with custom gates | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | | PEA | 🚫 | 🚫 | 🚫 | | 🚫 | ✅ | 🚫 | ✅ | | PEC | 🚫 | 🚫 | 🚫 | 🚫 | | ✅ | 🚫 | ✅ | | dynamical decoupling | ✅ | 🚫 | ✅ | ✅ | ✅ | | ✅ | ✅ | From 1389ce61eeb6e4382b2b709743719cd2e215dfb1 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 14 Jun 2024 15:31:50 -0500 Subject: [PATCH 30/63] remove image links from table --- docs/run/runtime-options-overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index e7cbeb0137f..a7fc9025dbe 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -251,9 +251,9 @@ Key: | | fractional gates | dynamic circuits | Gate-folding ZNE | PEA | PEC | dynamical decoupling | pulse gates (Eagle only) | gate twirling | |--------------------------|------------------|-----------------------------------------------------------------|------------------------------------|-----|-----------------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| -| fractional gates | | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ✅ IH comment | 🚫 | 🚫 | ✅ | ✅ | 🚫 | +| fractional gates | | no | ✅ IH comment | 🚫 | 🚫 | ✅ | ✅ | 🚫 | | dynamic circuits | 🚫 | | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | ✅ (non conditional gates only) | -| Gate-folding ZNE | ✅ | 🚫 | | 🚫 | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Limitations](/images/run/runtime-options-overview/warning--alt.svg) - Might not work with custom gates | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | +| Gate-folding ZNE | ✅ | 🚫 | | 🚫 | no | check | limited - Might not work with custom gates | check | | PEA | 🚫 | 🚫 | 🚫 | | 🚫 | ✅ | 🚫 | ✅ | | PEC | 🚫 | 🚫 | 🚫 | 🚫 | | ✅ | 🚫 | ✅ | | dynamical decoupling | ✅ | 🚫 | ✅ | ✅ | ✅ | | ✅ | ✅ | From e73127f7337d01ac79524256e4dcd47b608dec34 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 14 Jun 2024 15:35:33 -0500 Subject: [PATCH 31/63] remove pasted images from table --- docs/run/runtime-options-overview.mdx | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index a7fc9025dbe..3b4fc65002e 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -251,14 +251,7 @@ Key: | | fractional gates | dynamic circuits | Gate-folding ZNE | PEA | PEC | dynamical decoupling | pulse gates (Eagle only) | gate twirling | |--------------------------|------------------|-----------------------------------------------------------------|------------------------------------|-----|-----------------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| -| fractional gates | | no | ✅ IH comment | 🚫 | 🚫 | ✅ | ✅ | 🚫 | -| dynamic circuits | 🚫 | | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | ✅ (non conditional gates only) | -| Gate-folding ZNE | ✅ | 🚫 | | 🚫 | no | check | limited - Might not work with custom gates | check | -| PEA | 🚫 | 🚫 | 🚫 | | 🚫 | ✅ | 🚫 | ✅ | -| PEC | 🚫 | 🚫 | 🚫 | 🚫 | | ✅ | 🚫 | ✅ | -| dynamical decoupling | ✅ | 🚫 | ✅ | ✅ | ✅ | | ✅ | ✅ | -| pulse gates (Eagle only) | ✅ | 🚫 | ⚠️ (may not work with custom gates) | 🚫 | 🚫 | ✅ | | ~✅ IH comment~

⚠️ (does not work with non-Clifford entanglers) | -| gate twirling | 🚫 | ✅ (non conditional gates only) | ✅ | ✅ | ✅ | ✅ | ⚠️ (does not work with non-Clifford entanglers) | | +| gate twirling | ![Incompatible](/images/run/runtime-options-overview/error.svg) |![Compatible](/images/run/runtime-options-overview/checkmark.svg) | y | y | y | ✅ | ⚠️ (does not work with non-Clifford entanglers) | | ## V2 changes Options are specified differently in the V2 primitives in these ways: From 361a182c9bbefc38f2d2319cf5ba497f81ac66c0 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 14 Jun 2024 15:42:06 -0500 Subject: [PATCH 32/63] no table --- docs/run/runtime-options-overview.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 3b4fc65002e..306abba4da8 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -249,9 +249,6 @@ Key: - ![Compatible](/images/run/runtime-options-overview/checkmark.svg) - These features can be used together. - ![Limitations](/images/run/runtime-options-overview/warning--alt.svg) - - These features can be used together but with limitations. -| | fractional gates | dynamic circuits | Gate-folding ZNE | PEA | PEC | dynamical decoupling | pulse gates (Eagle only) | gate twirling | -|--------------------------|------------------|-----------------------------------------------------------------|------------------------------------|-----|-----------------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| -| gate twirling | ![Incompatible](/images/run/runtime-options-overview/error.svg) |![Compatible](/images/run/runtime-options-overview/checkmark.svg) | y | y | y | ✅ | ⚠️ (does not work with non-Clifford entanglers) | | ## V2 changes Options are specified differently in the V2 primitives in these ways: From eb3e5349fba2d2ae47ae5389958b33d54f12dd76 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 14 Jun 2024 15:48:10 -0500 Subject: [PATCH 33/63] delete new section --- docs/run/runtime-options-overview.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 306abba4da8..de3834348ea 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -245,9 +245,6 @@ Scroll to see the full table. Due to differences in the device compilation process, certain runtime features cannot be used together in a single job. See the following table for details on which features are compatible with each other: Key: -- ![Incompatible](/images/run/runtime-options-overview/error.svg) - These features cannot be used together. -- ![Compatible](/images/run/runtime-options-overview/checkmark.svg) - These features can be used together. -- ![Limitations](/images/run/runtime-options-overview/warning--alt.svg) - - These features can be used together but with limitations. ## V2 changes From 439f5f3d491b710271af766ca7b72579c17a2545 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Tue, 25 Jun 2024 11:31:46 -0500 Subject: [PATCH 34/63] Update docs/run/runtime-options-overview.mdx Co-authored-by: Ian Hincks --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index de3834348ea..120fd794092 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -6,7 +6,7 @@ description: Specify options when building with Qiskit Runtime primitives # Advanced Qiskit Runtime options - You can pass options to primitives to customize them to meet your needs. 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. + 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` and `qiskit_aer.primitives` options. From 727bc8cd018206c5f6aeaf4aef138ecc60d466f9 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Tue, 25 Jun 2024 12:32:24 -0500 Subject: [PATCH 35/63] Update docs/run/runtime-options-overview.mdx Co-authored-by: Ian Hincks --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 120fd794092..f34b904ab7d 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -62,7 +62,7 @@ estimator.run([circuit1, circuit2], shots=128) The `default_shots` and `resilience_level` options require special consideration: -If you set `default_shots`, it overrides any value set for `default_precision`. +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 than 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. From 6dbdd20ff9d03d793c1ac3f66c6832e89a6ede71 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Tue, 25 Jun 2024 12:32:41 -0500 Subject: [PATCH 36/63] Update docs/run/runtime-options-overview.mdx Co-authored-by: Ian Hincks --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index f34b904ab7d..88a6130c95d 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -64,7 +64,7 @@ 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 than 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. +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`. From 8f4836f3d9d7850c2ce83f8debf401871e91fb50 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Tue, 25 Jun 2024 12:46:07 -0500 Subject: [PATCH 37/63] Update docs/run/runtime-options-overview.mdx Co-authored-by: Jessie Yu --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 88a6130c95d..0d771f2be53 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -134,7 +134,7 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| | default_shots | | | integer in the range[0, `backend.max_shots`] | `4096` | -| default_precision | | | float > 0 | `0.015625 (1 / sqrt(4096))` | +| default_precision | | | float > 0 | `0.015625, or 1 / sqrt(4096)` | | dynamical_decoupling | | | | `FieldInfo(annotation=Union[DynamicalDecouplingOptions, Dict], required=False, default_factory=DynamicalDecouplingOptions)` | | | enable | | `True`/`False` | `False` | | | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | From 774ec9ef77989e261fd3c32d5eb5093a74019428 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Tue, 25 Jun 2024 12:46:24 -0500 Subject: [PATCH 38/63] Update docs/run/runtime-options-overview.mdx Co-authored-by: Jessie Yu --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 0d771f2be53..3dd777fd7f7 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -158,7 +158,7 @@ Scroll to see the full table. | | measure_noise_learning | num_randomizations | integer >= 1 (Note that this value strongly influences execution time.) | `32` | | | | shots_per_randomization | integer | 'auto' | | | pec | max_overhead | `None`/ integer >1 | `100` | -| | | noise_gain | `auto`/ float in the range `[0, 1)` | `auto` | +| | | 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)` | From f3ec7e102709b56b5e7aa40695fa77ebc21de308 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 25 Jun 2024 15:57:08 -0500 Subject: [PATCH 39/63] Review comments --- docs/run/runtime-options-overview.mdx | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 3dd777fd7f7..668f0b3c8b3 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -39,10 +39,13 @@ The tables in the [Options classes summary section](#options-classes) lists the 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 in `run()` are used for that execution. See the [Run() method](#run-method) section for full details. 2. Any options set after primitive initialization. 3. 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 @@ -134,8 +137,8 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| | default_shots | | | integer in the range[0, `backend.max_shots`] | `4096` | -| default_precision | | | float > 0 | `0.015625, or 1 / sqrt(4096)` | -| dynamical_decoupling | | | | `FieldInfo(annotation=Union[DynamicalDecouplingOptions, Dict], required=False, default_factory=DynamicalDecouplingOptions)` | +| default_precision | | | float > 0 | `0.015625 (1 / sqrt(4096))` | +| dynamical_decoupling | | | | | | | enable | | `True`/`False` | `False` | | | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | | | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | @@ -147,7 +150,7 @@ Scroll to see the full table. | 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 | | | integer number of seconds in the range (0, 5000] | `10800` (3 hours) | +| max_execution_time | | | integer number of seconds in the range [1, 10800] | `10800` (3 hours) | | optimization_level | | | `0`/`1` | `1` | | resilience | LayerNoiseLearning | | `True`/`False` | `True` | | | | max_layers_to_learn | `None`/ integer >= 1 | `4` | @@ -162,20 +165,21 @@ Scroll to see the full table. | | pec_mitigation | | `True`/`False` | `False` | | | zne_mitigation | | `True`/`False` | `False` | | | zne | noise_factors | list of floats; each float >= 1 | `(1, 3, 5)` | -| | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | +| | | 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 | | | `0`/`1`/`2` | `1` | | seed_estimator | | | integer | `None` | | simulator | | | | | | | noise_model | | [Qiskit Aer NoiseModel](../verify/building_noise_models), or its representation | `None` | | | seed_simulator | | integer | `None` | -| | coupling_map | | List where each entry specifies a directed two-qubit interaction, for example: [[0, 1], [0, 3], [1, 2], [1, 5], [2, 5], [4, 1], [5, 3]] | full connectivity | -| | basis_gates | | Set of single- and two-qubit gates that provide a universal gates set, meaning that any quantum operation can be decomposed into those gates. Example: `['ecr', 'x', 'sx', 'rz']` | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | +| | 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) | | transpilation | skip_transpilation | | `True`/`False` | `False` | | | initial_layout | | | | | twirling | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | `auto`/ integer >= 1 (Note that this value strongly influences execution time.) | `'auto'` | -| | shots_per_randomization | | `auto`/ integer >= 1. The maximum depends on the maximum shots allowed by the system. To find this value, run `backend.max_shots`. | `'auto'` | +| | shots_per_randomization | | `auto`/ integer >= 1 and <= `backend.max_shots`. | `'auto'` | | | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | From 9e0f48492cb24ff400744ad0fbfea70e84627633 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 25 Jun 2024 17:18:50 -0500 Subject: [PATCH 40/63] more updates --- docs/run/runtime-options-overview.mdx | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 668f0b3c8b3..3fa55e46a5b 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -281,7 +281,7 @@ options.execution.shots = 2048 ## Set primitive options -You can set options in an options class, when initializing the primitive, when calling the `run()` method, or any combination of those. +You can set options in an options class, when initializing the primitive, or both. ### Options class @@ -350,11 +350,12 @@ 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) @@ -382,6 +383,21 @@ 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: + +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 + ```python from qiskit_ibm_runtime import SamplerV2 as Sampler From 02a68b2c4bc79f3d56650eb99f904509b0758439 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 26 Jun 2024 13:52:14 -0500 Subject: [PATCH 41/63] ALL THE CLICKABLE TABS!!! --- docs/run/runtime-options-overview.mdx | 60 ++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 3fa55e46a5b..310fdd3e43a 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -248,7 +248,65 @@ Scroll to see the full table. Due to differences in the device compilation process, certain runtime features cannot be used together in a single job. See the following table for details on which features are compatible with each other: -Key: + + + 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. + + + Compatibile 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 From 6e1ecb63e74f4fe0c374d791d4be4236e598a196 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 26 Jun 2024 14:15:23 -0500 Subject: [PATCH 42/63] Big old table --- docs/run/runtime-options-overview.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 310fdd3e43a..745478ef0b8 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -308,6 +308,16 @@ Due to differences in the device compilation process, certain runtime features c +| | fractional gates | dynamic circuits | Gate-folding ZNE | PEA | PEC | dynamical decoupling | pulse gates (Eagle only) | gate twirling | +|--------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| fractional gates | | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | +| dynamic circuits | ![Incompatible](/images/run/runtime-options-overview/error.svg) | | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) (Non-conditional gates) | +| Gate-folding ZNE | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Limitations](/images/run/runtime-options-overview/warning.svg) (Might not work with custom gates
) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | +| PEA | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | +| PEC | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | +| dynamical decoupling | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | +| pulse gates (Eagle only) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Limitations](/images/run/runtime-options-overview/warning.svg) (Might not work with custom gates) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | | ![Compatible](/images/run/runtime-options-overview/checkmark.svg)
![Limitations](/images/run/runtime-options-overview/warning.svg) (Clifford entanglers only) | +| gate twirling | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) (Non-conditional gates) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Limitations](/images/run/runtime-options-overview/warning.svg) (Clifford entanglers only) | | ## V2 changes Options are specified differently in the V2 primitives in these ways: From fb6d1c82c727639194397981812ae9d228bf2e5e Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 26 Jun 2024 15:50:27 -0500 Subject: [PATCH 43/63] add link in the table --- docs/run/runtime-options-overview.mdx | 39 ++++++++++++++++++--------- 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 745478ef0b8..3ed58c41bd6 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -136,7 +136,7 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| default_shots | | | integer in the range[0, `backend.max_shots`] | `4096` | +| default_shots | | | integer in the range[0, `backend.max_shots`] | None | | default_precision | | | float > 0 | `0.015625 (1 / sqrt(4096))` | | dynamical_decoupling | | | | | | | enable | | `True`/`False` | `False` | @@ -152,7 +152,8 @@ 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 | | | integer number of seconds in the range [1, 10800] | `10800` (3 hours) | | optimization_level | | | `0`/`1` | `1` | -| resilience | LayerNoiseLearning | | `True`/`False` | `True` | +| [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` | @@ -174,11 +175,10 @@ Scroll to see the full table. | | 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) | -| transpilation | skip_transpilation | | `True`/`False` | `False` | -| | initial_layout | | | | -| twirling | enable_gates | | `True`/`False` | `False` | +| twirling | | | | | +| | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | -| | num_randomizations | | `auto`/ integer >= 1 (Note that this value strongly influences execution time.) | `'auto'` | +| | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | | | shots_per_randomization | | `auto`/ integer >= 1 and <= `backend.max_shots`. | `'auto'` | | | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | @@ -186,16 +186,31 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| default_shots | | | | `4096` | -| optimization_level | | | `0`/`1` | `1` | -| dynamical_decoupling | enable | |`True`/`False` |`False` | +| default_shots | | | integer in the range[0, `backend.max_shots`] | `4096` | +| dynamical_decoupling | | | | | +| | enable | | `True`/`False` | `False` | | | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | | | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | | | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | -| twirling | enable_gates | | `True`/`False` | `False` | +| 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 | | | | | +| | 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 | | | integer number of seconds in the range [1, 10800] | `10800` (3 hours) | +| optimization_level | | | `0`/`1` | `1` | +| simulator | | | | | +| | noise_model | | [Qiskit Aer NoiseModel](../verify/building_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 | | | | | +| | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | -| | num_randomizations | | | `'auto'` | -| | shots_per_randomization | | | `'auto'` | +| | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | +| | shots_per_randomization | | `auto`/ integer >= 1 and <= `backend.max_shots`. | `'auto'` | | | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | From bc7fcc1c18ab0cd1d1637b4f52ccddffd066850c Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 26 Jun 2024 16:03:38 -0500 Subject: [PATCH 44/63] add more links --- docs/run/runtime-options-overview.mdx | 53 +++++++++++++-------------- 1 file changed, 26 insertions(+), 27 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 3ed58c41bd6..a30334a898e 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -136,22 +136,22 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| default_shots | | | integer in the range[0, `backend.max_shots`] | None | -| default_precision | | | float > 0 | `0.015625 (1 / sqrt(4096))` | -| dynamical_decoupling | | | | | +| [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 | | | | | +| [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 | | | | | +| [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 | | | integer number of seconds in the range [1, 10800] | `10800` (3 hours) | -| optimization_level | | | `0`/`1` | `1` | +| [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` | @@ -159,7 +159,7 @@ Scroll to see the full table. | | | 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 (Note that this value strongly influences execution time.) | `32` | +| | 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` | @@ -168,14 +168,14 @@ Scroll to see the full table. | | 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 | | | `0`/`1`/`2` | `1` | -| seed_estimator | | | integer | `None` | -| simulator | | | | | +| [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](../verify/building_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 | | | | | +| [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'` | @@ -186,27 +186,26 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| default_shots | | | integer in the range[0, `backend.max_shots`] | `4096` | -| dynamical_decoupling | | | | | +| [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 | | | | | +| [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 | | | | | +| [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 | | | integer number of seconds in the range [1, 10800] | `10800` (3 hours) | -| optimization_level | | | `0`/`1` | `1` | -| simulator | | | | | +| [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](../verify/building_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 | | | | | +| [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'` | @@ -218,19 +217,19 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| optimization_level | | | `0`/`1` | `1` | +| [optimization_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | `0`/`1` | `1` | | resilience_level | | | `0`/`1`/`2` | `1` | -| dynamical_decoupling | enable | |`True`/`False` |`False` | +| [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'` | -| resilience | measure_mitigation | | `True`/`False` | `True` | +| [resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptions) | measure_mitigation | | `True`/`False` | `True` | | | measure_noise_learning | num_randomizations | | `32` | | | | shots_per_randomization | | 'auto' | | | zne_mitigation | | `True`/`False` | `False` | | | zne | noise_factors | | `(1, 3, 5)` | | | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | -| twirling | enable_gates | | `True`/`False` | `False` | +| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | | `'auto'` | | | shots_per_randomization | | | `'auto'` | @@ -241,12 +240,12 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| optimization_level | | | `0`/`1` | `1` | -| dynamical_decoupling | enable | |`True`/`False` |`False` | +| [optimization_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | `0`/`1` | `1` | +| [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'` | -| twirling | enable_gates | | `True`/`False` | `False` | +| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | | `'auto'` | | | shots_per_randomization | | | `'auto'` | From 654eac7365c4af828cf5ad749478ee9439d724d0 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 28 Jun 2024 10:16:33 -0500 Subject: [PATCH 45/63] Version with working table --- docs/run/runtime-options-overview.mdx | 26 ++++++++++--------- .../{warning--alt.svg => warning.svg} | 0 2 files changed, 14 insertions(+), 12 deletions(-) rename public/images/run/runtime-options-overview/{warning--alt.svg => warning.svg} (100%) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index a30334a898e..592db410288 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -179,7 +179,7 @@ Scroll to see the full table. | | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | -| | shots_per_randomization | | `auto`/ integer >= 1 and <= `backend.max_shots`. | `'auto'` | +| | shots_per_randomization | | `auto`/ integer no larger than `backend.max_shots`. | `'auto'` | | | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | @@ -209,7 +209,7 @@ Scroll to see the full table. | | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | -| | shots_per_randomization | | `auto`/ integer >= 1 and <= `backend.max_shots`. | `'auto'` | +| | shots_per_randomization | | `auto`/ integer no larger than `backend.max_shots`. | `'auto'` | | | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | @@ -324,14 +324,14 @@ Due to differences in the device compilation process, certain runtime features c | | fractional gates | dynamic circuits | Gate-folding ZNE | PEA | PEC | dynamical decoupling | pulse gates (Eagle only) | gate twirling | |--------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| fractional gates | | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | -| dynamic circuits | ![Incompatible](/images/run/runtime-options-overview/error.svg) | | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) (Non-conditional gates) | -| Gate-folding ZNE | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Limitations](/images/run/runtime-options-overview/warning.svg) (Might not work with custom gates
) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | -| PEA | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | -| PEC | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | -| dynamical decoupling | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | -| pulse gates (Eagle only) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Limitations](/images/run/runtime-options-overview/warning.svg) (Might not work with custom gates) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | | ![Compatible](/images/run/runtime-options-overview/checkmark.svg)
![Limitations](/images/run/runtime-options-overview/warning.svg) (Clifford entanglers only) | -| gate twirling | ![Incompatible](/images/run/runtime-options-overview/error.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) (Non-conditional gates) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Compatible](/images/run/runtime-options-overview/checkmark.svg) | ![Limitations](/images/run/runtime-options-overview/warning.svg) (Clifford entanglers only) | | +| fractional gates | | X | ✔ | X | X | ✔ | ✔ | X | +| dynamic circuits | X | | X | X | X | X | X | ✔ (Non-conditional gates) | +| Gate-folding ZNE | ✔ | X | | X | X | ✔ | ! (Might not work with custom gates) | ✔ | +| PEA | X | X | X | | X | ✔ | X | ✔ | +| PEC | X | X | X | X | | ✔ | X | ✔ | +| dynamical decoupling | ✔ | X | ✔ | ✔ | ✔ | | ✔ | ✔ | +| pulse gates (Eagle only) | ✔ | X | ! (Might not work with custom gates) | X | X | ✔ | | ✔
! (Clifford entanglers only) | +| gate twirling | X | ✔ (Non-conditional gates) | ✔ | ✔ | ✔ | ✔ | ! (Clifford entanglers only) | | ## V2 changes Options are specified differently in the V2 primitives in these ways: @@ -480,7 +480,9 @@ Shots (or precision) can be specified in multiple places in V2. They are priori 3. The `options.default_shots` value 4. The `options.default_precision` value - ```python +Example: + +```python from qiskit_ibm_runtime import SamplerV2 as Sampler # Setting shots during primitive initialization @@ -495,7 +497,7 @@ sampler.options.update(default_shots=1024, dynamical_decoupling={"sequence_type" # Sample two circuits at 128 shots each. sampler.run([circuit1, circuit2], shots=128) -``` + ``` diff --git a/public/images/run/runtime-options-overview/warning--alt.svg b/public/images/run/runtime-options-overview/warning.svg similarity index 100% rename from public/images/run/runtime-options-overview/warning--alt.svg rename to public/images/run/runtime-options-overview/warning.svg From c36921f6a5c91140703f26442ab1eb1d57c34c80 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 28 Jun 2024 10:25:10 -0500 Subject: [PATCH 46/63] clarify how to use tabs --- docs/run/runtime-options-overview.mdx | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 592db410288..a5587f9bd01 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -260,7 +260,7 @@ Scroll to see the full table. ### Options compatibility -Due to differences in the device compilation process, certain runtime features cannot be used together in a single job. See the following table for details on which features are compatible with each other: +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 not compatible with the selected feature: @@ -322,17 +322,6 @@ Due to differences in the device compilation process, certain runtime features c -| | fractional gates | dynamic circuits | Gate-folding ZNE | PEA | PEC | dynamical decoupling | pulse gates (Eagle only) | gate twirling | -|--------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| fractional gates | | X | ✔ | X | X | ✔ | ✔ | X | -| dynamic circuits | X | | X | X | X | X | X | ✔ (Non-conditional gates) | -| Gate-folding ZNE | ✔ | X | | X | X | ✔ | ! (Might not work with custom gates) | ✔ | -| PEA | X | X | X | | X | ✔ | X | ✔ | -| PEC | X | X | X | X | | ✔ | X | ✔ | -| dynamical decoupling | ✔ | X | ✔ | ✔ | ✔ | | ✔ | ✔ | -| pulse gates (Eagle only) | ✔ | X | ! (Might not work with custom gates) | X | X | ✔ | | ✔
! (Clifford entanglers only) | -| gate twirling | X | ✔ (Non-conditional gates) | ✔ | ✔ | ✔ | ✔ | ! (Clifford entanglers only) | | - ## V2 changes Options are specified differently in the V2 primitives in these ways: From b2e4b2d98aa378d123d4e8ddfbaede295bd6fe27 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 28 Jun 2024 10:33:38 -0500 Subject: [PATCH 47/63] address conflicts --- docs/run/_toc.json | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/run/_toc.json b/docs/run/_toc.json index 974fad662f0..59e76fea3a1 100644 --- a/docs/run/_toc.json +++ b/docs/run/_toc.json @@ -39,11 +39,7 @@ "url": "/run/configure-error-mitigation" }, { - "title": "Advanced runtime options", - "url": "/run/advanced-runtime-options" - }, - { - "title": "Error mitigation techniques", + "title": "Error mitigation and suppression techniques", "url": "/run/error-mitigation-explanation" } ] From 9f9fa718dfa358e444d230462a4cc17baf485e58 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 28 Jun 2024 10:36:22 -0500 Subject: [PATCH 48/63] spelling --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index a5587f9bd01..64dbc474ba1 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -314,7 +314,7 @@ Due to differences in the device compilation process, certain runtime features c - Can be used with gate twirling, but it does not work with non-Clifford entanglers. - Compatibile with all other features, with the following conditions: + Compatabile 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. From 7e8ab4489b4c920e47576e04427316130cc734a9 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 28 Jun 2024 10:40:08 -0500 Subject: [PATCH 49/63] spelling --- docs/run/runtime-options-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 64dbc474ba1..c7186198637 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -314,7 +314,7 @@ Due to differences in the device compilation process, certain runtime features c - Can be used with gate twirling, but it does not work with non-Clifford entanglers. - Compatabile with all other features, with the following conditions: + 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. From 2d349814ba46ff2544f8508c5f823abec01d254c Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 28 Jun 2024 12:21:48 -0500 Subject: [PATCH 50/63] Delete advanced-runtime-options.mdx --- docs/run/advanced-runtime-options.mdx | 328 -------------------------- 1 file changed, 328 deletions(-) delete mode 100644 docs/run/advanced-runtime-options.mdx diff --git a/docs/run/advanced-runtime-options.mdx b/docs/run/advanced-runtime-options.mdx deleted file mode 100644 index c87c2cafbce..00000000000 --- a/docs/run/advanced-runtime-options.mdx +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: Advanced Qiskit Runtime options -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. - - -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`. - -*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") -``` - - - - 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. - - -## 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 -``` -## Pass options to 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. 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) - -# Setting options after primitive initialization -# This uses auto complete. -estimator.options.optimization_level = 1 -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(mode=backend, options=options) -result = estimator.run(circuit, observable).result() -print(f">>> Metadata: {result.metadata[0]}") -``` - - - -### Primitive initialization - -You can specify options 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}) -``` - - - -### 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. - - - -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. -```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(mode=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. - - - - ```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(mode=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(mode=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). - - - - - - -### 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. - -The Qiskit Runtime primitives may perform additional runtime compilation to optimize circuits, with the degree of optimization controlled by an optimization level option. The optimization level you choose affects the compilation strategy, with higher levels invoking more expensive or aggressive optimizations. - -See the Optimization level table in the -[Runtime compilation topic](configure-runtime-compilation#set-the-optimization-level) for further details. - - - - The optimization level option is a "first-level option". Sampler V2 does not currently support `optimization_level`. - -```python -from qiskit_ibm_runtime import EstimatorV2 as Estimator - -estimator = Estimator(mode=backend, options={"optimization_level": 1}) - -# or.. -estimator.options.optimization_level = 1 -``` - -To turn off all optional runtime compilation steps, you must set `optimization_level=0`. V2 primitives do not support any advanced transpilation options. - - - - - In the currently deployed 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: - -```python -from qiskit_ibm_runtime import Estimator, Options - -options = Options(optimization_level=1) - -# or.. -options = Options() -options.optimization_level = 1 - -estimator = Estimator(mode=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(mode=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-runtime-compilation#transpilation-table). - - - -### Error mitigation - - -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). - - - -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.options.resilience_level = 2 -estimator.options.resilience.zne_mitigation = True -estimator.options.resilience.zne.noise_factors = [1, 3, 5] -``` - - - -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 = Estimator(mode=backend, options=options) -``` - - - - -## Options classes - -| 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 - - - - 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-runtime-compilation) 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. - - From 1696dce722c86069a499c72624652db737f43cc4 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 28 Jun 2024 13:59:08 -0500 Subject: [PATCH 51/63] remove unneeded images --- docs/run/runtime-options-overview.mdx | 45 ++++++++++++------- .../runtime-options-overview/checkmark.svg | 3 -- .../runtime-options-overview/close--large.svg | 3 -- .../run/runtime-options-overview/error.svg | 3 -- .../misuse--outline.svg | 3 -- .../run/runtime-options-overview/warning.svg | 3 -- 6 files changed, 28 insertions(+), 32 deletions(-) delete mode 100644 public/images/run/runtime-options-overview/checkmark.svg delete mode 100644 public/images/run/runtime-options-overview/close--large.svg delete mode 100644 public/images/run/runtime-options-overview/error.svg delete mode 100644 public/images/run/runtime-options-overview/misuse--outline.svg delete mode 100644 public/images/run/runtime-options-overview/warning.svg diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index c7186198637..81b4dd9bb37 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -218,22 +218,30 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| | [optimization_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | `0`/`1` | `1` | -| resilience_level | | | `0`/`1`/`2` | `1` | -| [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'` | -| [resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptions) | measure_mitigation | | `True`/`False` | `True` | -| | measure_noise_learning | num_randomizations | | `32` | -| | | shots_per_randomization | | 'auto' | -| | zne_mitigation | | `True`/`False` | `False` | -| | zne | noise_factors | | `(1, 3, 5)` | -| | | extrapolator | `'exponential'`
`'linear'`
`'double_exponential'`
`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | -| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | enable_gates | | `True`/`False` | `False` | -| | enable_measure | | `True`/`False` | `True` | -| | num_randomizations | | | `'auto'` | -| | shots_per_randomization | | | `'auto'` | -| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | +| [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` | | +| | routing_method | | `Basic`/`lookahead`/`stochastic`/`none` | | +| | approximation_degree | | Float in the range 0 - 1 | | +| [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](../verify/building_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) | @@ -245,7 +253,10 @@ Scroll to see the full table. | | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | | | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | | | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | -| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | enable_gates | | `True`/`False` | `False` | +| [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_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | Integer (0 - 3) | 1 | +| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | | | | | +| | enable_gates | | `True`/`False` | `False` | | | enable_measure | | `True`/`False` | `True` | | | num_randomizations | | | `'auto'` | | | shots_per_randomization | | | `'auto'` | diff --git a/public/images/run/runtime-options-overview/checkmark.svg b/public/images/run/runtime-options-overview/checkmark.svg deleted file mode 100644 index 3cc1d6fbd1b..00000000000 --- a/public/images/run/runtime-options-overview/checkmark.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/public/images/run/runtime-options-overview/close--large.svg b/public/images/run/runtime-options-overview/close--large.svg deleted file mode 100644 index 7913c8a2220..00000000000 --- a/public/images/run/runtime-options-overview/close--large.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/public/images/run/runtime-options-overview/error.svg b/public/images/run/runtime-options-overview/error.svg deleted file mode 100644 index 789d493125b..00000000000 --- a/public/images/run/runtime-options-overview/error.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/public/images/run/runtime-options-overview/misuse--outline.svg b/public/images/run/runtime-options-overview/misuse--outline.svg deleted file mode 100644 index 0e764bb3360..00000000000 --- a/public/images/run/runtime-options-overview/misuse--outline.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/public/images/run/runtime-options-overview/warning.svg b/public/images/run/runtime-options-overview/warning.svg deleted file mode 100644 index 854d608453b..00000000000 --- a/public/images/run/runtime-options-overview/warning.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - From c0bd32f2b4d13438f5a6484fd9f7e135c7719b2c Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 28 Jun 2024 14:32:47 -0500 Subject: [PATCH 52/63] Update v1 tables --- docs/run/runtime-options-overview.mdx | 42 ++++++++++++++++++--------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/docs/run/runtime-options-overview.mdx b/docs/run/runtime-options-overview.mdx index 81b4dd9bb37..97f662478a0 100644 --- a/docs/run/runtime-options-overview.mdx +++ b/docs/run/runtime-options-overview.mdx @@ -227,9 +227,9 @@ Scroll to see the full table. | [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` | | -| | routing_method | | `Basic`/`lookahead`/`stochastic`/`none` | | -| | approximation_degree | | Float in the range 0 - 1 | | +| | 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| @@ -248,19 +248,33 @@ Scroll to see the full table. | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| Options | Sub-options | Sub-sub-options | Choices | Default | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| | [optimization_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | `0`/`1` | `1` | -| [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'` | +| [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_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | Integer (0 - 3) | 1 | -| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | | | | | -| | enable_gates | | `True`/`False` | `False` | -| | enable_measure | | `True`/`False` | `True` | -| | num_randomizations | | | `'auto'` | -| | shots_per_randomization | | | `'auto'` | -| | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | +| [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](../verify/building_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) | From cbea9333e4acc93b9c4f53faacc86b66624c4de2 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 2 Jul 2024 13:19:58 -0500 Subject: [PATCH 53/63] adding recent changes to new locations --- docs/guides/configure-error-mitigation.mdx | 4 +- docs/guides/configure-error-suppression.mdx | 177 ++++++++ docs/guides/runtime-options-overview.mdx | 456 +++++++++++++++++--- 3 files changed, 582 insertions(+), 55 deletions(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 23af3a00e74..6af9a0a7a13 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -41,7 +41,7 @@ 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 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 primitives except Sampler V2 still optimize the input circuits. To bypass all optimization, 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. @@ -480,6 +480,6 @@ 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. + - 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/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index e69de29bb2d..e34d2e81c78 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -0,0 +1,177 @@ +--- +title: Configure error suppression +description: How to configure error suppression in Qiskit Runtime. (Previous topic - runtime compilation) + +--- + +# Configure error suppression for Qiskit Runtime + +Runtime compilation techniques optimize and 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 and, for Estimator V2, by setting the optimization level (`optimization_level`) option. 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. + +Estimator V2 supports optimization levels 0 and 1 only. Sampler V2 does not support setting the optimization level. + + +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`. + +*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") +``` + + +## Set the optimization level + +The `optimization_level` setting specifies how much optimization to perform on the circuits. Higher levels generate more optimized circuits, at the expense of longer compile times. + + + In primitive version 1, optimization levels 2 and 3 behave identically to level 1. Estimator V2 does not accept levels higher than 1 and Sampler V2 does not support setting the optimization level. + + + + + + + + + + + + + + + + + + + +
Optimization LevelEstimator & Sampler (V1)
0 + No optimization: typically used for hardware characterization or debugging +
1, 2, 3 + Light optimization: + + - Single-qubit gate optimization + - Two-qubit gate optimization + - Error suppression: dynamical decoupling (V1 primitives only. For V2 primitives, you can enable it by using the `dynamical_decoupling` option.) +
+ + + If using an IBM Cloud® Qiskit Runtime service instance with Q-CTRL performance management enabled, there is no need to specify runtime optimization or resilience levels, as the strategy includes an automatic preset. + + Q-CTRL defaults to `optimization_level=3` and `resilience_level=1`. + Setting `optimization_level` or `resilience_level` equal to 0 will result in an + execution error. Levels 1, 2, and 3 are permitted but will not impact performance. + Setting other options will likewise not impact performance, and it may result in a + runtime warning. For more information visit the [Q-CTRL documentation](https://docs.q-ctrl.com/q-ctrl-embedded). + + +### Example: configure Estimator with optimization levels + + + +```python +from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2 as Estimator +from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager +from qiskit.circuit.library import RealAmplitudes +from qiskit.quantum_info import SparsePauliOp + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) + +psi = RealAmplitudes(num_qubits=2, reps=2) +H = SparsePauliOp.from_list([("II", 1), ("IZ", 2), ("XI", 3)]) +theta = [0, 1, 1, 2, 3, 5] + +pm = generate_preset_pass_manager(backend=backend, optimization_level=1) +psi = pm.run(psi) +H = H.apply_layout(psi.layout) + +estimator = Estimator(mode=backend) + +estimator.options.optimization_level = 1 + +job = estimator.run([(psi, H, theta)]) + +psi1_H1 = job.result()[0] + ``` + + + +```python +from qiskit_ibm_runtime import QiskitRuntimeService, Estimator, Options +from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager +from qiskit.circuit.library import RealAmplitudes +from qiskit.quantum_info import SparsePauliOp + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) +options = Options(optimization_level=1) + +psi = RealAmplitudes(num_qubits=2, reps=2) +H = SparsePauliOp.from_list([("II", 1), ("IZ", 2), ("XI", 3)]) +theta = [0, 1, 1, 2, 3, 5] + +pm = generate_preset_pass_manager(backend=backend, optimization_level=1) +psi = pm.run(psi) +H = H.apply_layout(psi.layout) + +estimator = Estimator(options=options, mode=backend) + +job = estimator.run(circuits=[psi], observables=[H], parameter_values=[theta]) +psi1_H1 = job.result() +``` + + + + + + + If the optimization level is not specified, the service uses `optimization_level = 1`. + + + +## Advanced runtime compilation options + + + + In the V2 primitives, you can explicitly enable and disable individual error mitigation/suppression methods, such as dynamical decoupling. + + + Dynamical decoupling is not supported when the input circuits are dynamic. + +```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(backend) + +# Turn on dynamical decoupling with sequence XpXm. +sampler.options.dynamical_decoupling.enable = True +sampler.options.dynamical_decoupling.sequence_type = "XpXm" + +print(f">>> dynamical decoupling sequence to use: {sampler.options.dynamical_decoupling.sequence_type}") +``` + + + + Because all input must be ISA, options.transpilation.xxx will be ignored. + + + +## 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. + - 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/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index dadd658728c..6e109e94187 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -6,10 +6,11 @@ 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` and `qiskit_aer.primitives` 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 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 primitives except Sampler V2 still optimize the input circuits. To bypass all optimization, 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. @@ -18,11 +19,334 @@ 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 was dependant on the code version. + +The tables in the [Options classes summary section](#options-classes) 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: + +2. Any options set after primitive initialization. +3. 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**. + + + - [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](../verify/building_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](../verify/building_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](../verify/building_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 | Sub-options | Sub-sub-options | Choices | Default | +|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| +| 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](../verify/building_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 not compatible 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 +374,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. @@ -74,7 +403,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(mode=backend, options=options) +estimator = Estimator(session=backend, options=options) result = estimator.run(circuit, observable).result() print(f">>> Metadata: {result.metadata[0]}") ``` @@ -114,13 +443,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) @@ -131,7 +462,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(mode=backend, options=options) +estimator = Estimator(session=backend, options=options) result = estimator.run(circuit, observable, shots=1024).result() print(f">>> Metadata: {result.metadata[0]}") ``` @@ -148,7 +479,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 @@ -163,7 +511,7 @@ sampler.options.update(default_shots=1024, dynamical_decoupling={"sequence_type" # Sample two circuits at 128 shots each. sampler.run([circuit1, circuit2], shots=128) -``` + ``` @@ -176,7 +524,7 @@ from qiskit_ibm_runtime import Estimator, Options options = Options() options.execution.shots = 1024 -estimator = Estimator(mode=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 @@ -185,7 +533,7 @@ shots directly in the `run()` method. This overwrites the initial `shots` settin ```python from qiskit_ibm_runtime import Estimator -estimator = Estimator(mode=backend) +estimator = Estimator(session=backend) estimator.run(circuits=circuits, observables=observables, shots=50) @@ -200,16 +548,14 @@ For more information about the primitive options, refer to the - - -### Runtime compilation +### Error suppression 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. -The Qiskit Runtime primitives may perform additional runtime compilation to optimize circuits, with the degree of optimization controlled by an optimization level option. The optimization level you choose affects the compilation strategy, with higher levels invoking more expensive or aggressive optimizations. +The Qiskit Runtime primitives may perform additional error suppression to optimize circuits, with the degree of optimization controlled by an optimization level option. The optimization level you choose affects the error suppression strategy, with higher levels invoking more expensive or aggressive optimizations. See the Optimization level table in the -[Runtime compilation topic](./configure-error-suppression#set-the-optimization-level) for further details. +[Configure error suppression topic](configure-error-suppression#set-the-optimization-level) for further details. @@ -218,18 +564,16 @@ See the Optimization level table in the ```python from qiskit_ibm_runtime import EstimatorV2 as Estimator -estimator = Estimator(mode=backend, options={"optimization_level": 1}) +estimator = Estimator(session=backend, options={"optimization_level": 1}) # or.. estimator.options.optimization_level = 1 ``` - -To turn off all optional runtime compilation steps, you must set `optimization_level=0`. V2 primitives do not support any advanced transpilation options. - In the currently deployed 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. + In original (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: @@ -243,22 +587,11 @@ options = Options(optimization_level=1) options = Options() options.optimization_level = 1 -estimator = Estimator(mode=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(mode=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). @@ -274,7 +607,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 @@ -298,22 +631,39 @@ options = Options(resilience_level = 2) options = Options() options.resilience_level = 2 -estimator = Estimator(mode=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 @@ -321,7 +671,7 @@ estimator = Estimator(mode=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 From c7210f4103b839752725d63d921b3002cba74519 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 2 Jul 2024 13:28:16 -0500 Subject: [PATCH 54/63] links --- docs/guides/configure-error-mitigation.mdx | 4 ++-- docs/guides/configure-error-suppression.mdx | 4 ++-- docs/guides/primitives.mdx | 2 +- docs/guides/runtime-options-overview.mdx | 12 ++++++------ 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 6af9a0a7a13..3258e2eca53 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -41,7 +41,7 @@ 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 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 primitives except Sampler V2 still optimize the input circuits. To bypass all optimization, 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. @@ -480,6 +480,6 @@ 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. + - 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/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index e34d2e81c78..651bc1c1234 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -13,7 +13,7 @@ Primitives let you employ runtime compilation by choosing advanced runtime compi Estimator V2 supports optimization levels 0 and 1 only. Sampler V2 does not support setting the optimization level. -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 primitives except Sampler V2 still optimize the input circuits. To bypass all optimization, 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. @@ -172,6 +172,6 @@ For instructions to turn off all error suppression, see the [Turn off all error - 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/primitives.mdx b/docs/guides/primitives.mdx index 7d76cc3345c..08ad8ee8cc8 100644 --- a/docs/guides/primitives.mdx +++ b/docs/guides/primitives.mdx @@ -65,7 +65,7 @@ Version 2 (available with qiskit-ibm-runtime 0.21.0) is the first major interfac * 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 6e109e94187..06a8475cd1c 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 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 primitives except Sampler V2 still optimize the input circuits. To bypass all optimization, 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. @@ -171,7 +171,7 @@ Scroll to see the full table. | [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](../verify/building_noise_models), or its representation | `None` | +| | 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) | @@ -201,7 +201,7 @@ 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.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](../verify/building_noise_models), or its representation | `None` | +| | 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) | @@ -238,7 +238,7 @@ Scroll to see the full table. | | 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](../verify/building_noise_models), or its representation | `None` | +| | 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) | @@ -271,7 +271,7 @@ Scroll to see the full table. | | 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](../verify/building_noise_models), or its representation | `None` | +| | 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) | @@ -672,6 +672,6 @@ 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. + - 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 From 4156e3144a4a232bf70f123abbeca56bc8be93d5 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 2 Jul 2024 15:36:49 -0500 Subject: [PATCH 55/63] Don't need two tabs for V1 --- docs/guides/runtime-options-overview.mdx | 44 ++---------------------- 1 file changed, 2 insertions(+), 42 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 06a8475cd1c..25cbf7dc106 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -106,15 +106,7 @@ estimator.options.resilience.zne_mitigation = True - [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**. - - + - [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. @@ -214,7 +206,7 @@ Scroll to see the full table. - + | Options | Sub-options | Sub-sub-options | Choices | Default | |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| | [optimization_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options) | | | `0`/`1` | `1` | @@ -245,38 +237,6 @@ Scroll to see the full table. - -| Options | Sub-options | Sub-sub-options | Choices | Default | -|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| -| 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) | - - From daa93ab3e47fda4c01bf1d7bea4a88a80c734f16 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 2 Jul 2024 16:09:58 -0500 Subject: [PATCH 56/63] edits --- docs/guides/runtime-options-overview.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 25cbf7dc106..1eeab5e8250 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -32,15 +32,15 @@ When calling the primitives, you can pass in options by using an options class o 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 was dependant on the code version. -The tables in the [Options classes summary section](#options-classes) lists the default values. +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: -2. Any options set after primitive initialization. -3. Any options set during primitive initialization. +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. @@ -69,7 +69,7 @@ If you set `default_shots` in an estimator, it overrides any value set for `defa 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`. +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 @@ -441,13 +441,13 @@ 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. Int-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 2. The `run(...,precision=val)` value @@ -519,7 +519,7 @@ See the Optimization level table in the - The optimization level option is a "first-level option". Sampler V2 does not currently support `optimization_level`. + The optimization level option is a "first-level option". Sampler V2 does not support `optimization_level`. ```python from qiskit_ibm_runtime import EstimatorV2 as Estimator From 43766c65acdae868959af3a150411560d211bff6 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 10 Jul 2024 13:21:31 -0500 Subject: [PATCH 57/63] no optimization is done in V2 --- 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 651bc1c1234..b45a344031d 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -6,7 +6,7 @@ description: How to configure error suppression in Qiskit Runtime. (Previous top # Configure error suppression for Qiskit Runtime -Runtime compilation techniques optimize and 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. +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 and, for Estimator V2, by setting the optimization level (`optimization_level`) option. 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. From 626fd4da0de50fcff6e1884d626d0a708ef20436 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 16 Jul 2024 10:40:36 -0500 Subject: [PATCH 58/63] add more links --- docs/guides/get-started-with-primitives.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guides/get-started-with-primitives.mdx b/docs/guides/get-started-with-primitives.mdx index ee2106da752..6a370754e4d 100644 --- a/docs/guides/get-started-with-primitives.mdx +++ b/docs/guides/get-started-with-primitives.mdx @@ -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. From 10dcf23037f8357f80cb9ec02af6460a7c93ef43 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 16 Jul 2024 12:09:08 -0500 Subject: [PATCH 59/63] Updates --- docs/guides/_toc.json | 2 +- docs/guides/configure-error-suppression.mdx | 6 ++---- docs/guides/get-started-with-primitives.mdx | 6 +++--- docs/guides/primitives.mdx | 10 +++++----- 4 files changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 863964b0f0f..ebca94f7a18 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -294,7 +294,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-suppression.mdx b/docs/guides/configure-error-suppression.mdx index b45a344031d..14902a144d8 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -8,12 +8,10 @@ description: How to configure error suppression in Qiskit Runtime. (Previous top 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 and, for Estimator V2, by setting the optimization level (`optimization_level`) option. 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. - -Estimator V2 supports optimization levels 0 and 1 only. Sampler V2 does not support setting the optimization level. +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 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. diff --git a/docs/guides/get-started-with-primitives.mdx b/docs/guides/get-started-with-primitives.mdx index 6a370754e4d..c5163285904 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) diff --git a/docs/guides/primitives.mdx b/docs/guides/primitives.mdx index 08ad8ee8cc8..6832e78f594 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. @@ -36,7 +36,7 @@ Providers like Qiskit Runtime enable access to appropriate systems through nativ their own 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 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. @@ -48,7 +48,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 `optimization_level` and `resilience_level`, rather than building your own implementation of these techniques. @@ -59,7 +59,7 @@ 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**. From dc9d153560edaa9308aa2ae43834305f291a1943 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 16 Jul 2024 13:02:00 -0500 Subject: [PATCH 60/63] edits and new image --- docs/guides/configure-error-mitigation.mdx | 21 +++-------- docs/guides/configure-error-suppression.mdx | 6 ++-- .../guides/execution-modes/resilience-2.svg | 33 ++++++++++++++++++ public/images/optimize/resilience-2.psd | Bin 0 -> 399862 bytes 4 files changed, 41 insertions(+), 19 deletions(-) create mode 100644 public/images/guides/execution-modes/resilience-2.svg create mode 100644 public/images/optimize/resilience-2.psd diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 93b22876640..30bc93787bb 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 @@ -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`. diff --git a/docs/guides/configure-error-suppression.mdx b/docs/guides/configure-error-suppression.mdx index da86e9175a0..c84d99d5caf 100644 --- a/docs/guides/configure-error-suppression.mdx +++ b/docs/guides/configure-error-suppression.mdx @@ -128,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. @@ -156,7 +156,7 @@ 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. diff --git a/public/images/guides/execution-modes/resilience-2.svg b/public/images/guides/execution-modes/resilience-2.svg new file mode 100644 index 00000000000..efbb2f341df --- /dev/null +++ b/public/images/guides/execution-modes/resilience-2.svg @@ -0,0 +1,33 @@ + + + + + + Mitigated value + Expectation value + Noise amplification factor + Exact value + Unmitigated value + Noise amplified values + 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 From 724189923c90cae5594236d666cb02ee665391e5 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 16 Jul 2024 13:07:03 -0500 Subject: [PATCH 61/63] move image --- docs/guides/configure-error-mitigation.mdx | 4 ++-- .../{guides/execution-modes => optimize}/resilience-2.svg | 0 2 files changed, 2 insertions(+), 2 deletions(-) rename public/images/{guides/execution-modes => optimize}/resilience-2.svg (100%) diff --git a/docs/guides/configure-error-mitigation.mdx b/docs/guides/configure-error-mitigation.mdx index 30bc93787bb..07316d8a89c 100644 --- a/docs/guides/configure-error-mitigation.mdx +++ b/docs/guides/configure-error-mitigation.mdx @@ -128,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.svg "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, @@ -206,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, diff --git a/public/images/guides/execution-modes/resilience-2.svg b/public/images/optimize/resilience-2.svg similarity index 100% rename from public/images/guides/execution-modes/resilience-2.svg rename to public/images/optimize/resilience-2.svg From 22446a56aefa454a189aedcab4f0a2a7a861bc68 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 16 Jul 2024 13:08:02 -0500 Subject: [PATCH 62/63] delete extra code --- docs/guides/runtime-options-overview.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 7f5fcfe8029..be9f52f206f 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -534,8 +534,6 @@ 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 From d4ee49e1cbc03ca86c4153630af4faa650fc4b80 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 16 Jul 2024 14:10:16 -0500 Subject: [PATCH 63/63] Edis --- docs/guides/runtime-options-overview.mdx | 32 ++++++++++++------------ 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index be9f52f206f..92dfd5883ad 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -6,7 +6,7 @@ description: Specify options when building with Qiskit Runtime primitives # Advanced Qiskit Runtime 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` and `qiskit_aer.primitives` 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. @@ -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 was 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 dependant on the code version. The tables in the [Options classes summary](#options-classes) section lists the default values. @@ -90,12 +90,12 @@ 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. 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**. + - [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. @@ -128,7 +128,7 @@ 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_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` | @@ -142,7 +142,7 @@ Scroll to see the full table. | [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) | +| [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` | @@ -171,14 +171,14 @@ Scroll to see the full table. | | 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'` | +| | 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` | +| [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'` | @@ -191,7 +191,7 @@ Scroll to see the full table. | [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) | +| [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` | @@ -201,7 +201,7 @@ Scroll to see the full table. | | 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'` | +| | shots_per_randomization | | `auto`/ Integer no larger than `backend.max_shots`. | `'auto'` | | | strategy | | `'active'`
`'active-circuit'`
`'active-accum'`
`'all'` | `'active-accum'` | @@ -211,7 +211,7 @@ Scroll to see the full table. |----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------| | [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) | +| [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 | | | | @@ -224,7 +224,7 @@ Scroll to see the full table. | | 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| +| | 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` | @@ -245,7 +245,7 @@ Scroll to see the full table. ### 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 not compatible with the selected feature: +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: @@ -509,10 +509,10 @@ For more information about the primitive options, refer to the ### Error suppression -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. +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/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.