Specify Estimator options

Package versions

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

qiskit[all]~=2.5.2
qiskit-ibm-runtime~=0.47.0

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 :

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 only), 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 Estimator 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:

# Added by doQumentation — installs the packages this notebook needs if they are missing
import importlib.util

_needed = {"qiskit": "qiskit", "qiskit_ibm_runtime": "qiskit-ibm-runtime"}
_missing = [pip for module, pip in _needed.items()
            if importlib.util.find_spec(module) is None]
# One at a time, so a package that fails to install does not block the others
for _pip in _missing:
    %pip install -q {_pip}
if not _missing:
    print("\u2713 All required packages are installed")

from qiskit_ibm_runtime import QiskitRuntimeService

# Legacy server-side primitive before qiskit-ibm-runtime 0.50.0
# from qiskit_ibm_runtime import Estimator
# from qiskit_ibm_runtime.options import EstimatorOptions

# Client-side primitive introduced in qiskit-ibm-runtime 0.50.0
from qiskit_ibm_runtime.executor_estimator import Estimator
from qiskit_ibm_runtime.options_models 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)

Dictionary

You can specify options as a dictionary when initializing Estimator.

from qiskit_ibm_runtime import QiskitRuntimeService

# Legacy server-side primitive before qiskit-ibm-runtime 0.50.0
# from qiskit_ibm_runtime import Estimator

# Client-side primitive introduced in qiskit-ibm-runtime 0.50.0
from qiskit_ibm_runtime.executor_estimator import 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 Estimator options class (EstimatorOptions) does not need to be instantiated if you are setting options after initializing the primitive.

from qiskit_ibm_runtime import QiskitRuntimeService

# Legacy server-side primitive before qiskit-ibm-runtime 0.50.0
# from qiskit_ibm_runtime import Estimator

# Client-side primitive introduced in qiskit-ibm-runtime 0.50.0
from qiskit_ibm_runtime.executor_estimator import 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

# Legacy server-side primitive before qiskit-ibm-runtime 0.50.0
# from qiskit_ibm_runtime import Estimator

# Client-side primitive introduced in qiskit-ibm-runtime 0.50.0
from qiskit_ibm_runtime.executor_estimator import Estimator
from qiskit.circuit.library import random_iqp
from qiskit.transpiler import generate_preset_pass_manager
from qiskit.quantum_info import SparsePauliOp

service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

circuit1 = random_iqp(3)
circuit1.measure_all()
circuit2 = random_iqp(3)
circuit2.measure_all()

observable = SparsePauliOp("Z" * 3)

pass_manager = generate_preset_pass_manager(
    optimization_level=3, backend=backend
)

transpiled1 = pass_manager.run(circuit1)
transpiled2 = pass_manager.run(circuit2)
isa_observable1 = observable.apply_layout(transpiled1.layout)
isa_observable2 = observable.apply_layout(transpiled2.layout)

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, isa_observable1), (transpiled2, isa_observable2)],
    precision=0.02,
)

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

Special case: precision

The Estimator.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 Estimator execution interface, and are independent of the Runtime Estimator'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

These precision parameters are only for specifying target precision, and the results are not guaranteed to reach the specified 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 Estimator PUB:

If the PUB specifies precision, use that value.
If the precision keyword argument is specified in run, use that value.
If twirling is enabled (True by default), then the product of num_randomizations and shots_per_randomization, as specified as twirling options, is used.
If estimator.options.default_shots is specified, use that value to control the amount of data.
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

Although precision specified in the PUB and in run have higher precedence, the job fails if twirling is enabled and the product of num_randomizations and shots_per_randomization is smaller than the shots needed to achieve the precision. In this scenario, Estimator is unable to allocate the shots among the specified num_randomizations.

note

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

from qiskit_ibm_runtime import QiskitRuntimeService

# Legacy server-side primitive before qiskit-ibm-runtime 0.50.0
# from qiskit_ibm_runtime import Estimator

# Client-side primitive introduced in qiskit-ibm-runtime 0.50.0
from qiskit_ibm_runtime.executor_estimator import Estimator
from qiskit.circuit.library import random_iqp
from qiskit.transpiler import generate_preset_pass_manager
from qiskit.quantum_info import SparsePauliOp

service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

observable = SparsePauliOp("Z" * 3)

circuit = random_iqp(3)
circuit.measure_all()

pass_manager = generate_preset_pass_manager(
    optimization_level=3, backend=backend
)

isa_circuit = pass_manager.run(circuit)
isa_observable = observable.apply_layout(isa_circuit.layout)

# Setting precision during primitive initialization
estimator = Estimator(mode=backend, options={"default_precision": 0.05})

# Run with precision=0.02, overwriting the default.
estimator.run(
    [(isa_circuit, isa_observable1)],
    precision=0.02,
)

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

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 QiskitRuntimeService

# Legacy server-side primitive before qiskit-ibm-runtime 0.50.0
# from qiskit_ibm_runtime import Estimator

