Skip to main content
IBM Quantum Platform

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.

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

    default_shots API documentation

  • 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))

    default_precision API documentation

  • Control dynamical decoupling error mitigation settings.

    dynamical_decoupling API documentation

    • Choices: True, False

      Default: False

    • Choices: middle, edges

      Default: middle

    • Choices: asap, alap Default: alap

    • Choices: XX, XpXm, XY4 Default: XX

    • Choices: True, False Default: False

  • environment API documentation

    • Callable function that receives the Job ID and Job result.

      Choices: None

      Default: None

    • List of tags.

      Choices: None

      Default: None

    • Choices: DEBUG, INFO, WARNING, ERROR, CRITICAL

      Default: WARNING

    • Choices: True, False

      Default: False

  • execution API documentation

    • 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)

    max_execution_time API documentation

  • Advanced resilience options to fine tune the resilience strategy.

    resilience API documentation

    • Options for learning layer noise.

      resilience.layer_noise_learning API documentation

    • Choices: list[int] of 2-10 values in the range [0, 200]

      Default: (0, 1, 2, 4, 16, 32)

    • Choices: None, Integer >= 1

      Default: 4

    • Choices: Integer >= 1

      Default: 32

    • Choices: Integer >= 1

      Default: 128

    • Choices: NoiseLearnerResult, Sequence[LayerError]

      Default: None

    • Choices: True, False

      Default: True

    • Options for measurement noise learning.

      resilience.measure_noise_learning API documentation

    • Choices: Integer >= 1

      Default: 32

    • Choices: Integer, auto

      Default: auto

    • Choices: True, False

      Default: False

    • Probabilistic error cancellation mitigation options.

      resilience.pec API documentation

    • Choices: None, Integer >= 1

      Default: 100

    • Choices: auto, float in the range [0, 1]

      Default: auto

    • Choices: True, False

      Default: False

    • resilience.zne API documentation

    • 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)

    • Choices: List of floats; each float >= 1

      Default: (1, 1.5, 2) for PEA, and (1, 3, 5) otherwise

  • 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

    resilience_level API documentation

  • Choices: Integer

    Default: None

    seed_estimator

  • Options to pass when simulating a backend

    simulator API documentation

    • Choices: List of basis gate names to unroll to

      Default: The set of all basis gates supported by Qiskit Aer simulator

    • Choices: List of directed two-qubit interactions

      Default: None, which implies no connectivity constraints (full connectivity).

    • Choices: Qiskit Aer NoiseModel, or its representation

      Default: None

    • Choices: Integer

      Default: None

  • Twirling options

    twirling API documentation

    • Choices: True, False

      Default: False

    • Choices: True, False

      Default: True

    • Choices: auto, Integer >= 1

      Default: auto

    • Choices: auto, Integer >= 1

      Default: auto

    • Choices: active, active-circuit, active-accum, all

      Default: active-accum

  • Experimental options, when available.

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

Other notes:

  • Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks. Measurement twirling can only be applied to terminal measurements.
  • Compatible with fractional gates when using qiskit-ibm-runtime v0.42.0 or later.

Next steps

Recommendations
Was this page helpful?
Report a bug, typo, or request content on GitHub.