215 lines
22 KiB
Plaintext
215 lines
22 KiB
Plaintext
---
|
|
title: Introduction to options
|
|
description: Available options for building with Qiskit Runtime primitives
|
|
|
|
---
|
|
|
|
# Introduction to options
|
|
|
|
You can pass options to primitives to customize them to meet your needs. This section focuses on Qiskit Runtime primitive options. While the interface of the primitives' `run()` method is common across all implementations, their options are not. Consult the corresponding API references for information about the [`qiskit.primitives`](/api/qiskit/primitives#primitives) and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) options.
|
|
|
|
## Overview
|
|
|
|
<span id="options-structure"></span>
|
|
### Structure
|
|
|
|
When calling the primitives, you can pass in options by using an options class or a dictionary. Commonly used options, such as `resilience_level`, are at the first level. Other options are grouped into different categories, such as `execution`. See the [Set primitive options](specify-runtime-options) topic for full details.
|
|
|
|
<span id="options-defaults"></span>
|
|
### Defaults
|
|
|
|
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.
|
|
|
|
The tables in the [Options classes summary](#options-classes) section lists the default values.
|
|
|
|
<span id="options-precedence"></span>
|
|
## Set options
|
|
|
|
Options can be defined before a primitive is constructed and passed to the primitive, which makes a copy of them. This can be done either as a nested dictionary, or by using the options classes. Additionally, after the primitive is constructed, its options can be changed. Use the workflow that works best for your application. See [Specify options](specify-runtime-options) for full details.
|
|
|
|
<span id="options-classes"></span>
|
|
## Options classes summary
|
|
|
|
<Tabs>
|
|
<TabItem value="Estimator" label="Estimator">
|
|
- [Resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2): Advanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC.
|
|
- [Dynamical decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions): Options for dynamical decoupling.
|
|
- [Execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2): Primitive execution options, including whether to initialize qubits and the repetition delay.
|
|
- [Twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions): Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample.
|
|
- [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.
|
|
</TabItem>
|
|
|
|
<TabItem value="Sampler" label="Sampler">
|
|
- [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.
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
<span id="options-table"></span>
|
|
### Available options
|
|
|
|
<Admonition type="caution" title="Important">
|
|
Scroll to see the full table.
|
|
</Admonition>
|
|
|
|
<Tabs>
|
|
<TabItem value="Estimator" label="Estimator">
|
|
| Option | Sub-option | Sub-sub-option | Choices | Default | Options |
|
|
|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------|----------------------|
|
|
| [default_shots](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | Integer in the range[0, `backend.max_shots`]| None | default_shots |
|
|
| [default_precision](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | float > 0 | `0.015625 (1 / sqrt(4096))` | default_precision |
|
|
| [dynamical_decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions) | | | | | dynamical_decoupling |
|
|
| | enable | | `True`/`False` | `False` | |
|
|
| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | |
|
|
| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | |
|
|
| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | |
|
|
| [environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | | | | | environment |
|
|
| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | |
|
|
| | callback | |Callable function that receives Job ID and Job result. |`None` | |
|
|
| | job_tags | |List of tags |`None` | |
|
|
| [execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2) | | | | | execution |
|
|
| | init_qubits | | `True`/`False` | `True` | |
|
|
| | rep_delay | | Value in the range supplied by `backend.rep_delay_range`. | Given by `backend.default_rep_delay`.| |
|
|
| [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | max_execution_time |
|
|
| [resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2) | | | | | resilience |
|
|
| | [layer_noise_learning](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.LayerNoiseLearningOptions) | | `True`/`False` | `True` | |
|
|
| | | max_layers_to_learn | `None`/ integer >= 1 | `4` | |
|
|
| | | shots_per_randomization | integer >= 1 | `128` | |
|
|
| | | num_randomizations | integer >= 1 | `32` | |
|
|
| | | layer_pair_depths | list[int] of 2-10 values in the range [0, 200] | `(0, 1, 2, 4, 16, 32)` | |
|
|
| | measure_mitigation | | `True`/`False` | `True` | |
|
|
| | [measure_noise_learning](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.MeasureNoiseLearningOptions) | num_randomizations | integer >= 1 | `32` | |
|
|
| | | shots_per_randomization | integer | 'auto' | |
|
|
| | pec_mitigation | | `True`/`False` | `False` | |
|
|
| | [pec](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.PecOptions) | max_overhead | `None`/ integer >1 | `100` | |
|
|
| | | noise_gain | `auto`/ float in the range `[0, 1]` | `auto` | |
|
|
| | zne_mitigation | | `True`/`False` | `False` | |
|
|
| | [zne](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ZneOptions) | noise_factors | list of floats; each float >= 1 | `(1, 1.5, 2)` for PEA, and `(1, 3, 5)` otherwise. | |
|
|
| | | amplifier | `gate_folding`, `gate_folding_front`, `gate_folding_back, pea ` | `gate_folding` | |
|
|
| | | extrapolator | one or more of `'exponential'`<br />`'linear'`<br />`'double_exponential'`<br />`'polynomial_degree_(1 <= k <= 7)'` | (`'exponential'`, `'linear'`) | |
|
|
| [resilience_level](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | `0`/`1`/`2` | `1` | resilience_level |
|
|
| [seed_estimator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) | | | integer | `None` | seed_estimator |
|
|
| [simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | | | | | simulator |
|
|
| | noise_model | | [Qiskit Aer NoiseModel](build-noise-models), or its representation | `None` | |
|
|
| | seed_simulator | | integer | `None` | |
|
|
| | coupling_map | | List of directed two-qubit interactions | full connectivity | |
|
|
| | basis_gates | | List of basis gate names to unroll to | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | |
|
|
| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | | | | | twirling |
|
|
| | enable_gates | | `True`/`False` | `False` | |
|
|
| | enable_measure | | `True`/`False` | `True` | |
|
|
| | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | |
|
|
| | shots_per_randomization | | `auto`/ Integer no larger than `backend.max_shots`. | `'auto'` | |
|
|
| | strategy | | `'active'`<br />`'active-circuit'`<br />`'active-accum'`<br />`'all'` | `'active-accum'` | |
|
|
</TabItem>
|
|
|
|
<TabItem value="Sampler" label="Sampler">
|
|
| Option | Sub-option | Sub-sub-option | Choices | Default | Option |
|
|
|----------------------|--------------------------|-------------------------|-------------------------------------------------------------------------------------------|---------------------------|-------------------------|
|
|
| [default_shots](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions) | | | Integer in the range[0, `backend.max_shots`] | `4096` | default_shots |
|
|
| [dynamical_decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions) | | | | | dynamical_decoupling |
|
|
| | enable | | `True`/`False` | `False` | |
|
|
| | sequence_type | | `'XX'`/`'XpXm'`/`'XY4'` | `'XX'` | |
|
|
| | extra_slack_distribution | | `'middle'`/`'edges'` | `'middle'` | |
|
|
| | scheduling_method | | `'asap'`/`'alap'` | `'alap'` | |
|
|
| [environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | | | | | |
|
|
| | log_level | |`DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` |`WARNING` | environment |
|
|
| | callback | |Callable function that receives Job ID and Job result. |`None` | |
|
|
| | job_tags | |List of tags |`None` | |
|
|
| [execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2) | | | | | |
|
|
| | init_qubits | | `True`/`False` | `True` | execution |
|
|
| | rep_delay | | Value in the range supplied by `backend.rep_delay_range`. | Given by `backend.default_rep_delay`.| |
|
|
| [max_execution_time](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions) | | | Integer number of seconds in the range [1, 10800] | `10800` (3 hours) | |
|
|
| [simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | | | | | max_execution_time |
|
|
| | noise_model | | [Qiskit Aer NoiseModel](build-noise-models), or its representation | `None` | simulator |
|
|
| | seed_simulator | | integer | `None` | |
|
|
| | coupling_map | | List of directed two-qubit interactions | full connectivity | |
|
|
| | basis_gates | | List of basis gate names to unroll to | The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) | |
|
|
| [twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | | | | | |
|
|
| | enable_gates | | `True`/`False` | `False` | twirling |
|
|
| | enable_measure | | `True`/`False` | `True` | |
|
|
| | num_randomizations | | `auto`/ integer >= 1 | `'auto'` | |
|
|
| | shots_per_randomization | | `auto`/ Integer no larger than `backend.max_shots`. | `'auto'` | |
|
|
| | strategy | | `'active'`<br />`'active-circuit'`<br />`'active-accum'`<br />`'all'` | `'active-accum'` | |
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
|
|
<span id="options-compatibility-table"></span>
|
|
### Options compatibility
|
|
|
|
Due to differences in the device compilation process, certain runtime features cannot be used together in a single job. Click the appropriate tab for a list of features that are incompatible with the selected feature:
|
|
|
|
<Tabs>
|
|
<TabItem value="Dynamic" label="Dynamic circuits">
|
|
Incompatible with:
|
|
- Gate-folding ZNE
|
|
- PEA
|
|
- PEC
|
|
- Dynamical decoupling
|
|
- Pulse gates
|
|
|
|
Can be used with gate twirling for non-conditional gates.
|
|
</TabItem>
|
|
|
|
<TabItem value="ZNE" label="Gate-folding ZNE">
|
|
Incompatible with:
|
|
- Dynamic circuits
|
|
- PEA
|
|
- PEC
|
|
|
|
Can be used with pulse gates, but it might not work when using custom gates.
|
|
</TabItem>
|
|
|
|
<TabItem value="PEA" label="PEA">
|
|
Incompatible with:
|
|
- Dynamic circuits
|
|
- Gate-folding ZNE
|
|
- PEC
|
|
- Pulse gates
|
|
</TabItem>
|
|
|
|
<TabItem value="PEC" label="PEC">
|
|
Incompatible with:
|
|
- Dynamic circuits
|
|
- Gate-folding ZNE
|
|
- PEA
|
|
- Pulse gates
|
|
</TabItem>
|
|
<TabItem value="DD" label="Dynamical decoupling">
|
|
Incompatible with dynamic circuits.
|
|
|
|
</TabItem>
|
|
<TabItem value="Pulse" label="Pulse gates (Eagle only)">
|
|
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.
|
|
</TabItem>
|
|
<TabItem value="Twirling" label="Gate twirling">
|
|
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.
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
## Next steps
|
|
|
|
<Admonition type="tip" title="Recommendations">
|
|
- Find more details about the `EstimatorV2` methods in the [Estimator API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.EstimatorV2).
|
|
- Find more details about the `SamplerV2` methods in the [Sampler API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.SamplerV2).
|
|
- Find details about how to configure [error suppression](configure-error-suppression) and [error mitigation](configure-error-mitigation).
|
|
- Learn how to [specify options](specify-runtime-options).
|
|
</Admonition> |