Get started with Qiskit Runtime on the IBM Quantum platform

Qiskit Runtime quick-start guide

Step 1: Install or update Qiskit packages

Install or update the following packages (qiskit, qiskit-ibm-runtime) in your development environment, which are necessary to create circuits and work with primitives with Qiskit Runtime. For detailed instructions, refer to the Qiskit textbook. Periodically check the Qiskit release notes (or rerun these commands) so that you always have the latest version.

# Installs the latest version of the Qiskit meta-package for circuit creation.
pip install qiskit -U

# Installs the latest version of the Qiskit Runtime package, which is needed to interact with the Qiskit Runtime primitives on IBM Cloud.
pip install qiskit-ibm-runtime -U

Note

Be sure to run these commands even if you already installed these packages, to verify you have the latest versions.

Step 2: Authenticate with IBM Quantum

  1. Create an IBM Quantum account or log in to your existing account by visiting the IBM Quantum login page.

  2. Copy (and/or optionally regenerate) your API token from your IBM Quantum account page.

  3. Input your API token with the command below (replace "MY_IBM_QUANTUM_TOKEN" with your API token).

from qiskit_ibm_runtime import QiskitRuntimeService

# Save an IBM Quantum account.
QiskitRuntimeService.save_account(channel="ibm_quantum", token="MY_IBM_QUANTUM_TOKEN")

Note

After calling QiskitRuntimeService.save_account(), your credentials will be stored on disk. Once they are stored, at any point in the future you can load and use them in your program simply via:

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService(channel="ibm_quantum")
backend = service.get_backend("ibmq_qasm_simulator")

Alternatively, if you do not want to save your credentials to disk and only intend to use them during the current session, you can use:

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService(channel="ibm_quantum", token='MY_API_TOKEN')

Step 3: Test your setup

Run the Hello World program to ensure that your environment is set up properly:

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService()
program_inputs = {'iterations': 1}
options = {"backend_name": "ibmq_qasm_simulator"}
job = service.run(program_id="hello-world",
                options=options,
                inputs=program_inputs
                )
print(f"job id: {job.job_id()}")
result = job.result()
print(result)

Step 4: Choose a primitive to run

Qiskit Runtime uses primitives to interface with quantum computers. Primitives provide a simplified interface for defining near-time quantum-classical workloads required to efficiently build and customize applications. The initial release of Qiskit Runtime includes two primitives: Estimator and Sampler. They perform foundational quantum computing tasks and act as an entry point to Qiskit Runtime.

Estimator

The estimator primitive allows users to efficiently calculate and interpret expectation values of quantum operators required for many algorithms. Users specify a list of circuits and observables, then tell the program how to selectively group between the lists to efficiently evaluate expectation values and variances for a given parameter input. Get started with the Estimator primitive here.

Sampler

The sampler primitive takes a circuit as an input and generates an error-mitigated readout of quasiprobabilities. This provides users a way to better evaluate shot results using error mitigation and enables them to more efficiently evaluate the possibility of multiple relevant data points in the context of destructive interference. Get started with the Sampler primitive tutorial here.

Note

Read about the maximum execution time for a Qiskit Runtime job here.

Work with prototype programs

Prototype programs are built with primitives and are tailored for specific research applications. They are experimental and subject to change as Qiskit Runtime evolves. The Prototype programs page displays all available programs. Click any program to learn more about it, and optionally choose a backend and instance 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.

View your Qiskit Runtime jobs

You can view details about running and completed jobs by opening the Jobs page from the application switcher ( switcher ).