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 and qiskit_aer.primitives(opens in a new tab) 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 QPU (quantum processing unit) before being submitted to the Qiskit Runtime primitives. These are referred to as instruction set architecture (ISA) circuits and observables. See the transpilation documentation 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.
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. 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 topic for full details.
Defaults
For V2 primitives, if you do not specify a value for an option, it is given a special value of Unset and the server default value is used. Thus, the default value will be the same regardless of your code version.
For V1 primitives, if you do not specify a value for an option, the Qiskit Runtime client's default value is used. In V1, the default value is dependent on the code version.
The tables in the Options classes summary section lists the default values.
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 for full details.
Options classes summary
- Resilience: Advanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC.
- Dynamical decoupling: Options for dynamical decoupling.
- Execution: Primitive execution options, including whether to initialize qubits and the repetition delay.
- Twirling: Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample.
- Environment: Execution environment options, such as the logging level to set and job tags to add.
- Simulator: Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to local testing mode only.
- Dynamical decoupling: Options for dynamical decoupling.
- Execution: Primitive execution options, including whether to initialize qubits and the repetition delay.
- Twirling: Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample.
- Environment: Execution environment options, such as the logging level to set and job tags to add.
- Simulator: Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to local testing mode only.
- Resilience: Advanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC. Estimator only.
- Dynamical decoupling: Options for dynamical decoupling.
- Execution: Primitive execution options, including whether to initialize qubits and the repetition delay.
- Twirling: Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample.
- Environment: Execution environment options, such as the logging level to set and job tags to add.
- Simulator: 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.
| Option | Sub-option | Sub-sub-option | Choices | Default | Options |
|---|---|---|---|---|---|
| default_shots | Integer in the range[0, backend.max_shots] | None | default_shots | ||
| default_precision | float > 0 | 0.015625 (1 / sqrt(4096)) | default_precision | ||
| dynamical_decoupling | dynamical_decoupling | ||||
| enable | True/False | False | |||
| sequence_type | 'XX'/'XpXm'/'XY4' | 'XX' | |||
| extra_slack_distribution | 'middle'/'edges' | 'middle' | |||
| scheduling_method | 'asap'/'alap' | 'alap' | |||
| environment | 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 | 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) | max_execution_time | ||
| resilience | resilience | ||||
| layer_noise_learning | 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_mitigation | True/False | False | |||
| pec | max_overhead | None/ integer >1 | 100 | ||
| noise_gain | auto/ float in the range [0, 1] | auto | |||
| 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 | 0/1/2 | 1 | resilience_level | ||
| seed_estimator | integer | None | seed_estimator | ||
| simulator | simulator | ||||
| noise_model | Qiskit Aer NoiseModel, 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(opens in a new tab) | |||
| twirling | twirling | ||||
| enable_gates | True/False | False | |||
| enable_measure | True/False | True | |||
| num_randomizations | auto/ integer >= 1 | 'auto' | |||
| shots_per_randomization | auto/ Integer no larger than backend.max_shots. | 'auto' | |||
| strategy | 'active''active-circuit''active-accum''all' | 'active-accum' |
| Option | Sub-option | Sub-sub-option | Choices | Default | Option |
|---|---|---|---|---|---|
| default_shots | Integer in the range[0, backend.max_shots] | 4096 | default_shots | ||
| dynamical_decoupling | dynamical_decoupling | ||||
| enable | True/False | False | |||
| sequence_type | 'XX'/'XpXm'/'XY4' | 'XX' | |||
| extra_slack_distribution | 'middle'/'edges' | 'middle' | |||
| scheduling_method | 'asap'/'alap' | 'alap' | |||
| environment | |||||
| 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 | |||||
| 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 | Integer number of seconds in the range [1, 10800] | 10800 (3 hours) | |||
| simulator | max_execution_time | ||||
| noise_model | Qiskit Aer NoiseModel, 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(opens in a new tab) | |||
| twirling | |||||
| enable_gates | True/False | False | twirling | ||
| enable_measure | True/False | True | |||
| num_randomizations | auto/ integer >= 1 | 'auto' | |||
| shots_per_randomization | auto/ Integer no larger than backend.max_shots. | 'auto' | |||
| strategy | 'active''active-circuit''active-accum''all' | 'active-accum' |
| Option | Sub-option | Sub-sub-option | Choices | Default | Option |
|---|---|---|---|---|---|
| resilience_level | 0/1/2 | 1 | resilience_level | ||
| max_execution_time | Integer number of seconds in the range [1, 10800] | 10800 (3 hours) | max_execution_time | ||
| resilience | resilience | ||||
| extrapolator | LinearExtrapolator/QuadraticExtrapolator/CubicExtrapolator/QuarticExtrapolator | None, or LinearExtrapolator if resilience_level=2. | |||
| noise_amplifier | |||||
| noise_factors | Applies only for resilience_level=2. List of real valued noise factors. | (1, 3, 5) | |||
| transpilation | transpilation | ||||
| skip_transpilation | True/False | False | |||
| initial_layout | layout instance, dictionary, list, or None. See qiskit.compiler. | 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 | execution | ||||
| init_qubits | True/False | True | |||
| shots | Integer no larger than backend.max_shots. | 4000 | |||
| environment | environment | ||||
| log_level | DEBUG/INFO/WARNING/ERROR/CRITICAL | WARNING | |||
| callback | Callable function that receives Job ID and Job result. | None | |||
| job_tags | List of tags | None | |||
| simulator | simulator | ||||
| noise_model | Qiskit Aer NoiseModel, 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(opens in a new tab) |
Options compatibility
Due to differences in the device compilation process, certain runtime features cannot be used together in a single job. Click the appropriate tab for a list of features that are incompatible with the selected feature:
Incompatible with:
- Gate-folding ZNE
- PEA
- PEC
- Dynamical decoupling
- Pulse gates
Can be used with gate twirling for non-conditional gates.
Incompatible with:
- Dynamic circuits
- PEA
- PEC
Can be used with pulse gates, but it might not work when using custom gates.
Incompatible with:
- Dynamic circuits
- Gate-folding ZNE
- PEC
- Pulse gates
Incompatible with:
- Dynamic circuits
- Gate-folding ZNE
- PEA
- Pulse gates
Incompatible with dynamic circuits.
Incompatible with:
- Dynamic circuits
- PEA
- PEC
- Dynamical decoupling
Other notes:
- Can be used with gate-folding ZNE, but it might not work with custom gates.
- Can be used with gate twirling, but it does not work with non-Clifford entanglers.
Compatible with all other features, with the following conditions:
- Can be used with dynamic circuits with non-conditional gates.
- Can be used with pulse gates, but it does not work with non-Clifford entanglers.
Next steps
- Find more details about the
Estimatormethods in the Estimator API reference. - Find more details about the
Samplermethods in the Sampler API reference. - Find all available options in the Options API reference.
- Find details about how to configure error suppression and error mitigation.
- Learn how to specify options.