Skip to main contentIBM Quantum Documentation Preview
This is a preview build of IBM Quantum® documentation. Refer to quantum.cloud.ibm.com/docs for the official documentation.

Specify options

Package versions

The code on this page was developed using the following requirements. We recommend using these versions or newer.

qiskit[all]~=2.3.0
qiskit-ibm-runtime~=0.43.1

You can use options to customize the Estimator primitive. While the interface of the primitives' run() method is common across all implementations, their options are not. Consult the API references for information about the qiskit.primitives.BaseEstimatorV2 and qiskit_aer.BaseEstimatorV2 options.

Notes about specifying options in the Estimator primitives:

  • You can see the available options and update option values during or after Estimator initialization.
  • Use the update() method to apply changes to the options attribute.
  • If you do not specify a value for an option, it is given a special value of Unset and the server defaults are used.
  • The options attribute is the dataclass Python type. You can use the built-in asdict method to convert it to a dictionary.

Set Estimator options

You can set options when initializing Estimator, after initializing Estimator, or (for precision) in the run() method.

Primitive initialization

You can pass in an instance of the options class or a dictionary when initializing Estimator, which then makes a copy of those options. Thus, changing the original dictionary or options instance doesn't affect the options owned by the primitive.

Options class

When creating an instance of the EstimatorV2 class, you can pass in an instance of the options class. Those options will then be applied when you use run() to perform the calculation. Specify the options in this format: options.option.sub-option.sub-sub-option = choice. For example: options.dynamical_decoupling.enable = True

Example:

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import EstimatorV2 as Estimator
from qiskit_ibm_runtime.options import EstimatorOptions
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
options = EstimatorOptions(
    resilience_level=2,
    resilience={"zne_mitigation": True, "zne": {"noise_factors": [1, 3, 5]}},
)
 
# or...
options = EstimatorOptions()
options.resilience_level = 2
options.resilience.zne_mitigation = True
options.resilience.zne.noise_factors = [1, 3, 5]
 
estimator = Estimator(mode=backend, options=options)

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.

Dictionary

You can specify options as a dictionary when initializing Estimator.

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import EstimatorV2 as Estimator
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
# Setting options during initialization
estimator = Estimator(
    backend,
    options={
        "resilience_level": 2,
        "resilience": {
            "zne_mitigation": True,
            "zne": {"noise_factors": [1, 3, 5]},
        },
    },
)

Update options after initialization

You can specify the options in this format: estimator.options.option.sub-option.sub-sub-option = choice to take advantage of auto-complete, or use the update() method to make bulk updates.

The EstimatorV2 options class (EstimatorOptions) does not need to be instantiated if you are setting options after initializing the primitive.

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import EstimatorV2 as Estimator
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
estimator = Estimator(mode=backend)
 
# Setting options after initialization
# This uses auto-complete.
estimator.options.default_precision = 0.01
# This does bulk update.
estimator.options.update(
    default_precision=0.02, resilience={"zne_mitigation": True}
)

Run() method

The only values you can pass to run() are those defined in the interface. That is, precision for Estimator. This overwrites any value set for default_precision for the current run.

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import EstimatorV2 as Estimator
from qiskit.circuit.library import random_iqp
from qiskit.transpiler import generate_preset_pass_manager
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
circuit1 = random_iqp(3)
circuit1.measure_all()
circuit2 = random_iqp(3)
circuit2.measure_all()
 
pass_manager = generate_preset_pass_manager(
    optimization_level=3, backend=backend
)
 
transpiled1 = pass_manager.run(circuit1)
transpiled2 = pass_manager.run(circuit2)
 
estimator = Estimator(mode=backend)
# Default precision to use if not specified in run()
estimator.options.default_precision = 0.01
# Run two circuits, requiring a precision of .02 for both.
estimator.run([transpiled1, transpiled2], precision=0.02)
 
# Run two circuits with different precision requirements.
estimator.run([(transpiled1, None, 0.01), (transpiled2, None, 0.02)])

Output:

<RuntimeJobV2('d5k96cn853es738djikg', 'estimator')>

Special cases

Resilience level

The resilience level is not actually an option that directly impacts the primitive query, but specifies a base set of curated options as a starting point. In general, level 0 turns off all error mitigation, level 1 turns on options for measurement error mitigation, and level 2 turns on options for gate and measurement error mitigation.