# Client-side primitive introduced in qiskit-ibm-runtime 0.50.0
from qiskit_ibm_runtime.executor_estimator import Estimator

# 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 information 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.

default_shots

The total number of shots to use per circuit per configuration.

Choices: Integer >= 0

Default: None

default_shots API documentation

default_precision

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

dynamical_decoupling

Control dynamical decoupling error mitigation settings.

dynamical_decoupling API documentation

dynamical_decoupling.enable

Choices: True, False

Default: False

dynamical_decoupling.extra_slack_distribution

Choices: middle, edges

Default: middle

dynamical_decoupling.scheduling_method

Choices: asap, alap Default: alap

dynamical_decoupling.sequence_type

Choices: XX, XpXm, XY4 Default: XX

dynamical_decoupling.skip_reset_qubits

Choices: True, False Default: False

environment

environment API documentation

environment.job_tags

List of tags.

Choices: None

Default: None

environment.log_level

Choices: DEBUG, INFO, WARNING, ERROR, CRITICAL

Default: WARNING

environment.private

Choices: True, False

Default: False

execution

execution API documentation

execution.init_qubits

Whether to reset the qubits to the ground state for each shot.

Choices: True, False

Default: True

execution.rep_delay

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

max_execution_time

Limits how long a job can run, in seconds. See the maximum execution time guide for details.

Choices: Integer number of seconds in the range [1, 10800]

Default: 10800 (3 hours)

resilience

Advanced resilience options to fine tune the resilience strategy.

resilience API documentation

resilience.layer_noise_model

Choices: Sequence[LayerNoiseModel]

Default: None

resilience.measure_mitigation

Choices: True, False

Default: True

resilience.measure_noise_learning

Options for measurement noise learning.

resilience.measure_noise_learning API documentation

resilience.measure_noise_learning.num_randomizations

Choices: Integer >= 1

Default: 32

resilience.pec_mitigation

Choices: True, False

Default: False

resilience.pec

Probabilistic error cancellation mitigation options.

resilience.pec API documentation

resilience.pec.max_overhead

Choices: None, Integer >= 1

Default: 100

resilience.pec.noise_gain

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

Default: auto

resilience.zne_mitigation

Choices: True, False

Default: False

resilience.zne

resilience.zne API documentation

resilience.zne.amplifier

Choices: gate_folding, gate_folding_front, gate_folding_back, pea

Default: gate_folding

resilience.zne.extrapolated_noise_factors

Choices: List of floats

Default: [0, *noise_factors]

resilience.zne.extrapolator

Choices: One or more of: exponential, linear, double_exponential, polynomial_degree_(1 <= k <= 7), fallback

Default: (exponential, linear)

resilience.zne.noise_factors

Choices: List of floats; each float >= 1

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

resilience_level

How much resilience to build against errors. Higher levels generate more accurate results at the expense of longer processing times. See the resilience levels section in the Noise management topic to learn more.

Choices: 0, 1, 2

Default: 1

resilience_level API documentation

simulator

Options to pass when simulating a backend

simulator API documentation

simulator.basis_gates

Choices: List of basis gate names to unroll to

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

simulator.coupling_map

Choices: List of directed two-qubit interactions

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

simulator.noise_model

Choices: Qiskit Aer NoiseModel, or its representation

Default: None

simulator.seed_simulator

Choices: Integer

Default: None

twirling

Twirling options

twirling API documentation

twirling.enable_gates

Choices: True, False

Default: False

twirling.enable_measure

Choices: True, False

Default: True

twirling.num_randomizations

Choices: auto, Integer >= 1

Default: auto

twirling.shots_per_randomization

Choices: auto, Integer >= 1

Default: auto

twirling.strategy

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

Default: active-accum

experimental

Experimental options, when available.

Feature compatibility

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:

Fractional gates

Incompatible with:

Gate twirling
PEA
PEC

Gate-folding ZNE

Might not work when using custom gates. Incompatible with:

Gate twirling

Incompatible with:

Fractional gates
Stretches

Other notes:

Measurement twirling can only be applied to terminal measurements.
Does not work with non-Clifford entanglers.

PEA

Incompatible with:

Fractional gates
Gate-folding ZNE
PEC

PEC

Incompatible with:

Fractional gates
Gate-folding ZNE
PEA

Next steps

Recommendations

Find more details about the Estimator methods in the Estimator API reference.
Decide what execution mode to run your job in.
Learn about noise management with Estimator.

Set Estimator options​

Primitive initialization​

Options class​

Dictionary​

Update options after initialization​

Run() method​

Special case: precision​

Turn off all error mitigation and error suppression​

Available options​

Feature compatibility​

Next steps​

Set Estimator options

Primitive initialization

Options class

Dictionary

Update options after initialization

Run() method

Special case: precision

Turn off all error mitigation and error suppression

Available options

Feature compatibility

Next steps