Run your first Qiskit Serverless workload remotely

qiskit[all]~=1.3.1
qiskit-ibm-runtime~=0.34.0
qiskit-aer~=0.15.1
qiskit-serverless~=0.18.0
qiskit-ibm-catalog~=0.2
qiskit-addon-sqd~=0.8.1
qiskit-addon-utils~=0.1.0
qiskit-addon-mpf~=0.2.0
scipy~=1.14.1
qiskit-addon-aqc-tensor~=0.1.2
qiskit-addon-obp~=0.1.0
scipy~=1.14.1
pyscf~=2.7.0

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 fetch 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()
next(
    program
    for program in serverless.list()
    if program.title == "transpile_remote_serverless"
)

Output:

QiskitFunction(transpile_remote_serverless)

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, seed=i)) for i in range(10)]
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
 
# If you have not previously saved your credentials, follow instructions at
# https://docs.quantum.ibm.com/guides/setup-channel#iqp
# to authenticate with your API token.
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
print(backend.name)

Output:

ibm_kyiv

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:

'3fadc753-6672-4106-8783-e782d88c4633'

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'

You've successfully run your first Qiskit Serverless program!

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.

At any time, you can also cancel a job:

job.stop()

Output:

'Job has been stopped.'

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

# We can't get results from a cancelled job, so we'll fetch a completed one instead
completed_job = next(
    job for job in serverless.jobs() if job.status() == "DONE"
)
completed_job.result()

Output:

[<qiskit.circuit.quantumcircuit.QuantumCircuit at 0x7f25b1a49410>,
 <qiskit.circuit.quantumcircuit.QuantumCircuit at 0x7f25b16be710>,
 <qiskit.circuit.quantumcircuit.QuantumCircuit at 0x7f25b16d7e90>]

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 | 3fadc753-6672-4106-8783-e782d88c4633>,
 <Job | 86177d7b-9e27-433b-a067-69d29f5ce59a>,
 <Job | 2413216a-60f5-4771-bfaa-4f2f1c137e29>,
 <Job | 57d784b2-edc3-4bbd-b6f1-a3572ab091b4>,
 <Job | 3aa6ff7c-4190-45d4-a667-6d0d7a84ff93>,
 <Job | 296974a6-f70c-4a94-b765-75c1aa820e16>,
 <Job | 8ba75351-f7df-4fd0-ba05-c69f08d2595a>,
 <Job | 40258467-539f-4211-b14d-650c3e8422e6>,
 <Job | c3e2c659-7d63-43c7-9042-2a4f9c06e6f0>,
 <Job | 157c2b84-2c0c-4433-849b-5b2618c5d9d2>]

Next steps