qiskit.providers.ibmq.runtime.IBMRuntimeService¶

class IBMRuntimeService(provider)[source]¶

Class for interacting with the Qiskit Runtime service.

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.

A sample workflow of using the runtime service:

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

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

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

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

# Execute the circuit using the "circuit-runner" program.
program_inputs = {'circuits': circuit, 'measurement_error_mitigation': True}
options = {'backend_name': backend.name()}
job = provider.runtime.run(program_id="circuit-runner",
                           options=options,
                           inputs=program_inputs)

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

If the program has any interim results, you can use the callback parameter of the run() method to stream the interim results. Alternatively, you can use the RuntimeJob.stream_results() method to stream the results at a later time, but before the job finishes.

The run() method returns a RuntimeJob object. You can use its methods to perform tasks like checking job status, getting job result, and canceling job.

IBMRuntimeService constructor.

Paramètres: provider (AccountProvider) – IBM Quantum account provider.

__init__(provider)[source]¶

IBMRuntimeService constructor.

Paramètres: provider (AccountProvider) – IBM Quantum account provider.

Methods

`__init__`(provider)	IBMRuntimeService constructor.
`delete_job`(job_id)	Delete a runtime job.
`delete_program`(program_id)	Delete a runtime program.
`job`(job_id)	Retrieve a runtime job.
`jobs`([limit, skip])	Retrieve all runtime jobs.
`logout`()	Clears authorization cache on the server.
`pprint_programs`([refresh])	Pretty print information about available runtime programs.
`program`(program_id[, refresh])	Retrieve a runtime program.
`programs`([refresh])	Return available runtime programs.
`run`(program_id, options, inputs[, callback, …])	Execute the runtime program.
`upload_program`(data[, metadata, name, …])	Upload a runtime program.

delete_job(job_id)[source]¶

Delete a runtime job.

Note that this operation cannot be reversed.

Paramètres

job_id (str) – ID of the job to delete.

Lève

RuntimeJobNotFound – If the job doesn’t exist.
QiskitRuntimeError – If the request failed.

Type renvoyé

None

delete_program(program_id)[source]¶

Delete a runtime program.

Paramètres

program_id (str) – Program ID.

Lève

RuntimeProgramNotFound – If the program doesn’t exist.
QiskitRuntimeError – If the request failed.

Type renvoyé

None

job(job_id)[source]¶

Retrieve a runtime job.

Paramètres

job_id (str) – Job ID.

Type renvoyé

RuntimeJob

Renvoie

Runtime job retrieved.

Lève

RuntimeJobNotFound – If the job doesn’t exist.
QiskitRuntimeError – If the request failed.

jobs(limit=10, skip=0)[source]¶

Retrieve all runtime jobs.

Paramètres

limit (int) – Number of jobs to retrieve.
skip (int) – Starting index for the job retrieval.

Type renvoyé

List[RuntimeJob]

Renvoie

A list of runtime jobs.

logout()[source]¶

Clears authorization cache on the server.

For better performance, the runtime server caches each user’s authorization information. This method is used to force the server to clear its cache.

Note

Invoking this method ONLY when your access level to the runtime service has changed - for example, the first time your account is given the authority to upload a program.

Type renvoyé: None

pprint_programs(refresh=False)[source]¶

Pretty print information about available runtime programs.

Paramètres: refresh (bool) – If True, re-query the server for the programs. Otherwise return the cached value.
Type renvoyé: None

program(program_id, refresh=False)[source]¶

Retrieve a runtime program.

Currently only program metadata is returned.

Paramètres

program_id (str) – Program ID.
refresh (bool) – If True, re-query the server for the program. Otherwise return the cached value.

Type renvoyé

RuntimeProgram

Renvoie

Runtime program.

Lève

RuntimeProgramNotFound – If the program does not exist.
QiskitRuntimeError – If the request failed.

programs(refresh=False)[source]¶

Return available runtime programs.

Currently only program metadata is returned.

Paramètres: refresh (bool) – If True, re-query the server for the programs. Otherwise return the cached value.
Type renvoyé: List[RuntimeProgram]
Renvoie: A list of runtime programs.

run(program_id, options, inputs, callback=None, result_decoder=None)[source]¶

Execute the runtime program.

Paramètres

program_id (str) – Program ID.
options (Dict) – Runtime options that control the execution environment. Currently the only available option is backend_name, which is required.
inputs (Dict) – Program input parameters. These input values are passed to the runtime program.
callback (Optional[Callable]) –
Callback function to be invoked for any interim results. The callback function will receive 2 positional parameters:
1. Job ID
2. Job interim result.
result_decoder (Optional[Type[ResultDecoder]]) – A ResultDecoder subclass used to decode job results. ResultDecoder is used if not specified.

Type renvoyé

RuntimeJob

Renvoie

A RuntimeJob instance representing the execution.

Lève

IBMQInputValueError – If input is invalid.

upload_program(data, metadata=None, name=None, max_execution_time=None, description=None, version=None, backend_requirements=None, parameters=None, return_values=None, interim_results=None)[source]¶

Upload a runtime program.

In addition to program data, the following program metadata is also required:

name

max_execution_time

description

Program metadata can be specified using the metadata parameter or individual parameter (for example, name and description). If the same metadata field is specified in both places, the individual parameter takes precedence. For example, if you specify:

upload_program(metadata={"name": "name1"}, name="name2")

name2 will be used as the program name.

Paramètres

data (Union[bytes, str]) – Name of the program file or program data to upload.
metadata (Union[Dict, str, None]) – Name of the program metadata file or metadata dictionary. A metadata file needs to be in the JSON format. See program/program_metadata_sample.yaml for an example.
name (Optional[str]) – Name of the program. Required if not specified via metadata.
max_execution_time (Optional[int]) – Maximum execution time in seconds. Required if not specified via metadata.
description (Optional[str]) – Program description. Required if not specified via metadata.
version (Optional[float]) – Program version. The default is 1.0 if not specified.
backend_requirements (Optional[str]) – Backend requirements.
parameters (Optional[List[ProgramParameter]]) – A list of program input parameters.
return_values (Optional[List[ProgramResult]]) – A list of program return values.
interim_results (Optional[List[ProgramResult]]) – A list of program interim results.

Type renvoyé

str

Renvoie

Program ID.

Lève

IBMQInputValueError – If required metadata is missing.
RuntimeDuplicateProgramError – If a program with the same name already exists.
IBMQNotAuthorizedError – If you are not authorized to upload programs.
QiskitRuntimeError – If the upload failed.