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.

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.

Important

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'`
	skip_reset_qubits		`True`/`False`	`False`
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	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'`
	skip_reset_qubits	`True`/`False`	`False`
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

Note

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_fez, ibm_marrakesh, ibm_torino, ibm_brisbane, and ibm_strasbourg.

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
gen3-turbo
PEA
PEC
Dynamical decoupling
Fractional gates
Pulse gates

Can be used with gate twirling for non-conditional gates.

Incompatible with:

Dynamic circuits
Fractional gates
Pulse gates
meas_type=kerneled or meas_type=avg_kerneled (measurement level 1)
Parameter expressions with arithmetic operations

Next steps

Recommendations

Find more details about the EstimatorV2 methods in the Estimator API reference.
Find more details about the SamplerV2 methods in the Sampler API reference.
Find details about how to configure error suppression and error mitigation.
Learn how to specify options.