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 options.
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
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 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.
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, 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''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 | |||
| 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' | |||
| experimental | |||||
| execution_path | gen3-turbo (see note) | None |
| 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 | |||
| 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' | |||
| experimental | |||||
| execution_path | gen3-turbo (see note) | None |
Setting gen3-turbo enables the next-generation execution path, which provides a great improvement in performance. This option is experimental (subject to change without notice, and stability is not guaranteed) and is only available on ibm_torino.
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.
Incompatible with:
- Dynamic circuits
meas_type=kerneledormeas_type=avg_kerneled- Fractional gates
Next steps
- Find more details about the
EstimatorV2methods in the Estimator API reference. - Find more details about the
SamplerV2methods in the Sampler API reference. - Find details about how to configure error suppression and error mitigation.
- Learn how to specify options.