Experiment with Qiskit Runtime¶
Learn how Qiskit Runtime works by trying out a prebuilt program.
Overview¶
Qiskit Runtime speeds up processing time by combining classical and quantum computing in a streamlined architecture.
In this first version you can explore running simple circuits or more complex variational algorithms (based on VQE). Additionally, you can test it using our quantum simulators on the cloud, so that you can quickly get up to speed with this new way to run Qiskit programs. With Qiskit Runtime, you can keep your quantum program on the cloud and run it any time.

Diagram of Qiskit Runtime’s architecture.¶
View available Qiskit Runtime programs¶
On the Services page, click the Programs tab to view available programs. Click any program to learn more about it, and optionally choose a backend and provider to generate a custom program template and open it directly in Quantum Lab. You can then modify it as necessary and use it to execute circuits.
Run a Qiskit Runtime program¶
In this example we will use a preloaded Qiskit Runtime program called sampler
. We will first build a circuit using Qiskit, then execute it with Qiskit Runtime, taking advantage of its low-latency architecture.
Note
You will need the latest
qiskit
andqiskit-ibm-runtime
packages to use Qiskit Runtime.Read about the maximum execution time for a Qiskit Runtime job here.
The sampler
program is one of the primitive programs (another is the estimator
).
These primitives provide methods that make it easier to build modular algorithms and other higher-order programs. They provide a seamless way to leverage the latest optimizations in IBM Quantum hardware and software.
The Sampler primitive lets you more accurately contextualize counts. It takes a user circuit as an input and generates a readout of quasi-probabilities. This enables you to more efficiently evaluate the possibility of multiple relevant data points in the context of destructive interference.
qiskit-ibm-runtime
now provides a simple Sampler
class which
allows access to the Sampler primitive service.
Instantiate the QiskitRuntimeService
from one of the saved accounts
like below.
from qiskit_ibm_runtime import QiskitRuntimeService, Sampler
# Save your credentials on disk.
# QiskitRuntimeService.save_account(channel='ibm_quantum', token=<IBM Quantum API key>)
service = QiskitRuntimeService()
A Qiskit Runtime session allows you to cache data, such as parameterized circuits, on the server side for the duration of a session. You can then pass in only parameters during subsequent calls.
Let’s prepare the quantum circuits as shown below.
from qiskit import QuantumCircuit
bell = QuantumCircuit(2)
bell.h(0)
bell.cx(0, 1)
bell.measure_all()
print(bell.draw())
┌───┐ ░ ┌─┐
q_0: ┤ H ├──■───░─┤M├───
└───┘┌─┴─┐ ░ └╥┘┌─┐
q_1: ─────┤ X ├─░──╫─┤M├
└───┘ ░ ║ └╥┘
meas: 2/══════════════╩══╩═
0 1
The quantum circuits can then be passed as lists to the Sampler class, which instantiates and opens a session with the Sampler primitive service.
sampler
can then be called multiple times to write different
circuit_indices
(a list of circuit indices) and parameter_values
(an optional list of concrete parameters to be bound) to the session and
read the calculated quasi-probabilities. The result is an instance of
SamplerResult
class in qiskit-terra
and it contains
quasi-probabilities and metadata.
with Sampler(circuits=[bell]*3, service=service, options={ "backend": "ibmq_qasm_simulator" }) as sampler:
result1 = sampler(circuit_indices=[0, 1, 2], shots=2000)
print(result1)
result2 = sampler(circuit_indices=[0, 1, 2], shots=3000)
print(result2)
result3 = sampler(circuit_indices=[0, 1, 2], shots=4000)
print(result3)
SamplerResult(quasi_dists=[{'00': 0.5155, '11': 0.4845}, {'11': 0.5175, '00': 0.4825}, {'00': 0.4915, '11': 0.5085}], metadata=[{'header_metadata': None, 'shots': 2000}, {'header_metadata': None, 'shots': 2000}, {'header_metadata': None, 'shots': 2000}])
SamplerResult(quasi_dists=[{'11': 0.5043333333333333, '00': 0.49566666666666664}, {'00': 0.501, '11': 0.499}, {'00': 0.493, '11': 0.507}], metadata=[{'header_metadata': None, 'shots': 3000}, {'header_metadata': None, 'shots': 3000}, {'header_metadata': None, 'shots': 3000}])
SamplerResult(quasi_dists=[{'00': 0.495, '11': 0.505}, {'11': 0.50075, '00': 0.49925}, {'11': 0.49825, '00': 0.50175}], metadata=[{'header_metadata': None, 'shots': 4000}, {'header_metadata': None, 'shots': 4000}, {'header_metadata': None, 'shots': 4000}])
View your Qiskit program jobs¶
You can view details about running and completed jobs by opening the Jobs page from the application switcher ( ), then clicking the Program jobs tab.
Qiskit Runtime tutorials and other resources¶
To learn more, visit the Qiskit Runtime Github repository. You can also implement Qiskit Runtime by using the public REST API.
Explore these Qiskit Runtime tutorials:
Database search with Grover’s algorithm using the Sampler primitive
Qiskit Runtime Introduction (Open directly in IBM Quantum Lab here)
How to use Qiskit Runtime VQE for chemistry simulation (Open directly in IBM Quantum Lab here)
How to use Qiskit Runtime Quantum Kernel Alignment (QKA) for Machine Learning (Open directly in IBM Quantum Lab here)
Limitations¶
API¶
Qiskit Runtime is still in beta mode, and heavy modifications to both functionality and API are likely to occur. Some of the changes might not be backward-compatible and would require updating your Qiskit version.
Qiskit Runtime glossary¶
Qiskit program¶
Qiskit Python source code that describes the problem to solve, combining classical and quantum computation. It takes inputs from the users, makes the calculation, and returns the results. Each instance of a Qiskit program execution is similar to a computer process and is represented as a runtime job.
Qiskit program metadata¶
The data that defines your program. Critical components are name, maximum execution time, version, backend requirements, and input/output parameters.
Qiskit Runtime¶
Qiskit Runtime is a cloud service that runs the Qiskit program remotely as a process, passing the input from the user, and handling the connectivity between the Qiskit program, the user, and the quantum processing unit. You can repeat this multiple times with the same or different Qiskit programs.
Qiskit Runtime manager¶
The main task of this component of the architecture is to prepare Qiskit Runtime, load the Qiskit programs, and supervise the correct execution.
OpenQASM circuit¶
Quantum circuit format generated by the Qiskit program. OpenQASM is the low-level language consumed by the Quantum Processing Unit (QPU).
Quantum processing unit (QPU)¶
Part of the computational unit that performs the quantum computation.