Archived: This repository has been merged with qiskit-ibm-runtime to keep documentation closer to code. This repository is archived and no longer maintained. Please use qiskit-ibm-runtime instead.
Qiskit Runtime is a new architecture offered by IBM Quantum that streamlines quantum computations. It is designed to use classical compute resources to execute quantum circuits with more efficiency on quantum processors.
Using Qiskit Runtime, for example, a research team at IBM Quantum was able to achieve 120x speed up in their lithium hydride simulation. For more information, see the IBM Research blog
Qiskit Runtime allows authorized users to upload quantum programs. A quantum program, also called a Qiskit runtime program, is a piece of Python code that takes certain inputs, performs quantum and classical computation, and returns the processing results. The users can then invoke these quantum programs by simply passing in the required input parameters.
🚀 Qiskit Runtime is now available on all IBM Quantum systems. If ibm-q/open/main
is the
only hub/group/project in your account, then you can only execute runtime programs on
ibmq_qasm_simulator
. If you have more than one hub/group/project, you can execute runtime programs
on any systems to which you have access and upload your custom programs.
You need to install the required packages for the tutorials, which are documented in requirements.txt
.
After that, you can download this repository and use Jupyter Notebook/Lab to explore the
tutorials and learn how Qiskit Runtime works.
git clone https://github.com/Qiskit-Partners/qiskit-runtime.git
cd qiskit-runtime
pip install -r requirements.txt
cd tutorials
jupyter notebook .
Before you can start using Qiskit Runtime, make sure you have an IBM Quantum
account. If this is
your first time using IBM Quantum or Qiskit, please refer to the instruction in the
qiskit-ibmq-provider
repository to configure your IBM Quantum credentials.
To list all available programs:
from qiskit import IBMQ
IBMQ.load_account()
provider = IBMQ.get_provider(hub='MY_HUB', group='MY_GROUP', project='MY_PROJECT')
provider.runtime.pprint_programs()
pprint_programs()
prints the metadata of all programs visible to you. A program's metadata
consists of its ID, name, description, input parameters, return values, interim results, and
other information that helps you to know more about the program.
If you know the ID of the program you're looking for, you can also print out the metadata of just that one program:
print(provider.runtime.program('hello-world'))
The output of the code above would be:
hello-world:
Name: hello-world
Description: A sample runtime program.
Creation date: 2021-07-02T13:45:13Z
Update date: 2021-07-02T13:45:13Z
Max execution time: 300
Input parameters:
Properties:
- iterations:
Description: Number of iterations to run. Each iteration generates a runs a random circuit.
Minimum: 0
Type: integer
Required: True
Interim results:
Properties:
- counts:
Description: Histogram data of the circuit result.
Type: object
Required: False
- iteration:
Description: Iteration number.
Type: integer
Required: False
Returns:
Description: A string that says 'All done!'.
Type: string
hello-world
is a sample program used for demonstration.
It takes only 1 input parameter iterations
, which indicates how many iterations to run.
For each iteration it generates and runs a random 5-qubit circuit and returns the counts as well
as the iteration number as the interim results. When the program finishes, it returns the sentence
All done!
. This program has a maximum execution time of 300 seconds, after which the execution will
be forcibly terminated.
Because hello-world
provides interim results, which are results available to you while the program is
still running, we want to first define a callback function that would handle these interim results:
def interim_result_callback(job_id, interim_result):
print(f"interim result: {interim_result}")
When an interim result is available, this callback function will be invoked and the result data passed to it. Not all programs provide interim results, and you don't have to provide a callback even if the program you're executing does provide them.
To run the hello-world
program:
program_inputs = {
'iterations': 3
}
options = {'backend_name': 'ibmq_montreal'}
job = provider.runtime.run(program_id="hello-world",
options=options,
inputs=program_inputs,
callback=interim_result_callback
)
print(f"job ID: {job.job_id()}")
result = job.result()
While not strictly necessary, deleting unwanted jobs can help with performance when you want to query for old jobs. To delete a job:
provider.runtime.delete_job('JOB_ID')
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.
This README only provides a quick overview of Qiskit Runtime. Check out the
tutorials.
The Qiskit user interface for accessing Qiskit Runtime is provided by qiskit-ibmq-provider
, so you
might want to also check out its runtime API documentation.