Qiskit Runtime (qiskit_ibm_runtime)

Modules related to Qiskit Runtime IBM Client.

Qiskit Runtime is a new architecture that streamlines computations requiring many iterations. These experiments will execute significantly faster within its improved hybrid quantum/classical process.

Primitives and sessions

Qiskit Runtime has two predefined primitives: Sampler and Estimator. These primitives provide a simplified interface for performing foundational quantum computing tasks while also accounting for the latest developments in quantum hardware and software.

Qiskit Runtime also has the concept of a session. Jobs submitted within a session are prioritized by the scheduler, and parameter data is cached for reuse. A session allows you to make iterative calls to the quantum computer more efficiently.

Below is an example of using primitives within a session:

from qiskit_ibm_runtime import QiskitRuntimeService, Session, Sampler, Estimator, Options
from qiskit.test.reference_circuits import ReferenceCircuits
from qiskit.circuit.library import RealAmplitudes
from qiskit.quantum_info import SparsePauliOp

# Initialize account.
service = QiskitRuntimeService()

# Set options, which can be overwritten at job level.
options = Options(optimization_level=3)

# Prepare inputs.
bell = ReferenceCircuits.bell()
psi = RealAmplitudes(num_qubits=2, reps=2)
H1 = SparsePauliOp.from_list([("II", 1), ("IZ", 2), ("XI", 3)])
theta = [0, 1, 1, 2, 3, 5]

with Session(service=service, backend="ibmq_qasm_simulator") as session:
    # Submit a request to the Sampler primitive within the session.
    sampler = Sampler(session=session, options=options)
    job = sampler.run(circuits=bell)
    print(f"Sampler results: {job.result()}")

    # Submit a request to the Estimator primitive within the session.
    estimator = Estimator(session=session, options=options)
    job = estimator.run(
        circuits=[psi], observables=[H1], parameter_values=[theta]
    )
    print(f"Estimator results: {job.result()}")
    # Close the session only if all jobs are finished and you don't need to run more in the session.
    session.close()

Backend data

QiskitRuntimeService also has methods, such as backend(), backends(), and least_busy(), that allow you to query for a target backend to use. These methods return one or more IBMBackend instances that contains methods and attributes describing the backend.

Supplementary Information

Account initialization

You need to initialize your account before you can start using the Qiskit Runtime service. This is done by initializing a QiskitRuntimeService instance with your account credentials. If you don’t want to pass in the credentials each time, you can use the QiskitRuntimeService.save_account() method to save the credentials on disk.

Qiskit Runtime is available on both IBM Cloud and IBM Quantum, and you can specify channel="ibm_cloud" for IBM Cloud and channel="ibm_quantum" for IBM Quantum. The default is IBM Cloud.

Runtime Jobs

When you use the run() method of the Sampler or Estimator to invoke the primitive, a RuntimeJob instance is returned. This class has all the basic job methods, such as RuntimeJob.status(), RuntimeJob.result(), and RuntimeJob.cancel().

Logging

qiskit-ibm-runtime uses the qiskit_ibm_runtime logger.

Two environment variables can be used to control the logging:

• QISKIT_IBM_RUNTIME_LOG_LEVEL: Specifies the log level to use. If an invalid level is set, the log level defaults to WARNING. The valid log levels are DEBUG, INFO, WARNING, ERROR, and CRITICAL (case-insensitive). If the environment variable is not set, then the parent logger’s level is used, which also defaults to WARNING.

• QISKIT_IBM_RUNTIME_LOG_FILE: Specifies the name of the log file to use. If specified, messages will be logged to the file only. Otherwise messages will be logged to the standard error (usually the screen).

For more advanced use, you can modify the logger itself. For example, to manually set the level to WARNING:

import logging
logging.getLogger('qiskit_ibm_runtime').setLevel(logging.WARNING)

Invoking a non-primitive program

Qiskit Runtime has a handful of predefined programs in addition to the primitives. Unlike the primitives, these programs don’t have special classes defined and can be invoked in a generic way. For example:

from qiskit_ibm_runtime import QiskitRuntimeService

# Initialize account.
service = QiskitRuntimeService()

# Configure backend options.
options = {"backend": "ibmq_qasm_simulator"}

# Prepare inputs.
runtime_inputs = {"iterations": 1}

# Invoke the "hello-world" program.
job = service.run(program_id="hello-world",
                  options=options,
                  inputs=runtime_inputs)
# Get runtime job result.
print(job.result())

Interim and final results

Some runtime programs provide interim results that inform you about program progress. You can choose to stream the interim results and final result when you run the program by passing in the callback parameter, or at a later time using the RuntimeJob.stream_results() method. For example:

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService()
options = {"backend": "ibmq_qasm_simulator"}
runtime_inputs = {"iterations": 2}

def result_callback(job_id, result):
    print(result)

# Stream results as soon as the job starts running.
job = service.run(program_id="hello-world",
                  options=options,
                  inputs=runtime_inputs,
                  callback=result_callback)
print(job.result())

Uploading a program

Authorized users can upload their custom Qiskit Runtime programs. A Qiskit Runtime program is a piece of Python code and its metadata that takes certain inputs, performs quantum and maybe classical processing, and returns the results.

Files related to writing a runtime program are in the qiskit_ibm_runtime/program directory.

Classes

QiskitRuntimeService([channel, token, url, ...])	Class for interacting with the Qiskit Runtime service.
Estimator([session, options])	Class for interacting with Qiskit Runtime Estimator primitive service.
Sampler([session, options])	Class for interacting with Qiskit Runtime Sampler primitive service.
Session([service, backend, max_time])	Class for creating a flexible Qiskit Runtime session.
IBMBackend(configuration, service, api_client)	Backend class interfacing with an IBM Quantum backend.
RuntimeJob(backend, api_client, ...[, ...])	Representation of a runtime program execution.
RuntimeProgram(program_name, program_id, ...)	Class representing program metadata.
ParameterNamespace(parameters)	A namespace for program parameters with validation.
RuntimeOptions([backend, image, log_level, ...])	Class for representing generic runtime execution options.
RuntimeEncoder(*[, skipkeys, ensure_ascii, ...])	JSON Encoder used by runtime service.
RuntimeDecoder(*args, **kwargs)	JSON Decoder used by runtime service.