Learn more about Qiskit Functions templates in our upcoming webinar on Tuesday, 15 July at 11 a.m. EDT. Register here.
Earlier this year, researchers at Cleveland Clinic published a promising new workflow for electronic structure calculations that are important in biochemical and medical applications. Their work is far from the only example we’ve seen in recent years of quantum developers building advanced heterogeneous workflows that can leverage both quantum and elastic classical compute resources far beyond what’s available in the everyday laptop. However, all too often, these innovative workflows are published in research papers and then sit untouched by the broader quantum community.
To change that, and enable more researchers to begin taking advantage of the powerful methods the quantum community is working to develop, we’re pleased to introduce Qiskit Function templates — a resource that gives you access to new workflows, like the one developed by Cleveland Clinic, right out of the box. Visit the documentation on IBM Quantum Platform to learn how to download, customize, and run Qiskit Function templates today.
Qiskit Function templates are an open-source collection of realistic code examples that give you a detailed guide to building high-quality, utility-scale application workflows using tools like the Qiskit SDK and Qiskit addons. They come in two varieties: function template implementations, which replicate cutting-edge techniques from real-world experiments, and base templates, which are more generalized code examples for building new circuit and application functions.
In either case, templates provide you with a modular pipeline that allows you to swap in new tools, methods, or configurations for your own custom experiments. All function templates are also readily deployable to Qiskit Serverless, where you can easily leverage classical compute as part of running your workflow. You can deploy your serverless package on your preferred cloud environment, or take advantage of the hosted service provided by IBM for Premium and Flex Plan users. Regardless of which option you choose, Qiskit Serverless helps to simplify execution and parallelize portions of your workflow.
Now, let’s take a closer look at the value you’ll get from the two categories of Qiskit Function templates.
Function template implementations: The latest research at your fingertips
Function template implementations are highly specialized code examples that replicate specific techniques from real-world experiments in areas like chemistry and physics — with all elements of the workflow packaged up in a reusable format complete with mid-experiment checkpoints, logs, etc. They make state-of-the-art methods like sample-based quantum diagonalization (SQD) more accessible than ever, allowing you to easily apply these methods to your use cases.
As an example of this, we can take a look at the SQD IEF-PCM Qiskit Function template created in collaboration with our partners at the Cleveland Clinic IBM Discovery Accelerator. IEF-PCM is a model used widely in quantum chemistry simulations on classical computers to understand and simulate the behavior of molecular systems in solvents. SQD, on the other hand, is a powerful simulation technique that allows you to leverage the best of both quantum and classical computing — especially classical high-performance computing (HPC) systems — to build rich and relatively large-scale simulations of quantum systems.
In June, Cleveland Clinic researchers published a promising new workflow using SQD to run quantum-centric implicit solvent simulations of electronic structure problems, which are critical for many biochemical and medical applications. Using IBM Quantum Heron QPUs, researchers were able to simulate methanol, methylamine, ethanol, and water systems — with active spaces of up to 23 orbitals.
Developing a workflow at this scale is a significant achievement, one that might take another research group months or years to replicate. That’s why the researchers set out to do more than simply publish their results in a journal. They also wanted to find a way to share their SQD workflow with the community, so other researchers and developers could explore and extend it.
To realize that goal, Cleveland Clinic and IBM worked together to create the SQD IEF-PCM Qiskit Function template, building on top of the SQD Qiskit addon. This template allows you to easily leverage, customize, and apply Cleveland Clinic’s sophisticated SQD workflow to new research. To understand how, we can walk through a brief example of how it works.
Putting Qiskit Function templates to use
Let’s say you want to use SQD to account for solute–solvent interactions in simulations of electronic structure. We’ll start by taking a look at the function template itself, sqd_pcm_entrypoint.py. The template gives you a framework that you can customize to suit your specific use case.
Keep in mind that this and all other code examples shown below are pseudocode. You can find the real, fully customizable public source code for this template here.
"""
SQD-PCM Function Template source code.
"""
from qiskit import QuantumCircuit, ...
from qiskit.transpiler import ...
from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2
import ffsim
from qiskit_addon_sqd import ...
from solve_solvent import solve_solvent # custom solver that plugs into SQD addon
from pyscf import ...
import logging
from qiskit_serverless import ...
def run_function(
backend_name,
molecule,
solvent_options,
sqd_options,
lucj_options
):
# Preparation Step: Input parsing and validation
geometry = molecule["atom"]
...
# Step 1: Map to an LUCJ quantum circuit
update_status(Job.MAPPING)
logger.info("Initializing molecule object")
circuit = QuantumCircuit(...)
...
# Step 2: Optimize for target backend
update_status(Job.OPTIMIZING_HARDWARE)
...
isa_circuit = pass_manager.run(circuit)
# Step 3: Execute on hardware with the Sampler primitve
logger.info("Submitting sampler job")
service = QiskitRuntimeService()
sampler = SamplerV2(backend)
job = sampler.run([isa_circuit])
while job.status() == "QUEUED":
update_status(Job.WAITING_QPU)
update_status(Job.EXECUTING_QPU)
# Step 4: Post-process samples with SQD
update_status(Job.POST_PROCESSING)
for i in range(iterations):
logger.info(f"Starting configuration recovery iteration {i}")
...
output = {
"lowest_energy_value": ...,
"solvation_free_energy": ...,
"metadata": ...,
...
}
return outputOnce you’ve downloaded and customized the template, it’s time to load it into Qiskit Serverless, our programming model for building, deploying, and running quantum workloads remotely. You’ll start by using qiskit-ibm-catalog to authenticate to QiskitServerless. Then, you’ll instantiate a QiskitFunction object that defines the function source code, so you can upload your custom function to Qiskit Serverless.
# Authenticate to the remote cluster
from qiskit_ibm_catalog import QiskitServerless
serverless = QiskitServerless(
channel="ibm_quantum_platform",
token="...",
instance="crn:***"
)
# instantiate a QiskitFunction for the template
from qiskit_ibm_catalog import QiskitFunction
template = QiskitFunction(
title="sqd_pcm_template",
entrypoint="sqd_pcm_entrypoint.py",
...
)
# upload the template to serverless
serverless.upload(template)After uploading the template, you can use Qiskit Serverless to execute it remotely with the desired inputs. The template allows you to specify which molecule you are observing, the solvent it’s in, and other properties that may be important for your simulation.
template = serverless.load("sqd_pcm_template")
# specify the molecule
molecule = {
"atom": """
O -0.04559 -0.75076 -0.00000;
C -0.04844 0.65398 -0.00000;
H 0.85330 -1.05128 -0.00000;
H -1.08779 0.98076 -0.00000;
H 0.44171 1.06337 0.88811;
H 0.44171 1.06337 -0.88811
""",
"basis": "cc-pvdz",
...
}
# set solvent options
solvent_options = {"method": "IEF-PCM", ...}
# set options for the LUCJ circuit and its execution on hardware
lucj_options = {...}
# set options for postprocessing samples with SQD
sqd_options = {
"sqd_iterations": 3,
"number_of_batches": 10,
...
}
# select a backend
backend_name = "ibm_torino"
job = template.run(
backend_name=backend_name,
molecule=molecule,
solvent_options=solvent_options,
lucj_options=lucj_options,
sqd_options=sqd_options,
)While the program runs, you can check its status and inspect logs. Since the entire template is open-source, you can also add print() statements to generate additional logs to capture realtime metadata and information as needed.
print(job.status())
print(job.logs())The logs will look something like this:
2025-06-27 08:42:41,358 INFO job_manager.py:531 -- Runtime env is setting up.
sqd_pcm_entrypoint.run_function:INFO:2025-06-27 08:42:45,015: Starting runtime service
sqd_pcm_entrypoint.run_function:INFO:2025-06-27 08:42:45,621: Backend: ibm_torino
sqd_pcm_entrypoint.run_function:INFO:2025-06-27 08:42:46,809: Initializing molecule object
sqd_pcm_entrypoint.run_function:INFO:2025-06-27 08:42:51,599: Performing CCSD
...Finally, after the experiment has finished running, you can retrieve the results.
result = job.result()
print(result['lowest_energy_value'])
print(result['solvation_free_energy'])
print(result['metadata']) The outputs will look something like this:
-115.15548493266616
-0.007181981952470838
{'resources_usage':
{'RUNNING: MAPPING': {'CPU_TIME': 7.57373046875},
'RUNNING: OPTIMIZING_FOR_HARDWARE': {'CPU_TIME': 5.982495069503784},
'RUNNING: WAITING_FOR_QPU': {'CPU_TIME': 8.278266191482544},
'RUNNING: EXECUTING_QPU': {'QPU_TIME': 34.58044767379761},
'RUNNING: POST_PROCESSING': {'CPU_TIME': 91.08398342132568}}
}
}And there you have it! Not only have you now successfully run an SQD experiment on IBM Quantum hardware, but you’ve also built a custom, reusable SQD workflow that you can apply to future experiments.
Base templates: Kickstart development of your own original Qiskit Function
In addition to function template implementations, you can also take advantage of base templates, which are more generalized code examples that illustrate how Qiskit functions are typically structured, and give you a useful head start in building your own.
Base templates demonstrate best practices for interface development, code formatting, unit testing, and more — reducing the time, effort, and trial-and-error you might invest when building your own function from scratch. There are currently two base templates available for use, one for development of circuit functions and another for application functions.
Try it yourself
Ready to give Qiskit Function Templates a try for yourself? There are a few different ways you can get started.
Learn: Join the Qiskit Function templates webinar on July 15 to learn more about the new research workflow the function templates introduce. Our team will take you through a detailed demo highlighting the ins and outs of using the templates, and will also share useful tips and tricks for getting started.
Customize: Templates are open source on GitHub, and they are available for download and execution today. This means that if, for example, you’re exploring chemistry applications with the SQD Qiskit addon, you can now test it on solute–solvent interactions in electronic structure simulations using the open-source SQD IEF-PCM Qiskit Function template. You could even test a physics application of the AQC-Tensor Qiskit addon with the open-source Hamiltonian simulation Qiskit Function template; the possibilities are endless. You’ll find an in-depth guide in our documentation here.
Build: If you’ve built custom, specialized power tools on top of Qiskit that you’d like to share with the community as a Function template, we invite you to open an issue and contribute to Qiskit Function templates repository. By working together and making your resources public, you open up new avenues for progress across all scientific disciplines.
Go deeper: Interested in digging deeper into the capabilities powering these templates? Check out the Qiskit addons for SQD, AQC-Tensor, and more. Learn how these modular software components can plug into your workflow to scale or design new quantum algorithms.
Our journey to fault-tolerant quantum computing cannot be realized without researchers and academics putting their brains to work and finding all that they can with the quantum technology available today. With Qiskit Function templates, we remove yet another barrier in the development of quantum computing by making it easier to get started, fostering both creativity and discovery for all interested.