Any options you manually specify in addition to the resilience level are applied on top of the base set of options defined by the resilience level. Therefore, in principle, you could set the resilience level to 1, but then turn off measurement mitigation, although this is not advised.

In the following example, setting the resilience level to 0 initially turns off zne_mitigation, but estimator.options.resilience.zne_mitigation = True overrides the relevant setup from estimator.options.resilience_level = 0.

from qiskit_ibm_runtime import EstimatorV2, QiskitRuntimeService
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
estimator = EstimatorV2(backend)
 
estimator.options.default_shots = 100
estimator.options.resilience_level = 0
estimator.options.resilience.zne_mitigation = True

Precision

The EstimatorV2.run method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for precision, and a precision keyword argument. These precision values are a part of the Executor execution interface, and are independent of the Runtime Executor's options. They take precedence over any values specified as options in order to comply with the Estimator abstraction.

However, if precision is not specified by any PUB or in the run keyword argument (or if they are all None), then the precision value from the options is used, most notably default_precision.

Note that Estimator options contain both default_shots and default_precision. However, because gate-twirling is enabled by default, the product of num_randomizations and shots_per_randomization takes precedence over those two options.

Specifically, for any particular Estimator PUB:

  1. If the PUB specifies precision, use that value.
  2. If the precision keyword argument is specified in run, use that value.
  3. If num_randomizations and shots_per_randomization are specified as twirling options (enabled by default), use their product to control the amount of data.
  4. If estimator.options.default_shots is specified, use that value to control the amount of data.
  5. If estimator.options.default_precision is specified, use that value.

For example, if precision is specified in all four places, the one with highest precedence (precision specified in the PUB) is used.

Note

Precision scales inversely with usage. That is, the lower the precision, the more QPU time it takes to run.

Commonly used options

Among the many available options, the following are the most commonly used:

Shots

For some algorithms, setting a specific number of shots is a core part of their routines. Shots (or precision) can be specified in multiple places. They are prioritized as follows:

For any Estimator PUB:

  1. Float-valued precision contained in the PUB
  2. The run(...,precision=val) value
  3. The options.default_shots value
  4. The options.default_precision value

Example:

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import EstimatorV2 as Estimator
from qiskit.circuit.library import random_iqp
from qiskit.transpiler import generate_preset_pass_manager
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
circuit1 = random_iqp(3)
circuit1.measure_all()
circuit2 = random_iqp(3)
circuit2.measure_all()
 
pass_manager = generate_preset_pass_manager(
    optimization_level=3, backend=backend
)
 
transpiled1 = pass_manager.run(circuit1)
transpiled2 = pass_manager.run(circuit2)
 
 
# Setting precision during primitive initialization
estimator = Estimator(mode=backend, options={"default_precision": 0.01})
 
# Setting options after primitive initialization
# This uses auto-complete.
estimator.options.default_precision = 0.01
 
# This does bulk update.  The value for default_precision is overridden if you specify precision with run() or in the PUB.
estimator.options.update(
    default_precision=0.01, dynamical_decoupling={"sequence_type": "XpXm"}
)
 
# Run two circuits to a precision of .02 each.
estimator.run([transpiled1, transpiled2], precision=0.02)

Output:

<RuntimeJobV2('d5k96icjt3vs73ds5t0g', 'estimator')>

Maximum execution time

The maximum execution time (max_execution_time) limits how long a job can run. If a job exceeds this time limit, it is forcibly canceled. This value applies to single jobs, whether they are run in job, session, or batch mode.

The value is set in seconds, based on quantum time (not wall clock time), which is the amount of time that the QPU is dedicated to processing your job. It is ignored when using local testing mode because that mode does not use quantum time.

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import EstimatorV2 as Estimator
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
estimator = Estimator(mode=backend)
 
estimator.options.max_execution_time = 2500

Turn off all error mitigation and error suppression

You can turn off all error mitigation and suppression if you are, for example, doing research on your own mitigation techniques. To accomplish this, set resilience_level = 0.

Example:

from qiskit_ibm_runtime import EstimatorV2 as Estimator, QiskitRuntimeService
 
# Define the service.  This allows you to access an IBM QPU.
service = QiskitRuntimeService()
 
# Get a backend
backend = service.least_busy(operational=True, simulator=False)
 
# Define Estimator
estimator = Estimator(backend)
 
options = estimator.options
 
# Turn off all error mitigation and suppression
options.resilience_level = 0

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