Get started with Qiskit Functions

Premium, Flex, and On-Prem (through the IBM Quantum Platform API) Plan users can get started with IBM Qiskit Functions for free, or can procure a license from one of the partners who have contributed a function to the catalog.

Request a free trial for third-party Qiskit Functions

To request a free trial, navigate to the Qiskit Functions Catalog, and explore the details panel. Click Request a free trial and fill out information required by the Functions partner, including the IBM Cloud AccessGroupId:

1. Navigate to IBM Cloud IAM.
2. Verify eligibility.
   • Switch your account in the menu bar on the header to one with the following format: XXXXXXX - [Organization Name]
   • Ensure the organization is the same as the one associated with your Premium account.
   • If you see "[Your Name]'s Account", you are using your personal account, which is not eligible for premium access.
3. Find your access group ID.
   • Click a group name.
   • Click Details.
   • Copy the access group ID. It should start with AccessGroup-.

Install the Qiskit Functions Catalog client

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

   pip install qiskit-ibm-catalog
   

2. Retrieve your API key from the IBM Quantum Platform dashboard, and activate your Python virtual environment. See the installation instructions if you do not already have a virtual environment set up.

   If you are working in a trusted Python environment (such as on a personal laptop or workstation), use the save_account() method to save your credentials locally. (Skip to the next step if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Quantum Platform.)

   To use save_account(), run python in your shell, then enter the following:

   from qiskit_ibm_catalog import QiskitFunctionsCatalog
   
   QiskitFunctionsCatalog.save_account(channel="ibm_quantum_platform", token="<your-token>", instance="<instance-crn>")

   Type exit(). From now on, whenever you need to authenticate to the service, you can load your credentials with the following:

   from qiskit_ibm_catalog import QiskitFunctionsCatalog
   catalog = QiskitFunctionsCatalog()

   For example:

   # Load saved credentials
   from qiskit_ibm_catalog import QiskitFunctionsCatalog
   
   catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

3. Avoid executing code on an untrusted machine or an external cloud Python environment to minimize security risks. If you must use an untrusted environment (on, for example, a public computer), change your API key after each use by deleting it on the IBM Cloud API keys page to reduce risk. Learn more in the Managing user API keys topic. To initialize the service in this situation, use this code:

   from qiskit_ibm_catalog import QiskitFunctionsCatalog
   
   # After using the following code, delete your API key on the
   # IBM Quantum Platform home dashboard
   catalog = QiskitFunctionsCatalog(token="<YOUR_API_KEY>") # Use the 44-character
   # API_KEY you created and saved from the IBM Quantum Platform Home dashboard

   Protect your API key

   Never include your key in source code, Python scripts, or notebook files. When sharing code with others, ensure that your API key is not embedded directly within the Python script. Instead, share the script without the key and provide instructions for securely setting it up.

   If you accidentally share your key with someone or include it in version control like Git, immediately revoke your key by deleting it on the IBM Cloud API keys page to reduce risk. Learn more in the Managing user API keys topic.

List the functions you can access

After you authenticate, you can list the functions from the Qiskit Functions Catalog that you have access to:

catalog.list()

Output:

[QiskitFunction(qunova/hivqe-chemistry),
 QiskitFunction(global-data-quantum/quantum-portfolio-optimizer),
 QiskitFunction(algorithmiq/tem),
 QiskitFunction(qedma/qesem),
 QiskitFunction(multiverse/singularity),
 QiskitFunction(ibm/circuit-function),
 QiskitFunction(q-ctrl/optimization-solver),
 QiskitFunction(colibritd/quick-pde),
 QiskitFunction(q-ctrl/performance-management),
 QiskitFunction(kipu-quantum/iskay-quantum-optimizer)]

Check available backends and capacity

Before you run a function, check which backends your instance can reach and how much runtime capacity you have left. run() performs the same checks before it submits a job, so you can catch capacity and backend problems early.

List the backends your instance can reach. Results are cached per catalog. Pass refresh_cache=True to refresh them.

catalog.backends()

