Skip to main contentIBM Quantum Documentation

Advanced Qiskit Runtime options

When calling the primitives, you can pass in options by using an options class or a dictionary. In the options classes, commonly used options, such as resilience_level, are at the first level. Other options are grouped into different categories, such as execution. See the options classes section for details.

Important

To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as instruction set architecture (ISA) circuits and observables) before being submitted to the Qiskit Runtime primitives. See the transpilation documentation for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set optimization_level=0.

Exception: When you initialize the Qiskit Runtime Service with the Q-CTRL channel strategy (example below), abstract circuits are still supported.

service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl")
Attention

This section focuses on Qiskit Runtime primitive options. While most of the primitives interface is common across implementations, most options are not. Consult the corresponding API references for information about the qiskit.primitives and qiskit_aer.primitives options.


V2 changes

Options are specified differently in the V2 primitives in these ways:

  • SamplerV2 and EstimatorV2 now have separate options classes. You can see the available options and update option values during or after primitive initialization.
  • Instead of the set_options() method, V2 primitive options have the update() method that applies 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.
  • For V2 primitives, the options attribute is the dataclass Python type. You can use the built-in asdict method to convert it to a dictionary.

Instantiate the Options class (V1)

In the example below, we create an instance of the Options class. optimization_level is a first-level option and can be passed as an input parameter. Options related to the execution environment are passed using the environment parameter.

from qiskit_ibm_runtime import Options
 
options = Options(optimization_level=1, environment={"log_level": "INFO"})

The Options class supports auto-complete. Once you create an instance of the Options class, you can use auto-complete to see what options are available. If you choose one of the categories, you can use auto-complete again to see what options are available under that category.

from qiskit_ibm_runtime import Options
 
options = Options()
options.resilience_level = 1
options.execution.shots = 2048

Pass options to a primitive

Options class

When creating an instance of the Estimator or Sampler class, you can pass in the options you created in the options class. Those options will then be applied when you use run() to perform the calculation. Example:

SamplerV2 and EstimatorV2 have separate options classes that do not need to be instantiated. You can see the available options and update option values during or after primitive initialization. Those options will then be applied when you use run() to perform the calculation. Example:

estimator = Estimator(mode=backend)
 
# Setting options after primitive initialization
# This uses auto complete.
estimator.options.default_shots = 4000

Primitive initialization

You can specify options when 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)
 
# Setting options during primitive initialization
estimator = Estimator(backend, options={"resilience_level": 2})

Run() method

You can pass in options by using the run() method. This overwrites the options you specified when creating the Estimator or Sampler instance for that particular execution.

In V2, the only options you can pass to run() are options defined in the interface. That is, shots for Sampler and precision for Estimator.

# Sample two circuits at 128 shots each.
sampler.run([circuit1, circuit2], shots=128)

Commonly used options

There are many available options, but the following are the most commonly used:

Shots

For some algorithms, setting a specific number of shots is a core part of their routines. There are several ways to set and update shots with the primitives.

from qiskit_ibm_runtime import SamplerV2 as Sampler
 
# Setting shots during primitive initialization
sampler = Sampler(backend, options={"default_shots": 4096})
 
# Setting options after primitive initialization
# This uses auto complete.
sampler.options.default_shots=2000
 
# This does bulk update.  The value for default_shots is overridden if you specify shots with run() or in the PUB.
sampler.options.update(default_shots=1024, dynamical_decoupling={"sequence_type": "XpXm"})
 
# Sample two circuits at 128 shots each.
sampler.run([circuit1, circuit2], shots=128)

Runtime compilation

The Qiskit Runtime primitives expect to be called with circuits already suitable for execution on the target system. This implies that the user has already transpiled their circuits to respect the native gate set and connectivity constraints of the target system.

In the V2 primitives, you can explicitly enable and disable individual error mitigation/suppression methods, such as dynamical decoupling. For an example, see the Runtime compilation topic.

Note

In the V1 Qiskit Runtime primitives, optimization levels 2 and 3 behave identically to level 1. If you want to use more advanced optimization, use the Qiskit transpiler locally, set skip_transpilation=True, and then pass the transpiled circuits to the primitives. For instructions see the Submit pre-transpiled circuits(opens in a new tab) tutorial.

The optimization level option is a "first-level option", and can be set as follows (V1 primitives only):

from qiskit_ibm_runtime import Estimator, Options
 
options = Options(optimization_level=1)
 
# or..
options = Options()
options.optimization_level = 1
 
estimator = Estimator(backend=backend, options=options)

Turning off all optional runtime compilation steps requires a "second-level option", as follows:

from qiskit_ibm_runtime import Estimator, Options
 
options = Options()
options.transpilation.skip_transpilation = True
 
estimator = Estimator(backend=backend, options=options)

For more information and a complete list of advanced transpilation options, see the Advanced transpilation options table in the Runtime compilation topic.

Error mitigation

You might want to leverage different error mitigation methods and see how these affect the performance of your algorithm. These methods can be set through the resilience_level option. For more information about error mitigation, see the Configure error mitigation topic.

With Estimator V2, you can set resilience levels 0-2 and you can also turn on and off various error mitigation settings for fine-tuning.

estimator = Estimator(mode=backend)
 
estimator.options.resilience_level = 2
estimator.options.resilience.zne_mitigation = True
estimator.options.resilience.zne.noise_factors = [1, 3, 5]

Options classes

CategoryDescriptionExample
ResilienceAdvanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC. Estimator only.estimator.options.resilience.measure_mitigation = True
Dynamical decouplingOptions for dynamical decoupling.estimator.options.dynamical_decoupling.enable = True
ExecutionPrimitive execution options, including whether to initialize qubits and the repetition delay.estimator.options.execution.init_qubits = False
TwirlingTwirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample.estimator.options.twirling.enable_gates = True
EnvironmentExecution environment options such as the logging level to set and job tags to add.estimator.options.environment.log_level = 'ERROR'
SimulatorSimulator options, such as the basis gates, simulator seed, and coupling map. Applies to local testing mode only.estimator.options.simulator.seed_simulator = 42

Next steps

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