Migrating to v0.27.0: SamplerV2 / EstimatorV2 are deprecated in favor of ExecutorSampler / ExecutorEstimator#

qrmi.primitives.ibm.SamplerV2 and qrmi.primitives.ibm.EstimatorV2 are deprecated as of v0.27.0 and will be removed no sooner than 3 months after the release date. Use qrmi.primitives.ibm.ExecutorSampler and qrmi.primitives.ibm.ExecutorEstimator instead.

Why#

SamplerV2 / EstimatorV2 submit jobs to the server-side sampler / estimator programs of IBM Quantum, which are deprecated. Starting with qiskit-ibm-runtime 0.50, the Sampler and Estimator primitives run all pre- and post-processing on the client side (twirling, dynamical decoupling, TREX, ZNE, PEC/PEA noise injection, expectation values, …) and submit only the resulting circuits to the generic executor program.

ExecutorSampler / ExecutorEstimator reuse that client-side processing from qiskit-ibm-runtime and submit the jobs through QRMI. The results are the same PrimitiveResult objects as before.

Requirements#

  • qiskit-ibm-runtime>=0.50. Install or upgrade with pip install -U "qrmi[ibm]".

  • Resource type ibm-quantum-system or ibm-quantum-compute-service. The deprecated qiskit-runtime-service resource type does not support the executor program.

  • qrmi[iqm] cannot be installed in the same environment: it requires qiskit<2.2, while qiskit-ibm-runtime>=0.50 requires qiskit>=2.3. Use separate virtual environments for IBM and IQM.

How to migrate#

Sampler#

# Before
from qrmi.primitives.ibm import SamplerV2, get_backend

target = get_backend(qrmi).target
sampler = SamplerV2(qrmi, options={"default_shots": 10000})

# After
from qrmi.primitives.ibm import ExecutorSampler, get_backend

backend = get_backend(qrmi)
target = backend.target
sampler = ExecutorSampler(backend, options={"default_shots": 10000})

Estimator#

# Before
from qrmi.primitives.ibm import EstimatorV2, get_backend

target = get_backend(qrmi).target
estimator = EstimatorV2(qrmi, options={})

# After
from qrmi.primitives.ibm import ExecutorEstimator, get_backend

backend = get_backend(qrmi)
target = backend.target
estimator = ExecutorEstimator(backend, options={})

Transpilation, run(), job.result(), and the structure of the results do not change. See the updated sampler.py and estimator.py examples.

The first argument#

The first argument can be either a QRMIBackend returned by get_backend(qrmi) or the QRMI resource itself. Passing the backend is recommended: you usually create it for transpilation anyway, and it provides the timing information needed for dynamical decoupling. If you pass the resource and enable dynamical decoupling, the backend is created automatically on the first run().

ExecutorSampler(get_backend(qrmi))   # recommended
ExecutorSampler(qrmi)                # also works

Options#

Options are now validated on the client side with qiskit-ibm-runtime’s SamplerOptions / EstimatorOptions. You can pass either a dict or an options object.

The run_options field is removed. Options that you put in run_options are now top-level fields:

# Before
sampler = SamplerV2(
    qrmi,
    options={
        "default_shots": 4096,
        "run_options": {"twirling": {"enable_measure": True}},
    },
)

# After
sampler = ExecutorSampler(
    backend,
    options={
        "default_shots": 4096,
        "twirling": {"enable_measure": True},
    },
)

Unknown option names now raise a validation error instead of being sent to the server.

Behavior changes#

Changes in QRMI#

These changes come from replacing QRMI’s SamplerV2 / EstimatorV2 with ExecutorSampler / ExecutorEstimator.

SamplerV2 / EstimatorV2

ExecutorSampler / ExecutorEstimator

Import

qrmi.primitives.ibm.SamplerV2 / EstimatorV2

qrmi.primitives.ibm.ExecutorSampler / ExecutorEstimator

First argument

QRMI resource

QRMIBackend from get_backend(qrmi) (recommended) or QRMI resource

Options

QRMI’s own default_shots / default_precision + run_options passed to the server as is

qiskit-ibm-runtime’s SamplerOptions / EstimatorOptions, validated on the client side; no run_options

Sampler default shots

1024

4096 (default of qiskit-ibm-runtime’s SamplerOptions)

Program the job is submitted to

sampler / estimator

executor

Supported resource types

ibm-quantum-system, ibm-quantum-compute-service, qiskit-runtime-service

ibm-quantum-system, ibm-quantum-compute-service

max_execution_time, environment options

-

Accepted by the options model but not sent. The timeout is set with {resource_name}_QRMI_IBM_QCS_TIMEOUT_SECONDS / {resource_name}_QRMI_IBM_QS_TIMEOUT_SECONDS as before

Job object

job_id(), status(), result(), cancel(), done(), errored(), logs(), …

Same

Changes inherited from qiskit-ibm-runtime#

ExecutorSampler / ExecutorEstimator reuse the client-side Sampler and Estimator of qiskit-ibm-runtime (0.50 and later). The following behavior is therefore the same as when you use qiskit_ibm_runtime.SamplerV2 / EstimatorV2 directly, and is not specific to QRMI. See the qiskit-ibm-runtime 0.50.0 release notes for details.

  • Pre- and post-processing (twirling, dynamical decoupling, TREX, ZNE, PEC/PEA noise injection, expectation values) run on your machine and use its CPU and memory.

  • Sampler: all PUBs in one run() must have the same number of shots. If you need different shots, call run() once per shot count.

  • Estimator: PEC and PEA require resilience.layer_noise_model to be set before run(). Noise learning is not run automatically.

  • Result metadata is produced by the client-side post-processing and may differ from the server-side primitives.

Finding remaining call sites#

Creating a SamplerV2 or EstimatorV2 now emits a FutureWarning. To find all remaining call sites, run your code with python -W error::FutureWarning.