Look up a single backend and confirm access:

catalog.backend("ibm_fez")

You can also get the backend with the fewest pending jobs:

catalog.least_busy()

Use usage() to see your remaining runtime capacity. It returns usage_remaining_seconds and usage_limit_reached for the active instance.

catalog.usage()

For example, check your remaining capacity before a long batch of jobs, and stop if there is not enough left to finish it:

usage = catalog.usage()
if usage["usage_remaining_seconds"] < 600:
    raise SystemExit("Not enough capacity remaining to start this batch.")

Run enabled functions

After a catalog object has been instantiated, you can select a function by 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(
    pubs=[(circuit, observable)],
    instance=instance,
    backend_name=backend_name,  # E.g. "ibm_fez"
)

job.job_id

Output:

'7f08c9d5-471b-4da2-92e7-4f2cb94c23a8'

job = ibm_cf.run(
    pubs=[(circuit, observable)],
    instance=instance,
    backend_name=backend_name,  # E.g. "ibm_fez"
    suppress_low_usage_warning=True,
)

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. This also includes several more detailed statuses if supported by specific functions.

  • RUNNING: MAPPING: The function is currently mapping your classical inputs to quantum inputs.
  • RUNNING: OPTIMIZING_FOR_HARDWARE: The function is optimizing for the selected QPU. This could include circuit transpilation, QPU characterization, observable backpropagation, and so forth.
  • RUNNING: WAITING_FOR_QPU: The function has submitted a job to Qiskit Runtime, and is waiting in the queue.
  • RUNNING: EXECUTING_QPU: The function has an active Qiskit Runtime job.
  • RUNNING: POST_PROCESSING: The function is post-processing results, which can include error mitigation, mapping quantum results to classical, and so forth.

• 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 by a user, the service, or the server.

  job.status()

  Output:

  'QUEUED'
  

Retrieve results

After 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:

PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(<shape=(), dtype=float64>), stds=np.ndarray(<shape=(), dtype=float64>), ensemble_standard_error=np.ndarray(<shape=(), dtype=float64>)), metadata={'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32})], metadata={'dynamical_decoupling': {'enable': True, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'}, 'twirling': {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'}, 'resilience': {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False}, 'version': 2})

You can also cancel a job at any time:

job.stop()

Output:

'Job has been stopped.'

List previously run Qiskit Functions jobs

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

old_jobs = catalog.jobs()
old_jobs

Output:

[<Job | f6c29f49-4d5f-4fff-aca6-2e9a115b9763>,
 <Job | 7f08c9d5-471b-4da2-92e7-4f2cb94c23a8>,
 <Job | 62fe9176-d1e5-467e-b2bd-7a3f3c7be4e5>,
 <Job | af525b2e-16b1-45a1-80bb-dbd94ce30258>,
 <Job | b95a7a57-c1ad-4958-b7ac-953e4e1ee824>,
 <Job | 7bfa33da-0f17-4e67-84b6-f556f7eeb436>,
 <Job | ca46c191-9eb9-4de6-bfa7-b60d7eb29b5e>,
 <Job | 6ac0ba93-3831-43fb-9fb9-760da2225e06>,
 <Job | f0e38071-060d-47e8-988d-9cc1f69358e3>,
 <Job | 629cf110-e490-4675-8a07-f6d298d166b0>]

If you already have the job ID for a certain job, you can retrieve the job with catalog.get_job_by_id():

# First, get the most recent job that has been executed.
latest_job = old_jobs[0]

# We can also get that same job with get_job_by_id
job_by_id = catalog.get_job_by_id(latest_job.job_id)

# Verify that the job is the same using both retrieval methods.
assert job_by_id.job_id == latest_job.job_id

# Print the job_id for this job.
print(job_by_id.job_id)

Output:

f6c29f49-4d5f-4fff-aca6-2e9a115b9763

Fetch error messages

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

job.error_message()

Output:

qiskit.exceptions.QiskitError: 'Workflow execution failed -- https://docs.quantum.ibm.com/errors#9999'

Next steps