Specify Sampler options

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.

Set Sampler options

You can set options when initializing the primitive, after initializing the primitive, or (for shots only), 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(
    dynamical_decoupling={"enable": True, "sequence_type": "XpXm"},
)

# or...
options = SamplerOptions()
options.dynamical_decoupling.enable = True
options.dynamical_decoupling.sequence_type = "XpXm"

sampler = Sampler(mode=backend, options=options)

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={
        "dynamical_decoupling": {
            "enable": True,
            "sequence_type": "XpXm",
        },
    },
)

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,
    dynamical_decoupling={"enable": True, "sequence_type": "XpXm"},
)

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)

Output:

<RuntimeJobV2('d7ans0b0g7hs73doium0', '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:

1. If the PUB specifies shots, use that value.
2. If the shots keyword argument is specified in run, use that value.
3. If twirling is enabled (True by default), then the product of num_randomizations and shots_per_randomization, as specified as twirling options, is used.
4. 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.

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

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.

• default_shots

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

  Choices: Integer >= 0

  Default: None

  default_shots 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

  • execution.meas_type

    Choices: classified, kerneled, avg_kerneled

    Default: classified

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

  max_execution_time 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: False

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

Next steps