Overview

This guide describes key patterns of behavior and use cases with code examples to help you migrate code from the legacy backend.run() interface to use the Qiskit Runtime primitives interface (qiskit-ibm-runtime package).

The qiskit-ibm-runtime package provides cloud access to the IBM QPUs (quantum processing units) through the primitives interface. The backend.run() interface coexisted with the original (V1) primitives model as the dedicated “direct hardware access” entry point. With the introduction of the V2 primitives interface, the new SamplerV2 class now fulfills that role. Consequentially, backend.run() is being deprecated, along with qiskit-ibm-provider, which only exposed the backend.run() interface.

The Qiskit Runtime primitives implement the reference Sampler V2 and Estimator V2 interfaces found in qiskit.primitives, and enable capabilities not available with the legacy backend.run() interface. These capabilities include application of advanced processing techniques for error suppression and mitigation in Estimator, the ability to efficiently sweep between arrays of parameter value sets or observables in both Sampler and Estimator, and access to the new local testing mode. Additionally, Qiskit Runtime lets users run iterative algorithm circuits back to back (session mode) or in collections of circuits without having to re-queue each job (batch mode). This results in more efficient quantum processor use and reduces the time spent running complex computations.

---

Why migrate to Qiskit Runtime primitives?

Similar to the early days of classical computers, when developers had to manipulate CPU registers directly, the early interface to QPUs simply returned the raw data coming out of the control electronics. This was not a huge issue when QPUs lived in labs and only allowed direct access by researchers. When IBM first brought its QPUs to the cloud, we recognized most developers would not and should not be familiar with distilling such raw data into 0s and 1s. Therefore, we introduced backend.run, our first abstraction for accessing QPUs. This allowed developers to operate on a data format they were more familiar with and focus on the bigger picture.

As access to QPUs became more widespread, and with more quantum algorithms being developed, we again recognized the need for a higher-level abstraction. This led to the introduction of the Qiskit primitives interface, which are optimized for two core tasks in quantum algorithm development: expectation value estimation (Estimator) and circuit sampling (Sampler). The goal is once again to help developers to focus more on innovation and less on data conversion.

For backward compatibility, the backend.run interface continues to exist in Qiskit. However, it is deprecated in Qiskit Runtime, as most of the IBM Quantum users have migrated to V2 primitives due to their improved usability and efficiency.

---

Basic steps to migrate to primitives

Step 1: Determine which primitive to use

When migrating, the key to writing an equivalent algorithm using primitives is to first identify what minimal unit of information your algorithm is based on:

• If it uses an expectation value of a certain observable with respect to a quantum state (a real number), you will now use Estimator.

  An expectation value of an observable could be the target quantity in scenarios where knowing a quantum state is not relevant. This often occurs in optimization problems or chemistry applications. For example, when trying to discover the extremal energy of a system.

• If it uses a probability distribution from sampling the device, you will now use Sampler.

  A probability distribution is often of interest in optimization problems that return a classical bit string, encoding a certain solution to a problem at hand. In these cases, you might be interested in finding a bit string that corresponds to a ket value with the largest probability of being measured from a quantum state, for example.

Step 2: Change imports as necessary

Follow the steps in the appropriate topic to change your import options and other setup information:

• Migrate from qiskit-ibm-provider
• Migrate from qiskit-ibmq-provider

Step 3: Replace the call to backend.run with a call to qiskit_ibm_runtime.

See these topics for instructions:

• Update code that performs circuit sampling
• Update code that calculates expectation values
• Common use cases (basic, parameterized, and dynamic circuits)

Step 3a: replace any backend.run options with qiskit_ibm_runtime options.

See the following topics for instructions:

• Migrate options
• Common use cases Options section

---

Information to share with your users

There is already a collection of migration guides for users to help with the following tasks:

• Transition to the Qiskit Runtime provider
• Update user code to the V2 primitives interface

---

Next steps