Runtime (qiskit.providers.ibmq.runtime)

Modules related to Qiskit Runtime Service.

Note

The Qiskit Runtime service is not available to all providers. To check if your provider has access:

from qiskit import IBMQ

IBMQ.load_account()
provider = IBMQ.get_provider(...)

can_use_runtime = provider.has_service('runtime')

Note

Not all backends support Qiskit Runtime. Refer to documentation in Qiskit-Partners/qiskit-runtime for more information.

Caution

This package is currently provided in beta form and heavy modifications to both functionality and API are likely to occur. Backward compatibility is not always guaranteed.

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

The Qiskit Runtime Service allows authorized users to upload their Qiskit quantum programs. A Qiskit quantum program, also called a 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. The same or other authorized users can invoke these quantum programs by simply passing in parameters.

Qiskit-Partners/qiskit-runtime contains detailed tutorials on how to use Qiskit Runtime.

Listing runtime programs

To list all available runtime programs:

from qiskit import IBMQ

provider = IBMQ.load_account()

# List all available programs.
provider.runtime.pprint_programs()

# Get a single program.
program = provider.runtime.program('circuit-runner')

# Print program metadata.
print(program)

In the example above, provider.runtime points to the runtime service class IBMRuntimeService, which is the main entry point for using this service. The example prints the program metadata of all available runtime programs and of just the circuit-runner program. A program metadata consists of the program’s ID, name, description, input parameters, return values, interim results, and other information that helps you to know more about the program.

Invoking a runtime program

You can use the IBMRuntimeService.run() method to invoke a runtime program. For example:

from qiskit import IBMQ, QuantumCircuit
from qiskit.providers.ibmq import RunnerResult


provider = IBMQ.load_account()
backend = provider.backend.ibmq_qasm_simulator

# Create a circuit.
qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

# Set the "circuit-runner" program parameters
params = provider.runtime.program(program_id="circuit-runner").parameters()
params.circuits = qc
params.measurement_error_mitigation = True

# Configure backend options
options = {'backend_name': backend.name()}

# Execute the circuit using the "circuit-runner" program.
job = provider.runtime.run(program_id="circuit-runner",
                        options=options,
                        inputs=params)

# Get runtime job result.
result = job.result(decoder=RunnerResult)

The example above invokes the circuit-runner program, which compiles, executes, and optionally applies measurement error mitigation to the circuit result.

Runtime Jobs

When you use the IBMRuntimeService.run() method to invoke a runtime program, a RuntimeJob instance is returned. This class has all the basic job methods, such as RuntimeJob.status(), RuntimeJob.result(), and RuntimeJob.cancel(). Note that it does not have the same methods as regular circuit jobs, which are instances of IBMQJob.

Interim results

Some runtime programs provide interim results that inform you about program progress. You can choose to stream the interim results 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 import IBMQ, QuantumCircuit

provider = IBMQ.load_account()
backend = provider.backend.ibmq_qasm_simulator

def interim_result_callback(job_id, interim_result):
    print(interim_result)

# Stream interim results as soon as the job starts running.
job = provider.runtime.run(program_id="circuit-runner",
                           options=options,
                           inputs=program_inputs,
                           callback=interim_result_callback)

Uploading a program

Note

Only authorized accounts can upload programs. Having access to the runtime service doesn’t imply access to upload programs.

Each runtime program has both data and metadata. Program data is the Python code to be executed. Program metadata provides usage information, such as program description, its inputs and outputs, and backend requirements. A detailed program metadata helps the consumers of the program to know what is needed to run the program.

Each program data needs to have a main(backend, user_messenger, **kwargs) method, which serves as the entry point to the program. The backend parameter is a ProgramBackend instance whose ProgramBackend.run() method can be used to submit circuits. The user_messenger is a UserMessenger instance whose UserMessenger.publish() method can be used to publish interim and final results. See qiskit/providers/ibmq/runtime/program/program_template.py for a program data template file.

Each program metadata must include at least the program name, description, and maximum execution time. You can find description of each metadata field in the IBMRuntimeService.upload_program() method. Instead of passing in the metadata fields individually, you can pass in a JSON file or a dictionary to IBMRuntimeService.upload_program() via the metadata parameter. qiskit/providers/ibmq/runtime/program/program_metadata_sample.json is a sample file of program metadata.

You can use the IBMRuntimeService.upload_program() to upload a program. For example:

from qiskit import IBMQ

provider = IBMQ.load_account()
program_id = provider.runtime.upload_program(
                data="my_vqe.py",
                metadata="my_vqe_metadata.json",
                version="1.2"
            )

In the example above, the file my_vqe.py contains the program data, and my_vqe_metadata.json contains the program metadata. An additional parameter version is also specified, which takes precedence over any version value specified in my_vqe_metadata.json.

Method IBMRuntimeService.delete_program() allows you to delete a program.

Files related to writing a runtime program are in the qiskit/providers/ibmq/runtime/program directory.

Classes

IBMRuntimeService(provider)	Class for interacting with the Qiskit Runtime service.
RuntimeJob(backend, api_client, credentials, …)	Representation of a runtime program execution.
RuntimeProgram(program_name, program_id, …)	Class representing program metadata.
UserMessenger()	Base class for handling communication with program users.
ProgramBackend(configuration[, provider])	Base class for a program backend.
ResultDecoder()	Runtime job result decoder.
RuntimeEncoder(*[, skipkeys, ensure_ascii, …])	JSON Encoder used by runtime service.
RuntimeDecoder(*args, **kwargs)	JSON Decoder used by runtime service.
ParameterNamespace(params)	A namespace for program parameters with validation.