Specify Sampler options
Die Seide is noch nich ibersetzt worn. Se guggen de englsche Originalversion.
Package versions
The code on this page was developed using the following requirements. We recommend using these versions or newer.
qiskit[all]~=2.4.0
qiskit-ibm-runtime~=0.46.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 Sampler, after initializing Sampler, or you can update the options after Sampler has been initialized. For instructions to use these techniques, see the Introduction to options topic.
Additionally, you can set the shots value in the run() method, as is described in the following section.
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.
# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-runtime
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)
<RuntimeJobV2('d8286680bvlc73d1vmu0', '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
shotskeyword argument is specified inrun, use that value. - If
twirlingis enabled (True by default), then the product ofnum_randomizationsandshots_per_randomization, as specified astwirlingoptions, is used. - If
sampler.options.default_shotsis 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.
Although shots 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 value. In this scenario, SamplerV2 is unable to allocate the shots among the specified num_randomizations.
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)
<RuntimeJobV2('d82868ugbeec73alfa80', '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
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.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.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)
simulator
Options to pass when simulating a backend
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.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:
Dynamic circuits
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-runtimev0.42.0 or later.
Dynamical decoupling
Incompatible with:
- Dynamic circuits
Fractional gates
Incompatible with:
- Gate twirling
Compatible with dynamic circuits when using qiskit-ibm-runtime v0.42.0 or later.
Gate twirling
Incompatible with:
- Fractional gates
- Stretches
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.
- Measurement twirling is incompatible with the
storeinstruction. - Does not work with non-Clifford entanglers.
Next steps
- Review the Introduction to options guide.
- Find more details about the
SamplerV2methods in the Sampler API reference. - Decide what execution mode to run your job in.
- Learn about noise management with Sampler.