Introduction to Qiskit Functions

Qiskit Functions simplify and accelerate utility-scale algorithm discovery and application development, by abstracting away parts of the quantum software development workflow. In this way, Qiskit Functions free up time normally spent hand-writing code and fine-tuning experiments.

Functions come in two forms:

Functions are provided by IBM® and third-party partners. Each is performant for specific workload characteristics and have unique performance-tuning options. Premium Plan users can get started with IBM Qiskit Functions for free, or procure a license from one of the partners who have contributed a function to the catalog.

Get started with Qiskit Functions

Install Qiskit Functions Catalog client

To start using Qiskit Functions, install the IBM Qiskit Functions Catalog client:

pip install qiskit-ibm-catalog

Once installed, authenticate using your IBM Quantum Platform API token as follows:

from qiskit_ibm_catalog import QiskitFunctionsCatalog
 
catalog = QiskitFunctionsCatalog(token='<YOUR_IQP_API_TOKEN>')

Optionally, you can use the save_account() method to save your credentials for easy access later on, before initializing the service. This saves your credentials in the same place as QiskitRuntimeService.save_account(), so you can skip this step if you had previously used QiskitRuntimeService to save your account. Note that account credentials are saved in plain text, so only do so if you are using a trusted device.

from qiskit_ibm_catalog import QiskitFunctionsCatalog
 
# This can be skipped if you previously did QiskitRuntimeService.save_account()
QiskitFunctionsCatalog.save_account(token="<YOUR_IQP_API_TOKEN>")

Once you have authenticated, you can list the functions from the Qiskit Functions Catalog that you have access to:

catalog.list()

Output:

[QiskitFunction(ibm/circuit-function)]

Run enabled functions

Once a catalog object has been instantiated, you can select a function using catalog.load(provider/function-name):

ibm_cf = catalog.load('ibm/circuit-function')

Each Qiskit Function has custom inputs, options, and outputs. Check the specific documentation pages for the function you want to run for more information. By default, all users can only run one function job at a time:

job = ibm_cf.run(
    instance=...,
    pubs=[],
    backend="backend_name"
)
 
job.job_id

Output:

0ede4d0f-06d6-4360-86a1-5028ca511b3f

Check job status

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

• QUEUED: The remote program is in the Qiskit Function queue. The queue priority is based on how much you've used Qiskit Functions.
• INITIALIZING: The remote program is starting; this includes setting up the remote environment and installing dependencies.
• RUNNING: The program is running.
• DONE: The program is complete, and you can retrieve result data with job.results().
• ERROR: The program stopped running because of a problem. Use job.result() to get the error message.
• CANCELED: The program was canceled; either by a user, the service, or the server.

job.status()

Output:

'DONE'

Retrieve results

Once a program is DONE, you can use job.results() to fetch the result. This output format varies with each function, so be sure to follow the specific documentation:

result = job.result()
print(result)

Output:

PubResult(data=DataBin(evs=np.ndarray(<shape=(20,), dtype=float64>), stds=np.ndarray(<shape=(20,), dtype=float64>), evs_noise_factors=np.ndarray(<shape=(20, 3), dtype=float64>), stds_noise_factors=np.ndarray(<shape=(20, 3), dtype=float64>), ensemble_stds_noise_factors=np.ndarray(<shape=(20, 3), dtype=float64>), evs_extrapolated=np.ndarray(<shape=(20, 2, 4), dtype=float64>), stds_extrapolated=np.ndarray(<shape=(20, 2, 4), dtype=float64>), shape=(20,)), metadata={'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {'zne': {'extrapolator': array(['exponential', 'exponential', 'exponential', 'exponential',
       'exponential', 'exponential', 'exponential', 'exponential',
       'exponential', 'exponential', 'exponential', 'exponential',
       'exponential', 'exponential', 'exponential', 'exponential',
       'exponential', 'exponential', 'exponential', 'exponential'],
      dtype='<U11')}, 'layer_noise': {'noise_overhead': 1, 'total_mitigated_layers': 0, 'unique_mitigated_layers': 0, 'unique_mitigated_layers_noise_overhead': []}}, 'num_randomizations': 32})
      

At any time, you can also cancel a job:

job.stop()

Output:

'Job has been stopped.'

List previously run jobs run with Qiskit Functions

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

old_jobs = catalog.jobs()
old_jobs

Output:

[<Job | 0ede4d0f-06d6-4360-86a1-5028ca511b3f>,
 <Job | abf78e9a-b554-4e38-966a-f99cff877b8c>,
 <Job | 90e1109e-809f-4768-a2dc-f45bf71a97b4>,
 <Job | 313050f2-aa78-4d7d-99f4-44bdfe98e4d7>]

Fetch error messages

If a program status is ERROR, use job.result() to fetch the error message to help debug as follows:

print(job.result())

Next steps