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 section 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
- Dynamical decoupling: Options for dynamical decoupling.
- Environment: Execution environment options, such as the logging level to set and job tags to add.
- Execution: Primitive execution options, including whether to initialize qubits and the repetition delay.
- Resilience: Advanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC.
- Simulator: Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to local testing mode only.
- Twirling: Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample.
- Dynamical decoupling: Options for dynamical decoupling.
- Environment: Execution environment options, such as the logging level to set and job tags to add.
- Execution: Primitive execution options, including whether to initialize qubits and the repetition delay.
- Simulator: Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to local testing mode only.
- Twirling: Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample.
Available options
The following table documents options from the latest version of qiskit-ibm-runtime. To see older option versions, visit the qiskit-ibm-runtime API reference and select a previous version.
The total number of shots to use per circuit per configuration.
Choices: Integer >= 0 Default: None
The default precision to use for any PUB or run() call that does not specify one.
Choices: Float > 0 Default: 0.015625 (1 / sqrt(4096))
Control dynamical decoupling error mitigation settings.
Callable function that receives the Job ID and Job result.
Choices: None Default: None
Whether to reset the qubits to the ground state for each shot.
Choices: True, False
Default: True
Choices: Integer number of seconds in the range [1, 10800] Default: 10800 (3 hours)
Advanced resilience options to fine tune the resilience strategy.
Options for learning layer noise.
Choices: list[int] of 2-10 values in the range [0, 200]
Default: (0, 1, 2, 4, 16, 32)
Options for measurement noise learning.
Probabilistic error cancellation mitigation options.
Choices: auto, float in the range [0, 1]
Default: auto
Choices: True, False
Default: False
Choices: gate_folding, gate_folding_front, gate_folding_back, pea
Default: gate_folding
Choices: List of floats
Default: [0, *noise_factors]
Choices: One or more of: exponential, linear, double_exponential, polynomial_degree_(1 <= k <= 7), fallback
Default: (exponential, linear)
How much resilience to build against errors. Higher levels generate more accurate results at the expense of longer processing times.
Choices: 0, 1, 2
Default: 1
Options to pass when simulating a backend
Choices: List of basis gate names to unroll to Default: The set of all basis gates supported by Qiskit Aer simulator
Choices: Qiskit Aer NoiseModel, or its representation Default: None
Twirling options
The total number of shots to use per circuit per configuration.
Choices: Integer >= 0 Default: None
Control dynamical decoupling error mitigation settings.
Callable function that receives the Job ID and Job result.
Choices: None Default: None
Whether to reset the qubits to the ground state for each shot.
Choices: True, False
Default: True
The delay between a measurement and the subsequent quantum circuit.
Choices: Value in the range supplied by backend.rep_delay_range
Default: Given by backend.default_rep_delay
Choices: Integer number of seconds in the range [1, 10800] Default: 10800 (3 hours)
Options to pass when simulating a backend
Choices: List of basis gate names to unroll to Default: The set of all basis gates supported by Qiskit Aer simulator
Choices: Qiskit Aer NoiseModel, or its representation Default: None
Twirling options
Feature 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
- Fractional gates
Other notes:
- Can be used with gate twirling for non-conditional gates.
- Dynamic circuits are not supported on all QPUs. Additionally, some dynamic circuit functions have been deprecated. For details, see Classical feedforward and control flow.
Incompatible with dynamic circuits.
Incompatible with:
- Dynamic circuits
- Gate twirling
- PEA
- PEC
Incompatible with:
- Dynamic circuits
- PEA
- PEC
Might not work when using custom gates.
Incompatible with fractional gates.
Other notes:
- Can be used with dynamic circuits with non-conditional gates.
- Does not work with non-Clifford entanglers.
Incompatible with:
- Dynamic circuits
- Fractional gates
- Gate-folding ZNE
- PEC
Incompatible with:
- Dynamic circuits
- Fractional gates
- Gate-folding ZNE
- PEA
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.