Skip to main contentIBM Quantum Documentation Preview
This is a preview build of IBM Quantum™ documentation. Refer to docs.quantum.ibm.com for the official documentation.

Run your first Qiskit Serverless workload remotely

Package versions

The code on this page was developed using the following requirements. We recommend using these versions or newer.

qiskit[all]~=1.2.4
qiskit-aer~=0.15.1
qiskit-ibm-runtime~=0.31.0
qiskit-serverless~=0.17.1
qiskit-ibm-catalog~=0.1

This section explores how to use qiskit-ibm-catalog to list programs available in Qiskit Serverless, pass inputs into these programs, run them remotely, check their status, and retrieve results and logs.

Be sure you have authenticated to Qiskit Serverless with your IBM Quantum account (see Deploy to IBM Quantum Platform for instructions).

List programs available

You can use QiskitServerless.list() to print out a list of the available programs to run with Qiskit Serverless. This includes the previously uploaded transpile_remote_serverless.

from qiskit_ibm_catalog import QiskitServerless
 
serverless = QiskitServerless()
serverless.list()

Output:

[QiskitFunction(transpile_remote_serverless_test_9fad0bc6),
 QiskitFunction(transpile_remote_serverless),
 QiskitFunction(transpile_remote_serverless_test_7b71d607),
 QiskitFunction(transpile_remote_serverless_test_6169e40a),
 QiskitFunction(transpile_remote_serverless_test_3e28580a),
 QiskitFunction(transpile_remote_serverless_test_7e16ef16),
 QiskitFunction(transpile_remote_serverless_test_47c755bf),
 QiskitFunction(transpile_remote_serverless_test_579ed35c-3f56-484c-8a64-58dc953ed845),
 QiskitFunction(transpile_remote_serverless_test_47c79b69),
 QiskitFunction(transpile_remote_serverless_test_53c0786c),
 QiskitFunction(transpile_remote_serverless_test_094ae798-88f7-46ab-8997-5a0bf503d908),
 QiskitFunction(transpile_remote_serverless_test_35fb8da4-0fa3-4596-85c4-3a13d67f8c6a),
 QiskitFunction(transpile_remote_serverless_test_426d1904),
 QiskitFunction(transpile_remote_serverless_test_ebd79361),
 QiskitFunction(transpile_remote_serverless_test_a966c167),
 QiskitFunction(transpile_remote_serverless_test_d19e6f7e-3de0-4dde-b978-bdd03fba9845),
 QiskitFunction(transpile_remote_serverless_test_b4d7a503),
 QiskitFunction(transpile_remote_serverless_test_ceb9a116),
 QiskitFunction(transpile_remote_serverless_test_355478eb),
 QiskitFunction(transpile_remote_serverless_test),
 QiskitFunction(transpile_remote_serverless_test_8e84c5f0-962d-4cd0-bca8-ebe1e227552f),
 QiskitFunction(transpile_remote_serverless_test_4532e330),
 QiskitFunction(transpile_remote_serverless_test_7659964c),
 QiskitFunction(transpile_remote_serverless_test_5d216ee7),
 QiskitFunction(transpile_remote_serverless_test_d0757405),
 QiskitFunction(transpile_remote_serverless_test_0f048273),
 QiskitFunction(transpile_remote_serverless_test_6a68a773),
 QiskitFunction(transpile_remote_serverless_test_f9b5609f),
 QiskitFunction(transpile_remote_serverless_test_701468af-437d-4737-8a00-843f0431a09c),
 QiskitFunction(transpile_remote_serverless_test_e81ddca0),
 QiskitFunction(transpile_remote_serverless_test_c1de9270),
 QiskitFunction(transpile_remote_serverless_test_3826f696),
 QiskitFunction(transpile_remote_serverless_test_2da7da19),
 QiskitFunction(transpile_remote_serverless_test_74c54154),
 QiskitFunction(transpile_remote_serverless_test_e51063a5),
 QiskitFunction(transpile_remote_serverless_test_69c1b2c6),
 QiskitFunction(transpile_remote_serverless_test_abb21121),
 QiskitFunction(transpile_remote_serverless_test_0990ad64),
 QiskitFunction(transpile_remote_serverless_test_65db9226),
 QiskitFunction(transpile_remote_serverless_test_f7057422)]

Run an uploaded program and pass inputs

First, set up your inputs. Your program has three inputs: circuits, backend, and optimization_level. You can use random_circuit to create 30 random circuits:

from qiskit.circuit.random import random_circuit
 
qc_random = [(random_circuit(4, 4, measure=True)) for _ in range(30)]
qc_random[0].draw(output="mpl", idle_wires=False)

Output:

Next, use QiskitRuntimeService and least_busy to select a backend:

from qiskit_ibm_runtime import QiskitRuntimeService
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
print(backend.name)

Output:

ibm_brisbane

Set your optimization level:

optimization_level = 3

Select your program with serverless.load('PROGRAM_NAME'):

transpile_remote_serverless = serverless.load("transpile_remote_serverless")

Next, pass your inputs and run it in a pythonic fashion as follows:

job = transpile_remote_serverless.run(
    circuits=qc_random,
    backend=backend.name,
    optimization_level=optimization_level,
)
job.job_id

Output:

'61a5a223-937f-4cc8-9ec5-37f837b3caf7'

Check job status

With your Qiskit Serverless job_id, you can check the status of running jobs. This includes the following statuses:

  • QUEUED: The remote program is in the Qiskit Serverless queue. The queue priority is currently based on how much you've used Qiskit Serverless
  • INITIALIZING: The remote program is starting; this includes setting up the remote environment and installing dependencies
  • RUNNING: The program is running. At this stage, if you have print() outputs in your program, you can retrieve logs using job.logs()
  • DONE: The program is complete, and you can retrieve data stored in save_result() with job.results()
job.status()

Output:

'QUEUED'
Tip

Currently, the IBM Quantum workloads table only reflects Qiskit Runtime workloads. Use job.status() to see your Qiskit Serverless workload's current status.

Retrieve logs and results

As mentioned before, once a program is RUNNING, you can use job.logs() to fetch logs created from print() outputs:

logs = job.logs()
print(logs)

Output:

No logs yet.

Once a program is DONE, you can use job.results() to fetch the result stored in save_result():

result = job.result()
print(result)

Output:

{}

At any time, you can also cancel a job:

job.stop()

Output:

'Job has been stopped.'

List previously run jobs run with Qiskit Serverless

You can use jobs() to list all jobs submitted to Qiskit Serverless:

old_jobs = serverless.jobs()
old_jobs

Output:

[<Job | 61a5a223-937f-4cc8-9ec5-37f837b3caf7>,
 <Job | 9db2a810-9ebe-4161-b795-1ddbfde08759>,
 <Job | 3d94eb94-b951-428a-84f6-5653b0109cb0>,
 <Job | 73628704-a036-4d27-a591-3dad440c6ce7>,
 <Job | 71bb4d9c-9be3-494e-9858-d5d7a8e901c5>,
 <Job | 57ebf76b-86a1-4f3e-9284-33c4a7f072e1>,
 <Job | 4030e0fd-fcb4-424e-aaad-c94aae48729c>,
 <Job | f3800c17-7880-4198-be12-ed12aa5fd221>,
 <Job | f5cc50b5-c8d5-4af1-9ab9-fe574a91e770>,
 <Job | b06f2b78-1dba-4c85-a4d7-82976d7fec7f>]

You've successfully run your first Qiskit Serverless program!

Next steps

Recommendations