Sampler 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 Sampler primitive. This section focuses on how to specify 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.BackendSamplerV2 and qiskit_aer.primitives.SamplerV2 options.

Notes about specifying options in the primitives:

You can see the available options and update option values during or after primitive 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 Sampler options

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

Primitive initialization

You can pass in an instance of the options class or a dictionary when initializing Sampler, 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 SamplerV2 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

See SamplerOptions for full details about the options class.

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import SamplerV2 as Sampler
from qiskit_ibm_runtime.options import SamplerOptions
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
options = SamplerOptions(
    resilience_level=2,
    resilience={"zne_mitigation": True, "zne": {"noise_factors": [1, 3, 5]}},
)
 
# or...
options = SamplerOptions()
options.resilience_level = 2
options.resilience.zne_mitigation = True
options.resilience.zne.noise_factors = [1, 3, 5]
 
sampler = Sampler(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.
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 Sampler.

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import SamplerV2 as Sampler
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
# Setting options during primitive initialization
sampler = Sampler(
    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: sampler.options.option.sub-option.sub-sub-option = choice to take advantage of auto-complete, or use the update() method to make bulk updates.

The SamplerV2 options class (SamplerOptions) 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 SamplerV2 as Sampler
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
sampler = Sampler(mode=backend)
 
# Setting options after primitive initialization
# This uses auto-complete.
sampler.options.default_shots = 4000
# This does bulk update.
sampler.options.update(
    default_shots=4000, resilience={"zne_mitigation": True}
)

Run() method

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

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import SamplerV2 as Sampler
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)
 
sampler = Sampler(mode=backend)
# Default shots to use if not specified in run()
sampler.options.default_shots = 500
# Sample two circuits at 128 shots each.
sampler.run([transpiled1, transpiled2], shots=128)
 
# Sample two circuits with different numbers of shots.
# 100 shots is used for transpiled1 and 200 for transpiled.
sampler.run([(transpiled1, None, 100), (transpiled2, None, 200)])

Output:

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

Special cases

Shots

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

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

To summarize, this is the order of precedence for specifying shots in the Sampler, for any particular PUB:

If the PUB specifies shots, use that value.
If the shots keyword argument is specified in run, use that value.
If num_randomizations and shots_per_randomization are specified as twirling options, shots are the product of those values.
If sampler.options.default_shots is specified, use that value.

Thus, if shots are specified in all possible places, the one with highest precedence (shots specified in the PUB) is used.

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. Shots (or precision) can be specified in multiple places. They are prioritized as follows:

For any Sampler PUB:

Integer-valued shots contained in the PUB
The run(...,shots=val) value
The options.default_shots value

Example:

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import SamplerV2 as Sampler
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 shots during primitive initialization
sampler = Sampler(mode=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([transpiled1, transpiled2], shots=128)

Output:

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

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 SamplerV2 as Sampler
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
sampler = Sampler(mode=backend)
 
sampler.options.max_execution_time = 2500

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
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
- 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: classified, kerneled, avg_kerneled
  Default: classified
Choices: Integer number of seconds in the range [1, 10800]
Default: 10800 (3 hours)
max_execution_time API documentation
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: False
- 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:

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.

Incompatible with:

Gate twirling

Compatible with dynamic circuits when using qiskit-ibm-runtime v0.42.0 or later.

Next steps

Recommendations

Find more details about the SamplerV2 methods in the Sampler API reference.
Find details about how to configure error suppression and error mitigation.
Decide what execution mode to run your job in.