From 44c81e08705aee2a2689c666d5695552b191d7b5 Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Thu, 25 Jun 2026 09:55:46 -0400 Subject: [PATCH 1/2] Move functions pages to subsite --- docs/functions/_toc.json | 151 +++++++++++++ .../colibritd-pde.ipynb | 0 .../global-data-quantum-optimizer.ipynb | 0 .../kipu-optimization.ipynb | 0 .../multiverse-computing-singularity.ipynb | 0 .../q-ctrl-optimization-solver.ipynb | 0 .../qunova-chemistry.ipynb | 0 .../circuit-functions}/algorithmiq-tem.ipynb | 0 .../q-ctrl-performance-management.ipynb | 0 .../circuit-functions}/qedma-qesem.ipynb | 0 ...function-template-chemistry-workflow.ipynb | 0 ...tion-template-hamiltonian-simulation.ipynb | 0 .../qiskit-function-templates.mdx | 0 .../get-started.ipynb} | 213 ++++-------------- docs/functions/index.ipynb | 137 +++++++++++ 15 files changed, 330 insertions(+), 171 deletions(-) create mode 100644 docs/functions/_toc.json rename docs/{guides => functions/application-functions}/colibritd-pde.ipynb (100%) rename docs/{guides => functions/application-functions}/global-data-quantum-optimizer.ipynb (100%) rename docs/{guides => functions/application-functions}/kipu-optimization.ipynb (100%) rename docs/{guides => functions/application-functions}/multiverse-computing-singularity.ipynb (100%) rename docs/{guides => functions/application-functions}/q-ctrl-optimization-solver.ipynb (100%) rename docs/{guides => functions/application-functions}/qunova-chemistry.ipynb (100%) rename docs/{guides => functions/circuit-functions}/algorithmiq-tem.ipynb (100%) rename docs/{guides => functions/circuit-functions}/q-ctrl-performance-management.ipynb (100%) rename docs/{guides => functions/circuit-functions}/qedma-qesem.ipynb (100%) rename docs/{guides => functions/function-templates}/function-template-chemistry-workflow.ipynb (100%) rename docs/{guides => functions/function-templates}/function-template-hamiltonian-simulation.ipynb (100%) rename docs/{guides => functions/function-templates}/qiskit-function-templates.mdx (100%) rename docs/{guides/functions.ipynb => functions/get-started.ipynb} (52%) create mode 100644 docs/functions/index.ipynb diff --git a/docs/functions/_toc.json b/docs/functions/_toc.json new file mode 100644 index 000000000000..70ddf72f96cb --- /dev/null +++ b/docs/functions/_toc.json @@ -0,0 +1,151 @@ +{ + "parentUrl": "/docs/guides", + "parentLabel": "Documentation", + "title": "Qiskit Functions", + "collapsed": true, + "children": [ + { + "title": "", + "children": [ + { + "title": "Overview", + "url": "/docs/functions" + }, + { + "title": "Get started with functions", + "url": "/docs/functions/get-started" + }, + { + "title": "Circuit functions", + "children": [ + { + "title": "Algorithmiq Tensor-network error mitigation", + "url": "/docs/functions/circuit-functions/algorithmiq-tem" + }, + { + "title": "Q-CTRL Performance Management", + "url": "/docs/functions/circuit-functions/q-ctrl-performance-management" + }, + { + "title": "Qedma QESEM", + "url": "/docs/functions/circuit-functions/qedma-qesem" + } + ] + }, + { + "title": "Application functions", + "children": [ + { + "title": "Kipu Quantum Iskay Quantum Optimizer", + "url": "/docs/functions/application-functions/kipu-optimization" + }, + { + "title": "Multiverse Computing Singularity", + "url": "/docs/functions/application-functions/multiverse-computing-singularity" + }, + { + "title": "Q-CTRL Optimization Solver", + "url": "/docs/functions/application-functions/q-ctrl-optimization-solver" + }, + { + "title": "Quantum Portfolio Optimizer: A Qiskit Function by Global Data Quantum", + "url": "/docs/functions/application-functions/global-data-quantum-optimizer" + }, + { + "title": "QUICK-PDE: A Qiskit Function by ColibriTD", + "url": "/docs/functions/application-functions/colibritd-pde" + }, + { + "title": "Qunova Computing HI-VQE Chemistry", + "url": "/docs/functions/application-functions/qunova-chemistry" + } + ] + }, + { + "title": "Qiskit Function templates", + "children": [ + { + "title": "Introduction to Qiskit Function templates", + "url": "/docs/functions/function-templates/qiskit-function-templates" + }, + { + "title": "Template for chemistry simulation", + "url": "/docs/functions/function-templates/function-template-chemistry-workflow" + }, + { + "title": "Template for Hamiltonian simulation", + "url": "/docs/functions/function-templates/function-template-hamiltonian-simulation" + } + ] + } + ], + "collapsible": false + }, + { + "title": "Tutorials", + "collapsible": false, + "children": [ + { + "title": "Circuit function tutorials", + "children": [ + { + "title": "Transverse-Field Ising Model with Q-CTRL's Performance Management", + "url": "/docs/tutorials/transverse-field-ising-model" + }, + { + "title": "Simulate 2D tilted-field Ising with the QESEM function", + "url": "/docs/tutorials/qedma-2d-ising-with-qesem" + }, + { + "title": "Simulate a kicked Ising model with the TEM function", + "url": "/docs/tutorials/simulate-kicked-ising-tem" + } + ] + }, + { + "title": "Application function tutorials", + "children": [ + { + "title": "Dynamic portfolio optimization with Global Data Quantum's Portfolio Optimizer", + "url": "/docs/tutorials/global-data-quantum-optimizer" + }, + { + "title": "Higher-order binary optimization with Q-CTRL's Optimization Solver", + "url": "/docs/tutorials/solve-higher-order-binary-optimization-problems-with-q-ctrls-optimization-solver" + }, + { + "title": "Model a flowing non-viscous fluid using QUICK-PDE", + "url": "/docs/tutorials/colibritd-pde" + }, + { + "title": "Dissociation PES curves with Qunova HiVQE", + "url": "/docs/tutorials/qunova-hivqe" + }, + { + "title": "Quantum Phase Estimation with Q-CTRL's Qiskit Functions", + "url": "/docs/tutorials/quantum-phase-estimation-qctrl" + }, + { + "title": "Solve the Market Split problem with Kipu Quantum's Iskay Quantum Optimizer", + "url": "/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer" + }, + { + "title": "Hybrid quantum-enhanced ensemble classification (grid stability workflow)", + "url": "/docs/tutorials/sml-classification" + } + ] + } + ] + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "/docs/api/functions" + } + ] + } + ] +} diff --git a/docs/guides/colibritd-pde.ipynb b/docs/functions/application-functions/colibritd-pde.ipynb similarity index 100% rename from docs/guides/colibritd-pde.ipynb rename to docs/functions/application-functions/colibritd-pde.ipynb diff --git a/docs/guides/global-data-quantum-optimizer.ipynb b/docs/functions/application-functions/global-data-quantum-optimizer.ipynb similarity index 100% rename from docs/guides/global-data-quantum-optimizer.ipynb rename to docs/functions/application-functions/global-data-quantum-optimizer.ipynb diff --git a/docs/guides/kipu-optimization.ipynb b/docs/functions/application-functions/kipu-optimization.ipynb similarity index 100% rename from docs/guides/kipu-optimization.ipynb rename to docs/functions/application-functions/kipu-optimization.ipynb diff --git a/docs/guides/multiverse-computing-singularity.ipynb b/docs/functions/application-functions/multiverse-computing-singularity.ipynb similarity index 100% rename from docs/guides/multiverse-computing-singularity.ipynb rename to docs/functions/application-functions/multiverse-computing-singularity.ipynb diff --git a/docs/guides/q-ctrl-optimization-solver.ipynb b/docs/functions/application-functions/q-ctrl-optimization-solver.ipynb similarity index 100% rename from docs/guides/q-ctrl-optimization-solver.ipynb rename to docs/functions/application-functions/q-ctrl-optimization-solver.ipynb diff --git a/docs/guides/qunova-chemistry.ipynb b/docs/functions/application-functions/qunova-chemistry.ipynb similarity index 100% rename from docs/guides/qunova-chemistry.ipynb rename to docs/functions/application-functions/qunova-chemistry.ipynb diff --git a/docs/guides/algorithmiq-tem.ipynb b/docs/functions/circuit-functions/algorithmiq-tem.ipynb similarity index 100% rename from docs/guides/algorithmiq-tem.ipynb rename to docs/functions/circuit-functions/algorithmiq-tem.ipynb diff --git a/docs/guides/q-ctrl-performance-management.ipynb b/docs/functions/circuit-functions/q-ctrl-performance-management.ipynb similarity index 100% rename from docs/guides/q-ctrl-performance-management.ipynb rename to docs/functions/circuit-functions/q-ctrl-performance-management.ipynb diff --git a/docs/guides/qedma-qesem.ipynb b/docs/functions/circuit-functions/qedma-qesem.ipynb similarity index 100% rename from docs/guides/qedma-qesem.ipynb rename to docs/functions/circuit-functions/qedma-qesem.ipynb diff --git a/docs/guides/function-template-chemistry-workflow.ipynb b/docs/functions/function-templates/function-template-chemistry-workflow.ipynb similarity index 100% rename from docs/guides/function-template-chemistry-workflow.ipynb rename to docs/functions/function-templates/function-template-chemistry-workflow.ipynb diff --git a/docs/guides/function-template-hamiltonian-simulation.ipynb b/docs/functions/function-templates/function-template-hamiltonian-simulation.ipynb similarity index 100% rename from docs/guides/function-template-hamiltonian-simulation.ipynb rename to docs/functions/function-templates/function-template-hamiltonian-simulation.ipynb diff --git a/docs/guides/qiskit-function-templates.mdx b/docs/functions/function-templates/qiskit-function-templates.mdx similarity index 100% rename from docs/guides/qiskit-function-templates.mdx rename to docs/functions/function-templates/qiskit-function-templates.mdx diff --git a/docs/guides/functions.ipynb b/docs/functions/get-started.ipynb similarity index 52% rename from docs/guides/functions.ipynb rename to docs/functions/get-started.ipynb index d273f123aa0c..26043c4c1f00 100644 --- a/docs/guides/functions.ipynb +++ b/docs/functions/get-started.ipynb @@ -2,98 +2,9 @@ "cells": [ { "cell_type": "markdown", - "id": "2ee21f3f-2a40-486f-9721-d8a358a87aa1", + "id": "88919905", "metadata": {}, "source": [ - "---\n", - "title: Introduction to Qiskit Functions\n", - "description: Explore IBM Qiskit Functions Catalog, abstracted circuit function and application function services designed to accelerate research and application prototyping.\n", - "---\n", - "\n", - "\n", - "{/* cspell:ignore Jarman, HIVQE, Cadavid, Chandarana, Leclerc, Sachdeva, HUBO, Filippov, Downfolding, Aharonov, Mundada, Yamauchi, supersymmetric, Paterakis, Gharibyan, Jaffali, Pellow */}" - ] - }, - { - "cell_type": "markdown", - "id": "97b94d47-ba58-4251-91f2-93097e50f2c9", - "metadata": {}, - "source": [ - "# Introduction to Qiskit Functions\n", - "\n", - "* Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "a4c425ca-c6c6-4232-b4b9-b2a365d10ad9", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [ - "\n", - "\n", - "\n", - "The code on this page was developed using the following requirements.\n", - "We recommend using these versions or newer.\n", - "\n", - "```\n", - "qiskit[all]~=1.4.1\n", - "qiskit-ibm-runtime~=0.37.0\n", - "qiskit-ibm-catalog~=0.4\n", - "```\n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "1fe03d0f-c7bb-439b-b98e-91ca400b62fc", - "metadata": {}, - "source": [ - "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.\n", - "\n", - "![Overview of Qiskit Functions](/docs/images/guides/functions/functions-overview.svg)\n", - "Functions come in two forms:\n", - "\n", - "| Type | What does it do? | Example inputs and outputs | Who is it for? |\n", - "| - | - | - | - |\n", - "| Circuit function | Simplified interface for running circuits. Abstracts transpilation, error suppression, and error mitigation | **Input**: Abstract `PUB` objects
**Output**: Mitigated expectation values | Researchers using Qiskit to discover new algorithms and applications, without needing to focus on optimizing for hardware or handling error. Circuit functions can be used to build custom application functions. |\n", - "| Application function | Covers higher-level tasks, such as exploring algorithms and domain-specific use cases. Abstracts quantum workflow to solve tasks, with classical inputs and outputs | **Input**: Molecules, graphs
**Output**: Ground + excited state energy, optimal values for cost function | Researchers in non-quantum domains, integrating quantum into existing large-scale classical workflows, without needing to map classical data to quantum circuits. |" - ] - }, - { - "cell_type": "markdown", - "id": "5e5b0531-f286-4573-8b1e-664ca5496d2d", - "metadata": {}, - "source": [ - "Functions are provided by IBM® and third-party partners. Each is performant for specific workload characteristics and has unique performance-tuning options.\n", - "\n", - "## Overview of available functions\n", - "\n", - "\n", - "### Circuit functions\n", - "\n", - "| Name | Provider | Recommended use | Unique benefits |\n", - "|---|---|---|---|\n", - "| Tensor-Network Error Mitigation

| Algorithmiq | Workloads that have low-weight observables and loop-free circuits. | Reduces measurement overhead and variance, outperforming standard error mitigation baselines such as Zero Noise Extrapolation (ZNE) and Probabilistic Error Cancellation (PEC) for relevant circuit classes. |\n", - "| QESEM: Error Suppression and Error Mitigation

| Qedma | Workloads that include circuits with fractional or parameterized gates, high-weight observables, and workflows that require unbiased expectation values and accurate runtime estimates. | Produces unbiased expectation values with lower variance and resource overhead, outperforming ZNE and PEC for relevant circuit classes. |\n", - "| Performance Management

| Q-CTRL | Workloads that contain parametric circuits, deep circuits, or require many circuit executions. | Automatically applies AI-driven error suppression to quantum algorithms, maximizing the performance of IBM devices to deliver accurate results while reducing the number of shots, compute time, and cost required.

Zero-overhead method that improves execution accuracy for the Sampler and the Estimator primitives, compatible with any weight of observables. |\n", - "\n", - "\n", - "### Application functions\n", - "\n", - "| Name | Provider | Recommended use | Unique benefits |\n", - "|---|---|---|---|\n", - "| QUICK-PDE

| ColibriTD | Use quantum computation for multi-physics PDEs.

Prepare simulation workflows for quantum hardware, while keeping full control over both quantum and physical modeling parameters. | Offers a robust hybrid VQA framework that delivers precise, scalable PDE solutions through advanced solution encoding and spectral methods, making it an ideal entry point for teams trying to build quantum-ready simulation capabilities. |\n", - "| Quantum Portfolio Optimizer

| Global Data Quantum | Workloads for financial optimization, seeking optimal portfolio strategies over time while minimizing risk and maximizing returns, enabling trading strategy back-testing. | Solves combinatorial optimization problems through a highly specialized adaptation of the VQE quantum algorithm for this financial use case, using optimized execution strategies and optimizers, along with noise-aware error mitigation techniques tailored to portfolio optimization. |\n", - "| HI-VQE Chemistry

| Qunova Computing | Workloads in computational chemistry, molecular simulation, materials science, or any Hamiltonian simulation that require solving many-body electronic structure problems. | Solves molecular electronic structures by using enhanced SQD with achieving chemical accuracy (1 kcal/mol, 1.6 mHa) for problems modeled with 40 to 60 qubits, outperforming some classical solutions on supercomputers or standard SQD in convergence speed or accuracy, respectively, by orders of magnitude. |\n", - "| Iskay Quantum Optimizer

| Kipu Quantum | Optimization workloads such as scheduling, logistics, routing, and QUBO/HUBO problems.

| Integrated tunable classical pre- and post-processing methods for the quantum optimization routine.

Delivers runtime advantage over classical solvers (CPLEX, simulated annealing, and tabu search) on selected HUBO benchmarks.

Market Split `ms_5_100`, a hard challenge, solved within hours (see [this tutorial](/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer)). |\n", - "| Singularity Machine Learning

| Multiverse Computing | Classical machine learning classification workflows that could benefit from improved accuracy or computational efficiency by leveraging quantum optimization executed on IBM hardware. | Delivers accuracy comparable to or exceeding classical models such as Random Forest or XGBoost, while operating with significantly fewer learners and a more compact ensemble.

Powered by quantum-optimized voting, it selects the most informative learners and refines decision boundaries, resulting in greater efficiency, reduced model complexity, and more robust performance. |\n", - "| Optimization Solver

| Q-CTRL | Binary optimization problems or any combinatorial problem that can be mapped to a binary cost function.

Cost functions of any order and problem sizes up to the maximum device scale are supported. | Noise-aware, end-to-end quantum optimization solution that enables inputs of high-level problem definitions and automatically finds accurate solutions to classically challenging combinatorial problems on utility-scale quantum hardware.

It abstracts away complexity by handling error suppression, efficient mapping, and hybrid quantum-classical optimization to solve optimization tasks at full device scale without deep quantum expertise. |\n", "\n", "## Get started with Qiskit Functions\n", "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.\n", @@ -140,8 +51,8 @@ }, { "cell_type": "code", - "execution_count": 1, - "id": "6699700c-ae26-4c10-8d09-05ee77a1afb7", + "execution_count": null, + "id": "5f0740c6", "metadata": {}, "outputs": [], "source": [ @@ -153,7 +64,7 @@ }, { "cell_type": "markdown", - "id": "a00d2d76-dfbe-4a92-be82-8dea393ff12a", + "id": "59fadf85", "metadata": {}, "source": [ "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](https://cloud.ibm.com/iam/apikeys) page to reduce risk. Learn more in the [Managing user API keys](https://cloud.ibm.com/docs/account?topic=account-userapikey&interface=ui) topic. To initialize the service in this situation, expand the following section to view code you can use:\n", @@ -173,7 +84,7 @@ }, { "cell_type": "markdown", - "id": "374939e2-54ac-4b72-92df-19a5fe9ec352", + "id": "42652fd3", "metadata": {}, "source": [ " \n", @@ -185,7 +96,7 @@ }, { "cell_type": "markdown", - "id": "e3cada45-0364-4096-8481-6eb99d43c656", + "id": "4956d025", "metadata": {}, "source": [ "4. After you have authenticated, you can list the functions from the Qiskit Functions Catalog that you have access to:" @@ -193,8 +104,8 @@ }, { "cell_type": "code", - "execution_count": 2, - "id": "275b4b94-7656-403e-8997-941c03c7ef55", + "execution_count": null, + "id": "c16abc02", "metadata": {}, "outputs": [ { @@ -212,9 +123,8 @@ " QiskitFunction(kipu-quantum/iskay-quantum-optimizer)]" ] }, - "execution_count": 2, "metadata": {}, - "output_type": "execute_result" + "output_type": "display_data" } ], "source": [ @@ -223,7 +133,7 @@ }, { "cell_type": "markdown", - "id": "de09ad8c-bd6d-4a02-8b24-7bb73beca811", + "id": "885ae29d", "metadata": {}, "source": [ "### Run enabled functions\n", @@ -233,8 +143,8 @@ }, { "cell_type": "code", - "execution_count": 3, - "id": "65a26da5-f537-44ed-9cb4-b335518d009d", + "execution_count": null, + "id": "e457173d", "metadata": {}, "outputs": [], "source": [ @@ -243,7 +153,7 @@ }, { "cell_type": "markdown", - "id": "0a5f87e4-3082-4ec5-a7ae-7ddb5c35632a", + "id": "0f73ff7f", "metadata": {}, "source": [ "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:" @@ -251,14 +161,9 @@ }, { "cell_type": "code", - "execution_count": 4, - "id": "139ac1d5-3727-4f44-a26c-0d8a1d8a58f2", - "metadata": { - "scrolled": true, - "tags": [ - "remove-cell" - ] - }, + "execution_count": null, + "id": "9020abfe", + "metadata": {}, "outputs": [], "source": [ "# This cell is hidden from users\n", @@ -276,8 +181,8 @@ }, { "cell_type": "code", - "execution_count": 5, - "id": "9b9a7a3c-cc98-4c19-93cd-f59793515c70", + "execution_count": null, + "id": "571d1c6c", "metadata": {}, "outputs": [ { @@ -286,9 +191,8 @@ "'7f08c9d5-471b-4da2-92e7-4f2cb94c23a8'" ] }, - "execution_count": 5, "metadata": {}, - "output_type": "execute_result" + "output_type": "display_data" } ], "source": [ @@ -303,7 +207,7 @@ }, { "cell_type": "markdown", - "id": "113d4382-a987-492d-9e12-b66d3b955bc4", + "id": "f238416c", "metadata": {}, "source": [ "### Check job status\n", @@ -329,8 +233,8 @@ }, { "cell_type": "code", - "execution_count": 6, - "id": "d0574d73-0966-4426-b2f5-94df72a07caa", + "execution_count": null, + "id": "47a08c71", "metadata": {}, "outputs": [ { @@ -339,9 +243,8 @@ "'QUEUED'" ] }, - "execution_count": 6, "metadata": {}, - "output_type": "execute_result" + "output_type": "display_data" } ], "source": [ @@ -350,7 +253,7 @@ }, { "cell_type": "markdown", - "id": "439fbefc-f7d3-4e6e-b3e6-61a3664ac5e9", + "id": "0c246c35", "metadata": {}, "source": [ "### Retrieve results\n", @@ -360,8 +263,8 @@ }, { "cell_type": "code", - "execution_count": 7, - "id": "45e302d8-f3c2-4868-8b7c-6d451f6119a9", + "execution_count": null, + "id": "f2912d82", "metadata": {}, "outputs": [ { @@ -379,7 +282,7 @@ }, { "cell_type": "markdown", - "id": "d809d8fa-479c-4c3b-81d7-3408925cec68", + "id": "b3adf22f", "metadata": {}, "source": [ "You can also cancel a job at any time:" @@ -387,8 +290,8 @@ }, { "cell_type": "code", - "execution_count": 8, - "id": "0e55d4d6-4680-4671-907f-35aac16971ef", + "execution_count": null, + "id": "6090afcc", "metadata": {}, "outputs": [ { @@ -397,9 +300,8 @@ "'Job has been stopped.'" ] }, - "execution_count": 8, "metadata": {}, - "output_type": "execute_result" + "output_type": "display_data" } ], "source": [ @@ -408,7 +310,7 @@ }, { "cell_type": "markdown", - "id": "1ef980bc-9030-4f8a-84d6-a0abd15923ac", + "id": "2fab74e8", "metadata": {}, "source": [ "### List previously run jobs run with Qiskit Functions\n", @@ -418,8 +320,8 @@ }, { "cell_type": "code", - "execution_count": 9, - "id": "4becfe13-68dd-481d-bb43-fc502c254623", + "execution_count": null, + "id": "0f0ff343", "metadata": {}, "outputs": [ { @@ -437,9 +339,8 @@ " ]" ] }, - "execution_count": 9, "metadata": {}, - "output_type": "execute_result" + "output_type": "display_data" } ], "source": [ @@ -449,7 +350,7 @@ }, { "cell_type": "markdown", - "id": "af7fa72a-f272-43ff-800d-5ae37dd42b2b", + "id": "3506af96", "metadata": {}, "source": [ "If you already have the job ID for a certain job, you can retrieve the job with `catalog.get_job_by_id()`:" @@ -457,8 +358,8 @@ }, { "cell_type": "code", - "execution_count": 18, - "id": "18d87f07-8a8e-4b93-80d0-7c07e49272e2", + "execution_count": null, + "id": "cfe768a5", "metadata": {}, "outputs": [ { @@ -485,7 +386,7 @@ }, { "cell_type": "markdown", - "id": "e15f89f8-925d-4d13-8fb8-80ad1d8ac7f6", + "id": "b7d666a2", "metadata": {}, "source": [ "### Fetch error messages\n", @@ -495,8 +396,8 @@ }, { "cell_type": "code", - "execution_count": 1, - "id": "68412b66-8022-4dd3-b140-ec33e119693b", + "execution_count": null, + "id": "593ddf1d", "metadata": {}, "outputs": [ { @@ -510,43 +411,13 @@ "source": [ "job.error_message()" ] - }, - { - "cell_type": "markdown", - "id": "709b39ca-5dbd-42c0-830c-1248c2e5d63c", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - "\n", - "- [Explore circuit functions](/docs/guides/algorithmiq-tem) to build new algorithms and applications, without needing to manage transpilation or error handling.\n", - "- [Explore application functions](/docs/guides/q-ctrl-optimization-solver) to solve domain-specific tasks, with classical inputs and outputs.\n", - "- See the [API reference documentation](/docs/api/functions/index) for Qiskit Functions.\n", - "- For hands-on experience, try out some [tutorials](/docs/tutorials/index#leverage-qiskit-capabilities) that demonstrate Qiskit Functions.\n", - "" - ] } ], "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3" + "name": "python" } }, "nbformat": 4, - "nbformat_minor": 4 + "nbformat_minor": 5 } diff --git a/docs/functions/index.ipynb b/docs/functions/index.ipynb new file mode 100644 index 000000000000..ea08514b9a0b --- /dev/null +++ b/docs/functions/index.ipynb @@ -0,0 +1,137 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "2ee21f3f-2a40-486f-9721-d8a358a87aa1", + "metadata": {}, + "source": [ + "---\n", + "title: Introduction to Qiskit Functions\n", + "description: Explore IBM Qiskit Functions Catalog, abstracted circuit function and application function services designed to accelerate research and application prototyping.\n", + "---\n", + "\n", + "\n", + "{/* cspell:ignore Jarman, HIVQE, Cadavid, Chandarana, Leclerc, Sachdeva, HUBO, Filippov, Downfolding, Aharonov, Mundada, Yamauchi, supersymmetric, Paterakis, Gharibyan, Jaffali, Pellow */}" + ] + }, + { + "cell_type": "markdown", + "id": "97b94d47-ba58-4251-91f2-93097e50f2c9", + "metadata": {}, + "source": [ + "# Introduction to Qiskit Functions\n", + "\n", + "* Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "a4c425ca-c6c6-4232-b4b9-b2a365d10ad9", + "metadata": { + "tags": [ + "version-info" + ] + }, + "source": [ + "\n", + "\n", + "\n", + "The code on this page was developed using the following requirements.\n", + "We recommend using these versions or newer.\n", + "\n", + "```\n", + "qiskit[all]~=1.4.1\n", + "qiskit-ibm-runtime~=0.37.0\n", + "qiskit-ibm-catalog~=0.4\n", + "```\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "1fe03d0f-c7bb-439b-b98e-91ca400b62fc", + "metadata": {}, + "source": [ + "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.\n", + "\n", + "![Overview of Qiskit Functions](/docs/images/guides/functions/functions-overview.svg)\n", + "Functions come in two forms:\n", + "\n", + "| Type | What does it do? | Example inputs and outputs | Who is it for? |\n", + "| - | - | - | - |\n", + "| Circuit function | Simplified interface for running circuits. Abstracts transpilation, error suppression, and error mitigation | **Input**: Abstract `PUB` objects
**Output**: Mitigated expectation values | Researchers using Qiskit to discover new algorithms and applications, without needing to focus on optimizing for hardware or handling error. Circuit functions can be used to build custom application functions. |\n", + "| Application function | Covers higher-level tasks, such as exploring algorithms and domain-specific use cases. Abstracts quantum workflow to solve tasks, with classical inputs and outputs | **Input**: Molecules, graphs
**Output**: Ground + excited state energy, optimal values for cost function | Researchers in non-quantum domains, integrating quantum into existing large-scale classical workflows, without needing to map classical data to quantum circuits. |" + ] + }, + { + "cell_type": "markdown", + "id": "5e5b0531-f286-4573-8b1e-664ca5496d2d", + "metadata": {}, + "source": [ + "Functions are provided by IBM® and third-party partners. Each is performant for specific workload characteristics and has unique performance-tuning options.\n", + "\n", + "## Overview of available functions\n", + "\n", + "\n", + "### Circuit functions\n", + "\n", + "| Name | Provider | Recommended use | Unique benefits |\n", + "|---|---|---|---|\n", + "| Tensor-Network Error Mitigation

| Algorithmiq | Workloads that have low-weight observables and loop-free circuits. | Reduces measurement overhead and variance, outperforming standard error mitigation baselines such as Zero Noise Extrapolation (ZNE) and Probabilistic Error Cancellation (PEC) for relevant circuit classes. |\n", + "| QESEM: Error Suppression and Error Mitigation

| Qedma | Workloads that include circuits with fractional or parameterized gates, high-weight observables, and workflows that require unbiased expectation values and accurate runtime estimates. | Produces unbiased expectation values with lower variance and resource overhead, outperforming ZNE and PEC for relevant circuit classes. |\n", + "| Performance Management

| Q-CTRL | Workloads that contain parametric circuits, deep circuits, or require many circuit executions. | Automatically applies AI-driven error suppression to quantum algorithms, maximizing the performance of IBM devices to deliver accurate results while reducing the number of shots, compute time, and cost required.

Zero-overhead method that improves execution accuracy for the Sampler and the Estimator primitives, compatible with any weight of observables. |\n", + "\n", + "\n", + "### Application functions\n", + "\n", + "| Name | Provider | Recommended use | Unique benefits |\n", + "|---|---|---|---|\n", + "| QUICK-PDE

| ColibriTD | Use quantum computation for multi-physics PDEs.

Prepare simulation workflows for quantum hardware, while keeping full control over both quantum and physical modeling parameters. | Offers a robust hybrid VQA framework that delivers precise, scalable PDE solutions through advanced solution encoding and spectral methods, making it an ideal entry point for teams trying to build quantum-ready simulation capabilities. |\n", + "| Quantum Portfolio Optimizer

| Global Data Quantum | Workloads for financial optimization, seeking optimal portfolio strategies over time while minimizing risk and maximizing returns, enabling trading strategy back-testing. | Solves combinatorial optimization problems through a highly specialized adaptation of the VQE quantum algorithm for this financial use case, using optimized execution strategies and optimizers, along with noise-aware error mitigation techniques tailored to portfolio optimization. |\n", + "| HI-VQE Chemistry

| Qunova Computing | Workloads in computational chemistry, molecular simulation, materials science, or any Hamiltonian simulation that require solving many-body electronic structure problems. | Solves molecular electronic structures by using enhanced SQD with achieving chemical accuracy (1 kcal/mol, 1.6 mHa) for problems modeled with 40 to 60 qubits, outperforming some classical solutions on supercomputers or standard SQD in convergence speed or accuracy, respectively, by orders of magnitude. |\n", + "| Iskay Quantum Optimizer

| Kipu Quantum | Optimization workloads such as scheduling, logistics, routing, and QUBO/HUBO problems.

| Integrated tunable classical pre- and post-processing methods for the quantum optimization routine.

Delivers runtime advantage over classical solvers (CPLEX, simulated annealing, and tabu search) on selected HUBO benchmarks.

Market Split `ms_5_100`, a hard challenge, solved within hours (see [this tutorial](/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer)). |\n", + "| Singularity Machine Learning

| Multiverse Computing | Classical machine learning classification workflows that could benefit from improved accuracy or computational efficiency by leveraging quantum optimization executed on IBM hardware. | Delivers accuracy comparable to or exceeding classical models such as Random Forest or XGBoost, while operating with significantly fewer learners and a more compact ensemble.

Powered by quantum-optimized voting, it selects the most informative learners and refines decision boundaries, resulting in greater efficiency, reduced model complexity, and more robust performance. |\n", + "| Optimization Solver

| Q-CTRL | Binary optimization problems or any combinatorial problem that can be mapped to a binary cost function.

Cost functions of any order and problem sizes up to the maximum device scale are supported. | Noise-aware, end-to-end quantum optimization solution that enables inputs of high-level problem definitions and automatically finds accurate solutions to classically challenging combinatorial problems on utility-scale quantum hardware.

It abstracts away complexity by handling error suppression, efficient mapping, and hybrid quantum-classical optimization to solve optimization tasks at full device scale without deep quantum expertise. |\n" + ] + }, + { + "cell_type": "markdown", + "id": "709b39ca-5dbd-42c0-830c-1248c2e5d63c", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + "\n", + "- [Explore circuit functions](/docs/guides/algorithmiq-tem) to build new algorithms and applications, without needing to manage transpilation or error handling.\n", + "- [Explore application functions](/docs/guides/q-ctrl-optimization-solver) to solve domain-specific tasks, with classical inputs and outputs.\n", + "- See the [API reference documentation](/docs/api/functions/index) for Qiskit Functions.\n", + "- For hands-on experience, try out some [tutorials](/docs/tutorials/index#leverage-qiskit-capabilities) that demonstrate Qiskit Functions.\n", + "" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} From 87eef02eaafe242ef49a89cf60876fa9dc48afb2 Mon Sep 17 00:00:00 2001 From: Sanket Panda Date: Thu, 25 Jun 2026 16:12:20 -0400 Subject: [PATCH 2/2] Prototyping with multiple microsites --- docs/functions/_toc.json | 144 +--- docs/functions/algorithmiq-tem/_toc.json | 50 ++ docs/functions/algorithmiq-tem/changelog.mdx | 6 + .../algorithmiq-tem/get-started.ipynb | 168 +++++ .../index.ipynb} | 144 +--- .../algorithmiq-tem/performance-tuning.mdx | 28 + .../kipu-optimization.ipynb | 650 ------------------ docs/functions/colibritd-pde/_toc.json | 50 ++ docs/functions/colibritd-pde/changelog.mdx | 6 + .../functions/colibritd-pde/get-started.ipynb | 272 ++++++++ .../index.ipynb} | 253 ------- .../colibritd-pde/performance-tuning.mdx | 26 + .../global-data-quantum-optimizer/_toc.json | 50 ++ .../changelog.mdx | 6 + .../get-started.ipynb} | 158 +---- .../global-data-quantum-optimizer/index.ipynb | 173 +++++ .../performance-tuning.mdx | 28 + docs/functions/index.ipynb | 137 ---- docs/functions/kipu-optimization/_toc.json | 50 ++ .../functions/kipu-optimization/changelog.mdx | 6 + .../kipu-optimization/get-started.ipynb | 448 ++++++++++++ docs/functions/kipu-optimization/index.ipynb | 189 +++++ .../performance-tuning.ipynb | 71 ++ .../_toc.json | 50 ++ .../changelog.mdx | 48 ++ .../get-started.ipynb} | 207 +----- .../index.ipynb | 174 +++++ .../performance-tuning.mdx | 24 + .../q-ctrl-optimization-solver/_toc.json | 54 ++ .../q-ctrl-optimization-solver/changelog.mdx | 6 + .../get-started.ipynb} | 171 +---- .../q-ctrl-optimization-solver/index.ipynb | 183 +++++ .../performance-tuning.mdx | 24 + .../q-ctrl-performance-management/_toc.json | 50 ++ .../changelog.mdx | 7 + .../get-started.ipynb} | 186 +---- .../q-ctrl-performance-management/index.ipynb | 191 +++++ .../performance-tuning.mdx | 25 + docs/functions/qedma-qesem/_toc.json | 50 ++ docs/functions/qedma-qesem/changelog.mdx | 6 + docs/functions/qedma-qesem/get-started.ipynb | 242 +++++++ .../index.ipynb} | 223 ------ .../qedma-qesem/performance-tuning.mdx | 22 + docs/functions/qunova-chemistry/_toc.json | 50 ++ docs/functions/qunova-chemistry/changelog.mdx | 6 + .../qunova-chemistry/get-started.ipynb | 261 +++++++ .../index.ipynb} | 347 +--------- .../qunova-chemistry/performance-tuning.ipynb | 141 ++++ docs/guides/_toc.json | 74 +- docs/{ => guides}/functions/get-started.ipynb | 97 +-- docs/guides/functions/index.mdx | 131 ++++ docs/guides/serverless-first-program.ipynb | 28 +- docs/guides/serverless-manage-resources.ipynb | 22 +- docs/guides/serverless-port-code.ipynb | 16 +- .../serverless-run-first-workload.ipynb | 26 +- docs/guides/serverless.mdx | 26 +- 56 files changed, 3515 insertions(+), 2766 deletions(-) create mode 100644 docs/functions/algorithmiq-tem/_toc.json create mode 100644 docs/functions/algorithmiq-tem/changelog.mdx create mode 100644 docs/functions/algorithmiq-tem/get-started.ipynb rename docs/functions/{circuit-functions/algorithmiq-tem.ipynb => algorithmiq-tem/index.ipynb} (70%) create mode 100644 docs/functions/algorithmiq-tem/performance-tuning.mdx delete mode 100644 docs/functions/application-functions/kipu-optimization.ipynb create mode 100644 docs/functions/colibritd-pde/_toc.json create mode 100644 docs/functions/colibritd-pde/changelog.mdx create mode 100644 docs/functions/colibritd-pde/get-started.ipynb rename docs/functions/{application-functions/colibritd-pde.ipynb => colibritd-pde/index.ipynb} (53%) create mode 100644 docs/functions/colibritd-pde/performance-tuning.mdx create mode 100644 docs/functions/global-data-quantum-optimizer/_toc.json create mode 100644 docs/functions/global-data-quantum-optimizer/changelog.mdx rename docs/functions/{application-functions/global-data-quantum-optimizer.ipynb => global-data-quantum-optimizer/get-started.ipynb} (65%) create mode 100644 docs/functions/global-data-quantum-optimizer/index.ipynb create mode 100644 docs/functions/global-data-quantum-optimizer/performance-tuning.mdx delete mode 100644 docs/functions/index.ipynb create mode 100644 docs/functions/kipu-optimization/_toc.json create mode 100644 docs/functions/kipu-optimization/changelog.mdx create mode 100644 docs/functions/kipu-optimization/get-started.ipynb create mode 100644 docs/functions/kipu-optimization/index.ipynb create mode 100644 docs/functions/kipu-optimization/performance-tuning.ipynb create mode 100644 docs/functions/multiverse-computing-singularity/_toc.json create mode 100644 docs/functions/multiverse-computing-singularity/changelog.mdx rename docs/functions/{application-functions/multiverse-computing-singularity.ipynb => multiverse-computing-singularity/get-started.ipynb} (58%) create mode 100644 docs/functions/multiverse-computing-singularity/index.ipynb create mode 100644 docs/functions/multiverse-computing-singularity/performance-tuning.mdx create mode 100644 docs/functions/q-ctrl-optimization-solver/_toc.json create mode 100644 docs/functions/q-ctrl-optimization-solver/changelog.mdx rename docs/functions/{application-functions/q-ctrl-optimization-solver.ipynb => q-ctrl-optimization-solver/get-started.ipynb} (55%) create mode 100644 docs/functions/q-ctrl-optimization-solver/index.ipynb create mode 100644 docs/functions/q-ctrl-optimization-solver/performance-tuning.mdx create mode 100644 docs/functions/q-ctrl-performance-management/_toc.json create mode 100644 docs/functions/q-ctrl-performance-management/changelog.mdx rename docs/functions/{circuit-functions/q-ctrl-performance-management.ipynb => q-ctrl-performance-management/get-started.ipynb} (98%) create mode 100644 docs/functions/q-ctrl-performance-management/index.ipynb create mode 100644 docs/functions/q-ctrl-performance-management/performance-tuning.mdx create mode 100644 docs/functions/qedma-qesem/_toc.json create mode 100644 docs/functions/qedma-qesem/changelog.mdx create mode 100644 docs/functions/qedma-qesem/get-started.ipynb rename docs/functions/{circuit-functions/qedma-qesem.ipynb => qedma-qesem/index.ipynb} (69%) create mode 100644 docs/functions/qedma-qesem/performance-tuning.mdx create mode 100644 docs/functions/qunova-chemistry/_toc.json create mode 100644 docs/functions/qunova-chemistry/changelog.mdx create mode 100644 docs/functions/qunova-chemistry/get-started.ipynb rename docs/functions/{application-functions/qunova-chemistry.ipynb => qunova-chemistry/index.ipynb} (57%) create mode 100644 docs/functions/qunova-chemistry/performance-tuning.ipynb rename docs/{ => guides}/functions/get-started.ipynb (64%) create mode 100644 docs/guides/functions/index.mdx diff --git a/docs/functions/_toc.json b/docs/functions/_toc.json index 70ddf72f96cb..6bd96176eafe 100644 --- a/docs/functions/_toc.json +++ b/docs/functions/_toc.json @@ -1,151 +1,41 @@ { "parentUrl": "/docs/guides", - "parentLabel": "Documentation", + "parentLabel": "Guides", "title": "Qiskit Functions", "collapsed": true, "children": [ { - "title": "", + "title": "Applications research tools", + "collapsible": false, "children": [ + { "title": "Introduction to Qiskit Functions", "url": "/docs/guides/functions" }, + { "title": "Getting Started with Qiskit Functions", "url": "/docs/guides/functions/get-started" }, { - "title": "Overview", - "url": "/docs/functions" - }, - { - "title": "Get started with functions", - "url": "/docs/functions/get-started" - }, - { - "title": "Circuit functions", + "title": "Custom Functions", "children": [ - { - "title": "Algorithmiq Tensor-network error mitigation", - "url": "/docs/functions/circuit-functions/algorithmiq-tem" - }, - { - "title": "Q-CTRL Performance Management", - "url": "/docs/functions/circuit-functions/q-ctrl-performance-management" - }, - { - "title": "Qedma QESEM", - "url": "/docs/functions/circuit-functions/qedma-qesem" - } - ] - }, - { - "title": "Application functions", - "children": [ - { - "title": "Kipu Quantum Iskay Quantum Optimizer", - "url": "/docs/functions/application-functions/kipu-optimization" - }, - { - "title": "Multiverse Computing Singularity", - "url": "/docs/functions/application-functions/multiverse-computing-singularity" - }, - { - "title": "Q-CTRL Optimization Solver", - "url": "/docs/functions/application-functions/q-ctrl-optimization-solver" - }, - { - "title": "Quantum Portfolio Optimizer: A Qiskit Function by Global Data Quantum", - "url": "/docs/functions/application-functions/global-data-quantum-optimizer" - }, - { - "title": "QUICK-PDE: A Qiskit Function by ColibriTD", - "url": "/docs/functions/application-functions/colibritd-pde" - }, - { - "title": "Qunova Computing HI-VQE Chemistry", - "url": "/docs/functions/application-functions/qunova-chemistry" - } + { "title": "Introduction to custom functions", "url": "/docs/guides/serverless" }, + { "title": "Write your first custom function", "url": "/docs/guides/serverless-first-program" }, + { "title": "Run your first custom function remotely", "url": "/docs/guides/serverless-run-first-workload" }, + { "title": "Manage custom function compute and data resources", "url": "/docs/guides/serverless-manage-resources" }, + { "title": "Port code to custom functions", "url": "/docs/guides/serverless-port-code" } ] }, { "title": "Qiskit Function templates", "children": [ - { - "title": "Introduction to Qiskit Function templates", - "url": "/docs/functions/function-templates/qiskit-function-templates" - }, - { - "title": "Template for chemistry simulation", - "url": "/docs/functions/function-templates/function-template-chemistry-workflow" - }, - { - "title": "Template for Hamiltonian simulation", - "url": "/docs/functions/function-templates/function-template-hamiltonian-simulation" - } - ] - } - ], - "collapsible": false - }, - { - "title": "Tutorials", - "collapsible": false, - "children": [ - { - "title": "Circuit function tutorials", - "children": [ - { - "title": "Transverse-Field Ising Model with Q-CTRL's Performance Management", - "url": "/docs/tutorials/transverse-field-ising-model" - }, - { - "title": "Simulate 2D tilted-field Ising with the QESEM function", - "url": "/docs/tutorials/qedma-2d-ising-with-qesem" - }, - { - "title": "Simulate a kicked Ising model with the TEM function", - "url": "/docs/tutorials/simulate-kicked-ising-tem" - } + { "title": "Introduction to Qiskit Function templates", "url": "/docs/functions/function-templates/qiskit-function-templates" }, + { "title": "Template for chemistry simulation", "url": "/docs/functions/function-templates/function-template-chemistry-workflow" }, + { "title": "Template for Hamiltonian simulation", "url": "/docs/functions/function-templates/function-template-hamiltonian-simulation" } ] }, { - "title": "Application function tutorials", + "title": "Sample-based quantum diagonalization (SQD)", "children": [ - { - "title": "Dynamic portfolio optimization with Global Data Quantum's Portfolio Optimizer", - "url": "/docs/tutorials/global-data-quantum-optimizer" - }, - { - "title": "Higher-order binary optimization with Q-CTRL's Optimization Solver", - "url": "/docs/tutorials/solve-higher-order-binary-optimization-problems-with-q-ctrls-optimization-solver" - }, - { - "title": "Model a flowing non-viscous fluid using QUICK-PDE", - "url": "/docs/tutorials/colibritd-pde" - }, - { - "title": "Dissociation PES curves with Qunova HiVQE", - "url": "/docs/tutorials/qunova-hivqe" - }, - { - "title": "Quantum Phase Estimation with Q-CTRL's Qiskit Functions", - "url": "/docs/tutorials/quantum-phase-estimation-qctrl" - }, - { - "title": "Solve the Market Split problem with Kipu Quantum's Iskay Quantum Optimizer", - "url": "/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer" - }, - { - "title": "Hybrid quantum-enhanced ensemble classification (grid stability workflow)", - "url": "/docs/tutorials/sml-classification" - } + { "title": "SQD addon overview", "url": "/docs/guides/qiskit-addons-sqd" }, + { "title": "Get started with SQD", "url": "/docs/guides/qiskit-addons-sqd-get-started" } ] } ] - }, - { - "title": "API reference", - "collapsible": false, - "children": [ - { - "title": "Python API reference", - "url": "/docs/api/functions" - } - ] } ] } diff --git a/docs/functions/algorithmiq-tem/_toc.json b/docs/functions/algorithmiq-tem/_toc.json new file mode 100644 index 000000000000..269ad50f9907 --- /dev/null +++ b/docs/functions/algorithmiq-tem/_toc.json @@ -0,0 +1,50 @@ +{ + "parentUrl": "/docs/guides/functions", + "parentLabel": "Qiskit Functions", + "title": "Algorithmiq Tensor-network error mitigation (TEM)", + "collapsed": true, + "children": [ + { + "title": "", + "collapsible": false, + "children": [ + { + "title": "Overview", + "url": "/docs/functions/algorithmiq-tem" + }, + { + "title": "Get started", + "url": "/docs/functions/algorithmiq-tem/get-started" + }, + { + "title": "Advanced techniques with Algorithmiq TEM", + "url": "/docs/functions/algorithmiq-tem/performance-tuning" + }, + { + "title": "Changelog", + "url": "/docs/functions/algorithmiq-tem/changelog" + } + ] + }, + { + "title": "Tutorials", + "collapsible": false, + "children": [ + { + "title": "Simulate a kicked Ising model with the TEM function", + "url": "/docs/tutorials/simulate-kicked-ising-tem" + } + ] + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "/docs/api/functions/algorithmiq-tem" + } + ] + } + ] +} diff --git a/docs/functions/algorithmiq-tem/changelog.mdx b/docs/functions/algorithmiq-tem/changelog.mdx new file mode 100644 index 000000000000..a5a82a09ab2d --- /dev/null +++ b/docs/functions/algorithmiq-tem/changelog.mdx @@ -0,0 +1,6 @@ +--- +title: Changelog +description: Changelog for the TEM Qiskit Function. +--- + +*This section is under development. Algorithmiq is encouraged to maintain a changelog here as new features and updates are released.* diff --git a/docs/functions/algorithmiq-tem/get-started.ipynb b/docs/functions/algorithmiq-tem/get-started.ipynb new file mode 100644 index 000000000000..fd320c8b5f9a --- /dev/null +++ b/docs/functions/algorithmiq-tem/get-started.ipynb @@ -0,0 +1,168 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "page-frontmatter", + "metadata": {}, + "source": [ + "---\ntitle: Get started with Algorithmiq TEM\ndescription: Get started with TEM — authenticate, load the function, and run an expectation value estimation example.\n---" + ] + }, + { + "cell_type": "markdown", + "id": "2995da29", + "metadata": {}, + "source": [ + "## Setup and load function\n\nAuthenticate using your [IBM Quantum Platform API key](http://quantum.cloud.ibm.com/), and select the TEM function as follows. (This snippet assumes you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment.)" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "cc0a8093", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", + "\n", + "tem_function_name = \"algorithmiq/tem\"\n", + "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n", + "\n", + "# Load your function\n", + "tem = catalog.load(tem_function_name)" + ] + }, + { + "cell_type": "markdown", + "id": "ae7adcc7", + "metadata": {}, + "source": [ + "## Run your first workload\n\n\nThe following snippet shows an example where TEM is used to compute the expectation values of an observable given a simple quantum circuit." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "ab05b87f", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit import QuantumCircuit\n", + "from qiskit.quantum_info import SparsePauliOp\n", + "\n", + "# Create a quantum circuit\n", + "qc = QuantumCircuit(3)\n", + "qc.u(0.4, 0.9, -0.3, 0)\n", + "qc.u(-0.4, 0.2, 1.3, 1)\n", + "qc.u(-1.2, -1.2, 0.3, 2)\n", + "for _ in range(2):\n", + " qc.barrier()\n", + " qc.cx(0, 1)\n", + " qc.cx(2, 1)\n", + " qc.barrier()\n", + " qc.u(0.4, 0.9, -0.3, 0)\n", + " qc.u(-0.4, 0.2, 1.3, 1)\n", + " qc.u(-1.2, -1.2, 0.3, 2)\n", + "\n", + "# Define the observables\n", + "observable = SparsePauliOp(\"IYX\", 1.0)\n", + "\n", + "# Define the execution options\n", + "pub = (qc, [observable])\n", + "options = {\"default_precision\": 0.02}\n", + "\n", + "# Define backend to use. TEM will choose the least-busy device\n", + "# reported by IBM if not specified\n", + "backend_name = \"ibm_marrakesh\"\n", + "\n", + "# Run the TEM function (uses around three minutes of QPU time)\n", + "job = tem.run(pubs=[pub], backend_name=backend_name, options=options)" + ] + }, + { + "cell_type": "markdown", + "id": "6e2a97e2", + "metadata": {}, + "source": [ + "Use the Qiskit Serverless APIs to check your Qiskit Function workload's status:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "47b0db71", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "QUEUED\n" + ] + } + ], + "source": [ + "print(job.status())" + ] + }, + { + "cell_type": "markdown", + "id": "fbaeace8", + "metadata": {}, + "source": [ + "You can return the results as:" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "ad5b9a53", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "0.02165380888171687\n" + ] + } + ], + "source": [ + "result = job.result()\n", + "evs = result[0].data.evs\n", + "print(evs[0])" + ] + }, + { + "cell_type": "markdown", + "id": "e5e138d3", + "metadata": {}, + "source": [ + "\n", + " The expected value for the noiseless circuit for the given operator should be around `0.18409094298943401`.\n", + "" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/functions/circuit-functions/algorithmiq-tem.ipynb b/docs/functions/algorithmiq-tem/index.ipynb similarity index 70% rename from docs/functions/circuit-functions/algorithmiq-tem.ipynb rename to docs/functions/algorithmiq-tem/index.ipynb index af71fbb847c8..838735c109c4 100644 --- a/docs/functions/circuit-functions/algorithmiq-tem.ipynb +++ b/docs/functions/algorithmiq-tem/index.ipynb @@ -10,7 +10,7 @@ "description: Introduction to TEM, a Qiskit Function by Algorithmiq, to compute estimations with software post-processing error mitigation using tensor networks.\n", "---\n", "\n", - "{/* cspell:ignore POVM, mathbf, Filippov, Lindblad, Leahy, Rossi, García, Pérez, Minev, Kandala, Temme, informationally */}" + "{/* cspell:ignore POVM, mathbf, Filippov, Lindblad, Leahy, Rossi, Garc\u00eda, P\u00e9rez, Minev, Kandala, Temme, informationally */}" ] }, { @@ -63,7 +63,7 @@ "source": [ "## Overview\n", "\n", - "Algorithmiq’s Tensor-network Error Mitigation (TEM) method is a hybrid\n", + "Algorithmiq\u2019s Tensor-network Error Mitigation (TEM) method is a hybrid\n", "quantum-classical algorithm designed for performing noise mitigation entirely at\n", "the classical post-processing stage. With TEM, the user can compute the\n", "expectation values of observables mitigating the inevitable noise-induced errors\n", @@ -144,146 +144,6 @@ "results." ] }, - { - "cell_type": "markdown", - "id": "2995da29", - "metadata": {}, - "source": [ - "## Get started\n", - "\n", - "Authenticate using your [IBM Quantum Platform API key](http://quantum.cloud.ibm.com/), and select the TEM function as follows. (This snippet assumes you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment.)" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "cc0a8093", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", - "\n", - "tem_function_name = \"algorithmiq/tem\"\n", - "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n", - "\n", - "# Load your function\n", - "tem = catalog.load(tem_function_name)" - ] - }, - { - "cell_type": "markdown", - "id": "ae7adcc7", - "metadata": {}, - "source": [ - "## Example\n", - "\n", - "\n", - "The following snippet shows an example where TEM is used to compute the expectation values of an observable given a simple quantum circuit." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "ab05b87f", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit import QuantumCircuit\n", - "from qiskit.quantum_info import SparsePauliOp\n", - "\n", - "# Create a quantum circuit\n", - "qc = QuantumCircuit(3)\n", - "qc.u(0.4, 0.9, -0.3, 0)\n", - "qc.u(-0.4, 0.2, 1.3, 1)\n", - "qc.u(-1.2, -1.2, 0.3, 2)\n", - "for _ in range(2):\n", - " qc.barrier()\n", - " qc.cx(0, 1)\n", - " qc.cx(2, 1)\n", - " qc.barrier()\n", - " qc.u(0.4, 0.9, -0.3, 0)\n", - " qc.u(-0.4, 0.2, 1.3, 1)\n", - " qc.u(-1.2, -1.2, 0.3, 2)\n", - "\n", - "# Define the observables\n", - "observable = SparsePauliOp(\"IYX\", 1.0)\n", - "\n", - "# Define the execution options\n", - "pub = (qc, [observable])\n", - "options = {\"default_precision\": 0.02}\n", - "\n", - "# Define backend to use. TEM will choose the least-busy device\n", - "# reported by IBM if not specified\n", - "backend_name = \"ibm_marrakesh\"\n", - "\n", - "# Run the TEM function (uses around three minutes of QPU time)\n", - "job = tem.run(pubs=[pub], backend_name=backend_name, options=options)" - ] - }, - { - "cell_type": "markdown", - "id": "6e2a97e2", - "metadata": {}, - "source": [ - "Use the Qiskit Serverless APIs to check your Qiskit Function workload's status:" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "47b0db71", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "QUEUED\n" - ] - } - ], - "source": [ - "print(job.status())" - ] - }, - { - "cell_type": "markdown", - "id": "fbaeace8", - "metadata": {}, - "source": [ - "You can return the results as:" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "ad5b9a53", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "0.02165380888171687\n" - ] - } - ], - "source": [ - "result = job.result()\n", - "evs = result[0].data.evs\n", - "print(evs[0])" - ] - }, - { - "cell_type": "markdown", - "id": "e5e138d3", - "metadata": {}, - "source": [ - "\n", - " The expected value for the noiseless circuit for the given operator should be around `0.18409094298943401`.\n", - "" - ] - }, { "cell_type": "markdown", "id": "e9ec2e67", diff --git a/docs/functions/algorithmiq-tem/performance-tuning.mdx b/docs/functions/algorithmiq-tem/performance-tuning.mdx new file mode 100644 index 000000000000..6caa1836cbe3 --- /dev/null +++ b/docs/functions/algorithmiq-tem/performance-tuning.mdx @@ -0,0 +1,28 @@ +--- +title: Advanced techniques with Algorithmiq TEM +description: Practical guidance for tuning accuracy, runtime, and cost when using the TEM Qiskit Function. +--- + +*Algorithmiq is encouraged to expand this page with vendor-specific tuning guidance. The suggestions below are derived from the API reference and are intended as a starting point.* + +## Accuracy vs runtime tradeoffs + +The primary accuracy lever is `tem_max_bond_dimension` — higher values improve mitigation fidelity but increase classical post-processing cost significantly. For initial runs, start with a lower value and increase if results show high residual noise. + +`tem_compression_cutoff` controls singular-value truncation in the tensor network; tightening it (smaller value) improves accuracy at the cost of runtime. + +## Randomization settings + +`num_randomizations` and `shots_per_randomization` jointly determine total shot count. A larger `num_randomizations` generally improves the quality of the noise model learned from randomized circuits. Consider the tradeoff against `max_execution_time`. + +## Readout error mitigation + +`mitigate_readout_error=True` adds a calibration pass before execution. This is recommended for backends with significant readout errors, but adds QPU overhead. Use `num_readout_calibration_shots` to control calibration cost. + +## Layer learning + +`max_layers_to_learn` caps how many circuit layers TEM characterizes. For deep circuits, limiting this reduces calibration time but may miss noise in deeper layers. Set `layer_pair_depths` explicitly when you have prior knowledge of where noise concentrates. + +## When to use TEM vs other approaches + +TEM is best suited for circuits where noise is dominated by gate errors that can be captured by a tensor-network noise model. See the [API reference](/docs/api/functions/algorithmiq-tem) for full parameter details. diff --git a/docs/functions/application-functions/kipu-optimization.ipynb b/docs/functions/application-functions/kipu-optimization.ipynb deleted file mode 100644 index ad8e44f4e9dd..000000000000 --- a/docs/functions/application-functions/kipu-optimization.ipynb +++ /dev/null @@ -1,650 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "f7d9993f", - "metadata": {}, - "source": [ - "---\n", - "title: Iskay Quantum Optimizer - A Qiskit Function by Kipu Quantum\n", - "description: Efficiently solve optimization problems with Kipu Quantum's Iskay Quantum Optimizer, available on the IBM Qiskit Functions Catalog\n", - "---\n", - "\n", - "{/* cspell:ignore Kipu, DCQO, QUBO, HUBO, counterdiabatic, Iskay, bitflips, Cadavid, Chandarana */}" - ] - }, - { - "cell_type": "markdown", - "id": "dde95705", - "metadata": {}, - "source": [ - "# Iskay Quantum Optimizer - A Qiskit Function by Kipu Quantum\n", - "\n", - "*See the [API reference](/docs/api/functions/kipu-optimization)*" - ] - }, - { - "cell_type": "markdown", - "id": "61da1dd5", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [] - }, - { - "cell_type": "markdown", - "id": "c60ba821", - "metadata": {}, - "source": [ - "\n", - "* Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", - "\n", - "\n", - "## Overview\n", - "\n", - "With the Iskay Quantum Optimizer by Kipu Quantum, you can tackle complex optimization problems using IBM® quantum computers. This solver leverages Kipu's cutting-edge [bf-DCQO algorithm](https://doi.org/10.48550/arXiv.2409.04477) requiring only the objective function as input to automatically deliver problem solutions. It can handle optimization problems involving up to 156 qubits, enabling the use of all qubits of the IBM quantum devices. The Optimizer uses a 1-to-1 mapping between classical variables and qubits, which allows you to tackle optimization problems with up to 156 binary variables.\n", - "\n", - "The Optimizer enables the solving of unconstrained binary optimization problems. In addition to the commonly used QUBO (Quadratic Unconstrained Binary Optimization) formulation, it also supports higher-order (HUBO) optimization problems. The solver utilizes a non-variational quantum algorithm, performing most of the computation on quantum devices.\n", - "\n", - "The following provides more details about the used algorithm and a brief guide on how to use the function, as well as benchmarking results on various problem instances of different sizes and complexities." - ] - }, - { - "cell_type": "markdown", - "id": "5f761442", - "metadata": {}, - "source": [ - "## Description\n", - "\n", - "The Optimizer is a ready-to-use implementation of cutting-edge quantum optimization algorithms. It solves optimization problems by running highly-compressed quantum circuits on quantum hardware. This compression is achieved by introducing counterdiabatic terms into the underlying time evolution of the quantum system. The algorithm executes several iterations of hardware runs to obtain the final solutions and combines it with post-processing. These steps are seamlessly integrated into the Optimizer's workflow and are executed automatically.\n", - "\n", - "### How does the Quantum Optimizer work?\n", - "This section outlines the basics of the implemented bf-DCQO algorithm. An introduction to the algorithm can also be found on the [Qiskit YouTube channel](https://www.youtube.com/watch?v=33QmsXhIlpU&t=1223s).\n", - "\n", - "The algorithm is based on the time evolution of a quantum system which is transformed over time, where the problem solution is encoded in the ground state of the quantum system at the end of the evolution. According to the [adiabatic theorem](https://en.wikipedia.org/wiki/Adiabatic_theorem), this evolution has to be slow to ensure the system remains in its ground state. Digitizing this evolution is the basis of digitized quantum adiabatic computation (DQA) and the infamous QAOA algorithm. However, the required slow evolution is not feasible for increasing problem sizes since it results in an increasing circuit depth. By using counterdiabatic protocols, you can suppress unwanted excitations occurring during short evolution times while remaining in the ground state. Here, digitizing this shorter evolution time results in quantum circuits with shorter depth and fewer entangling gates.\n", - "\n", - "The circuits of the bf-DCQO algorithms typically use up to ten times fewer entangling gates than DQA, and three to four times fewer entangling gates than standard QAOA implementations. Because of the smaller number of gates, fewer errors occur during the circuit execution on hardware. Hence, the optimizer does not require using techniques like error suppression or error mitigation. Implementing them in future versions can enhance the solution quality even further.\n", - "\n", - "Although the bf-DCQO algorithm uses iterations, it is non-variational. After each iteration of the algorithm, the distribution of states is measured. The obtained distribution is used to calculate a so-called bias-field. The bias-field allows starting the next iteration from an energy state near the previously found solution. In this way, the algorithm moves with each iteration to solutions of lower energy. Typically, approximately ten iterations are sufficient to converge to a solution, in total requiring a much lower number of iterations than variational algorithms, which is on the order of approximately 100 iterations.\n", - "\n", - "The optimizer combines the bf-DCQO algorithm with classical post-processing. After measuring the distribution of states, a local search is performed. During the local search, the bits of the measured solution are randomly flipped. After the flip, the energy of the new bitstring is evaluated. If the energy is lower, the bitstring is kept as the new solution. The local search only scales linearly with the number of qubits; hence, it is computationally cheap. Since the post-processing corrects local bitflips, it compensates for bit-flip errors that often are the result of hardware imperfections and readout errors.\n", - "\n", - "### Workflow\n", - "\n", - "A schematic of the workflow of the Quantum Optimizer follows.\n", - "\n", - "![Workflow](/docs/images/guides/kipu-optimization/workflow.svg \"Workflow of the Quantum Optimizer\")\n", - "\n", - "By using the Quantum Optimizer, solving an optimization problem on quantum hardware can be reduced to\n", - "* Formulate the objective function of the problem\n", - "* Access the Optimizer via Qiskit Functions\n", - "* Run the Optimizer and collect the result" - ] - }, - { - "cell_type": "markdown", - "id": "b34fe075", - "metadata": {}, - "source": [ - "## Benchmarks\n", - "\n", - "The benchmark metrics below show that the Optimizer effectively addresses problems involving up to 156 qubits and offer a general overview of the optimizer's accuracy and scalability across different problem types. Note that actual performance metrics may vary depending on specific problem characteristics, such as the number of variables, the density and locality of terms in the objective function, and the polynomial order.\n", - "\n", - "The following table includes the approximation ratio (AR), a metric defined as follows:\n", - "$$\n", - "AR = \\frac{C^{*} - C_\\textrm{max}}{C_{\\textrm{min}} - C_{\\textrm{max}}},\n", - "$$\n", - "where $C$ is the objective function, $C_{\\textrm{min}}$, $C_{\\textrm{max}}$ are its minimum and maximum values, and $C^{*}$ is the cost of the best solution found, respectively. Therefore, AR=100\\% means that the ground state of the problem has been obtained.\n", - "\n", - "\n", - "| Example | Number of qubits | Approximation Ratio | Total time (s) | Runtime usage (s) | Total Number of shots | Number of iterations |\n", - "| ----------------- | :--------------: | :------: | :------------: | :---------------: | :-------------------: | :------------------: |\n", - "| Unweighted MaxCut | 28 | 100% | 180 | 30 | 30k | 5 |\n", - "| Unweighted MaxCut | 30 | 100% | 180 | 30 | 30k | 5 |\n", - "| Unweighted MaxCut | 32 | 100% | 180 | 30 | 30k | 5 |\n", - "| Unweighted MaxCut | 80 | 100% | 480 | 60 | 90k | 9 |\n", - "| Unweighted MaxCut | 100 | 100% | 330 | 60 | 60k | 6 |\n", - "| Unweighted MaxCut | 120 | 100% | 370 | 60 | 60k | 6 |\n", - "| HUBO 1 | 156 | 100% | 600 | 70 | 100k | 10 |\n", - "| HUBO 2 | 156 | 100% | 600 | 70 | 100k | 10 |\n", - "\n", - "- The MaxCut instances with 28, 30, and 32 qubits were run on ibm_sherbrooke. Instances with 80, 100, and 120 were run on a Heron r2 processor.\n", - "- The HUBO instances were also run on a Heron r2 processor.\n", - "\n", - "All the benchmark instances are accessible on GitHub (see [Kipu benchmark instances](https://github.com/Kipu-Quantum-GmbH/benchmark-instances)). An example to run these instances can be found in [Example 3: Benchmark instances](#example-3-benchmark-instances)." - ] - }, - { - "cell_type": "markdown", - "id": "73390a19", - "metadata": {}, - "source": [ - "## Get started\n", - "\n", - "In this documentation, we will go through the steps of using the Iskay Quantum Optimizer. In the process we will quickly show how to load the function from the catalog and how to convert your problem to a valid input, all while showing how you can experiment with different optional parameters.\n", - "\n", - "For a more detailed example, please check out the tutorial [Solve the Market Split problem with Kipu Quantum's Iskay Quantum Optimizer](/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer), where we work through the whole process of using Iskay Solver to address the Market Split problem, which represents a real-world resource allocation challenge where markets must be partitioned into balanced sales regions to meet exact demand targets.\n", - "\n", - "Authenticate using your API key, found on the [IBM Quantum Platform dashboard](http://quantum.cloud.ibm.com/), and select the Qiskit Function as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "0e4fd124", - "metadata": { - "tags": [ - "remove-cell" - ] - }, - "outputs": [], - "source": [ - "# ruff: noqa: F821" - ] - }, - { - "cell_type": "markdown", - "id": "e5cd4ac8", - "metadata": {}, - "source": [ - "\n", - "The following code assumes that you have saved your credentials. If you have not, follow the instructions in [save your IBM Cloud account](/docs/guides/functions#install-qiskit-functions-catalog-client) to authenticate with your API key.\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "95a715d2", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", - "\n", - "catalog = QiskitFunctionsCatalog(\n", - " channel=\"ibm_quantum_platform\",\n", - " instance=\"INSTANCE_CRN\",\n", - " # For `token`, use the 44-character API_KEY you created\n", - " # and saved from the IBM Quantum Platform Home dashboard\n", - " token=\"YOUR_API_KEY\",\n", - ")\n", - "\n", - "# Access Function\n", - "optimizer = catalog.load(\"kipu-quantum/iskay-quantum-optimizer\")" - ] - }, - { - "cell_type": "markdown", - "id": "4a8e24f7", - "metadata": {}, - "source": [ - "## Custom configuration example\n", - "\n", - "Here's how you might configure Iskay with different settings:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "712dbae3", - "metadata": {}, - "outputs": [], - "source": [ - "custom_options = {\n", - " \"shots\": 15_000, # Higher shot count for better statistics\n", - " \"num_iterations\": 12, # More iterations for solution refinement\n", - " \"preprocessing_level\": 1, # Light preprocessing for problem simplification\n", - " \"postprocessing_level\": 2, # Maximum postprocessing for solution quality\n", - " \"transpilation_level\": 3, # Use higher transpilation level to optimize circuit\n", - " \"seed_transpiler\": 42, # Fixed seed for reproducible results\n", - " \"job_tags\": [\"custom_config\"], # Custom tracking tags\n", - "}" - ] - }, - { - "cell_type": "markdown", - "id": "50690350", - "metadata": {}, - "source": [ - "**Seed optimization**: Note that `seed_transpiler` is set to `None` by default. This enables the transpiler's automatic optimization process. When `None`, the system will start a trial with multiple seeds and select the one that produces the best circuit depth, leveraging the full power of the `max_trials` parameter for each transpilation level.\n", - "\n", - "**Transpilation level performance**: Increasing the number of `max_trials` with higher values for `transpilation_level` will unavoidably increase the transpilation time, but it might not always change the final circuit - this depends heavily on the specific circuit structure and complexity. For some circuits/problems, however, the difference between 10 trials (level 1) and 50 trials (level 5) can be dramatic, so exploring these parameters might be the key to successfully finding a solution." - ] - }, - { - "cell_type": "markdown", - "id": "d4ca2590", - "metadata": {}, - "source": [ - "## Example 1: Simple cost function\n", - "\n", - "Consider the cost function in spin formulation:\n", - "$$\n", - "C(x_0, x_1, x_2, x_3, x_4) = 1 + 1.5x_0 + 2x_1 + 1.3x_2 + 2.5x_0x_3 + 3.5x_1x_4 + 4x_0x_1x_2\n", - "$$\n", - "\n", - "where $(x_0, ..., x_4) \\in \\{-1, 1\\}^5$.\n", - "\n", - "The solution to this simple cost function is\n", - "$$\n", - "(x_0, x_1, x_2, x_3, x_4) = (-1, -1, -1, 1, 1)\n", - "$$\n", - "with minimum value $C^{*} = -6$" - ] - }, - { - "cell_type": "markdown", - "id": "a98e8232", - "metadata": {}, - "source": [ - "### 1. Create the objective function\n", - "\n", - "We start by creating a dictionary with the coefficients of the objective function as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "3b4a58b1", - "metadata": {}, - "outputs": [], - "source": [ - "objective_func = {\n", - " \"()\": 1,\n", - " \"(0,)\": 1.5,\n", - " \"(1,)\": 2,\n", - " \"(2,)\": 1.3,\n", - " \"(0, 3)\": 2.5,\n", - " \"(1, 4)\": 3.5,\n", - " \"(0, 1, 2)\": 4,\n", - "}" - ] - }, - { - "cell_type": "markdown", - "id": "ab63b08f", - "metadata": {}, - "source": [ - "### 2. Run the Optimizer\n", - "\n", - "We solve the problem by running the optimizer. Since $(x_0, ..., x_4) \\in \\{-1, 1\\}^5$ we must set `problem_type=spin`." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "469ae361", - "metadata": {}, - "outputs": [], - "source": [ - "# Setup options to run the optimizer\n", - "options = {\"shots\": 5000, \"num_iterations\": 5, \"use_session\": True}\n", - "\n", - "arguments = {\n", - " \"problem\": objective_func,\n", - " \"problem_type\": \"spin\",\n", - " \"backend_name\": backend_name, # such as \"ibm_fez\"\n", - " \"options\": options,\n", - "}\n", - "\n", - "job = optimizer.run(**arguments)" - ] - }, - { - "cell_type": "markdown", - "id": "1e3a8542", - "metadata": {}, - "source": [ - "### 3. Retrieve the result\n", - "\n", - "The solution of the optimization problem is provided directly from the optimizer." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "2f74d7e2", - "metadata": {}, - "outputs": [], - "source": [ - "print(job.result())" - ] - }, - { - "cell_type": "markdown", - "id": "c4d0a0f8", - "metadata": {}, - "source": [ - "This will show a dictionary of the form:\n", - "\n", - "```\n", - "{'solution': {'0': -1, '1': -1, '2': -1, '3': 1, '4': 1},\n", - " 'solution_info': {'bitstring': '11100',\n", - " 'cost': -13.8,\n", - " 'seed_transpiler': 42,\n", - " 'mapping': {0: 0, 1: 1, 2: 2, 3: 3, 4: 4}},\n", - " 'prob_type': 'spin'}\n", - "```\n", - "\n", - "Notice that the dictionary `solution` displays the result vector $(x_0, x_1, x_2, x_3, x_4) = (-1, -1, -1, 1, 1)$." - ] - }, - { - "cell_type": "markdown", - "id": "7eaa5cac", - "metadata": {}, - "source": [ - "## Example 2: MaxCut\n", - "\n", - "Many graph problems like MaxCut or Maximum independent set are NP-hard problems and ideal candidates for testing quantum algorithms and hardware. This example demonstrates solving the MaxCut problem of a 3-regular graph with the Quantum Optimizer.\n", - "\n", - "To run this example you must install the `networkx` package in addition to the `qiskit-ibm-catalog`. To install it, run the following command:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "9ea6d138", - "metadata": {}, - "outputs": [], - "source": [ - "# %pip install networkx numpy" - ] - }, - { - "cell_type": "markdown", - "id": "0c63487f", - "metadata": {}, - "source": [ - "### 1. Create the objective function\n", - "\n", - "Start by generating a random 3-regular graph. For this graph, we define the objective function of the MaxCut problem." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "d1d4017f", - "metadata": {}, - "outputs": [], - "source": [ - "import networkx as nx\n", - "\n", - "# Create a random 3-regular graph\n", - "G = nx.random_regular_graph(3, 10, seed=42)\n", - "\n", - "\n", - "# Create the objective function for MaxCut in Ising formulation\n", - "def graph_to_ising_maxcut(G):\n", - " \"\"\"\n", - " Convert a NetworkX graph to an Ising Hamiltonian for the max-cut problem.\n", - " Args:\n", - " G (networkx.Graph): The input graph.\n", - " Returns:\n", - " dict: The objective function of the Ising model\n", - " \"\"\"\n", - " # Initialize the linear and quadratic coefficients\n", - " objective_func = {}\n", - " # Populate the coefficients\n", - " for i, j in G.edges:\n", - " objective_func[f\"({i}, {j})\"] = 0.5\n", - " return objective_func\n", - "\n", - "\n", - "objective_func = graph_to_ising_maxcut(G)" - ] - }, - { - "cell_type": "markdown", - "id": "3be09664", - "metadata": {}, - "source": [ - "### 2. Run the Optimizer\n", - "\n", - "Solve the problem by running the optimizer." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "2499ab67", - "metadata": {}, - "outputs": [], - "source": [ - "options = {\"shots\": 5000, \"num_iterations\": 5, \"use_session\": True}\n", - "\n", - "arguments = {\n", - " \"problem\": objective_func,\n", - " \"problem_type\": \"spin\",\n", - " \"backend_name\": backend_name, # such as \"ibm_fez\"\n", - " \"options\": options,\n", - "}\n", - "\n", - "job = optimizer.run(**arguments)" - ] - }, - { - "cell_type": "markdown", - "id": "3548f6dc", - "metadata": {}, - "source": [ - "### 3. Retrieve the result\n", - "\n", - "Retrieve the result and map the solution bitstring back to the original graph nodes." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "169cbd6e", - "metadata": {}, - "outputs": [], - "source": [ - "print(job.result())" - ] - }, - { - "cell_type": "markdown", - "id": "7f22d66a", - "metadata": {}, - "source": [ - "The solution to the Maxcut problem is directly contained in the `solution` sub-dictionary of the result object" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "38309554", - "metadata": {}, - "outputs": [], - "source": [ - "maxcut_solution = job.result()[\"solution\"]" - ] - }, - { - "cell_type": "markdown", - "id": "19a664c4", - "metadata": {}, - "source": [ - "## Example 3: Benchmark instances" - ] - }, - { - "cell_type": "markdown", - "id": "98545ce3", - "metadata": {}, - "source": [ - "The benchmark instances are available on GitHub: [Kipu benchmark instances](https://github.com/Kipu-Quantum-GmbH/benchmark-instances).\n", - "\n", - "The instances can be loaded using the `pygithub` library. To install it, run the following command:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "1d8777e4", - "metadata": {}, - "outputs": [], - "source": [ - "# %pip install pygithub" - ] - }, - { - "cell_type": "markdown", - "id": "e3a03447", - "metadata": {}, - "source": [ - "The paths for the benchmark instances are:\n", - "\n", - "**Maxcut:**\n", - "- `'maxcut/maxcut_regular_3_100_nodes_weighted.json'`\n", - "- `'maxcut/maxcut_regular_3_140_nodes_weighted.json'`\n", - "- `'maxcut/maxcut_regular_3_150_nodes_weighted.json'`\n", - "- `'maxcut/maxcut_regular_4_130_nodes_weighted.json'`\n", - "\n", - "**HUBO:**\n", - "- `'HUBO/hubo1_marrakesh.json'`\n", - "- `'HUBO/hubo2_marrakesh.json'`\n", - "\n", - "To reproduce the performance of the benchmark for the HUBO instances, select the backend `ibm_marrakesh` and set `direct_qubit_mapping` to `True` in the `options` sub-dictionary." - ] - }, - { - "cell_type": "markdown", - "id": "adbed9be", - "metadata": {}, - "source": [ - "The following example runs the Maxcut instance with 150 nodes." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "da681a18", - "metadata": {}, - "outputs": [], - "source": [ - "from github import Github\n", - "import urllib\n", - "import json\n", - "import ast\n", - "\n", - "repo = \"Kipu-Quantum-GmbH/benchmark-instances\"\n", - "path = \"maxcut/maxcut_regular_3_150_nodes_weighted.json\"\n", - "gh = Github()\n", - "repo = gh.get_repo(repo)\n", - "branch = \"main\"\n", - "file = repo.get_contents(urllib.parse.quote(path), ref=branch)\n", - "\n", - "# load json file with benchmark problem\n", - "problem_json = json.loads(file.decoded_content)\n", - "\n", - "# convert objective function to compatible format\n", - "objective_func = {\n", - " key: ast.literal_eval(value) for key, value in problem_json.items()\n", - "}\n", - "\n", - "\n", - "# Setup configuration to run the optimizer\n", - "options = {\n", - " \"shots\": 5_000,\n", - " \"num_iterations\": 5,\n", - " \"use_session\": True,\n", - " \"direct_qubit_mapping\": False,\n", - "}\n", - "\n", - "arguments = {\n", - " \"problem\": objective_func,\n", - " \"problem_type\": \"spin\",\n", - " \"backend_name\": \"\",\n", - " \"options\": options,\n", - "}\n", - "\n", - "job = optimizer.run(**arguments)\n", - "\n", - "result = job.result()" - ] - }, - { - "cell_type": "markdown", - "id": "664476ff", - "metadata": {}, - "source": [ - "## Use cases\n", - "\n", - "Typical use cases for the Optimization solver are combinatorial optimization problems. You can solve problems from many industries like finance, pharmaceutics, or logistics. Some examples follow.\n", - "* Portfolio optimization (QUBO): [scientific publication](https://doi.org/10.1103/PhysRevApplied.22.054037) and [white paper](https://kipu-quantum.com/zope64/kipu_2024/content/e3915/e3916/e4187/White-Paper-2-Financial-modeling-on-quantum-computers-using-digitally-compressed-algorithms-1.pdf)\n", - "* Protein folding (HUBO): [scientific publication](https://doi.org/10.1103/PhysRevApplied.20.014024)\n", - "* Logistics scheduling (QUBO): [scientific publication](https://doi.org/10.1103/PhysRevApplied.22.064068)\n", - "* Network optimization: [webinar](https://www.youtube.com/watch?v=w5SrCIK88No)\n", - "* Market split (QUBO): [tutorial](/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer)\n", - "\n", - "If you are interested in tackling a specific use case and develop a dedicated mapping, we can assist you. [Contact us](https://share-eu1.hsforms.com/2Ff8cgWvTR9ukT_fPoaNhDw2dqpz5)." - ] - }, - { - "cell_type": "markdown", - "id": "e9ec2e67", - "metadata": {}, - "source": [ - "## Get support\n", - "\n", - "For support, contact support@kipu-quantum.com." - ] - }, - { - "cell_type": "markdown", - "id": "5a6a25c8", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "- [Request access to the Quantum Optimizer by Kipu Quantum](https://share-eu1.hsforms.com/2Ff8cgWvTR9ukT_fPoaNhDw2dqpz5).\n", - "- Visit the [API reference](/docs/api/functions/kipu-optimization) for this Qiskit Function.\n", - "- Try the [Solve the Market Split problem with Kipu Quantum's Iskay Quantum Optimizer](/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer) tutorial.\n", - "- Review [Romero, S. V., et al. (2025). Bias-Field Digitized Counterdiabatic Quantum Algorithm for Higher-Order Binary Optimization. arXiv preprint arXiv:2409.04477](https://arxiv.org/abs/2409.04477).\n", - "- Review [Cadavid, A. G., et al. (2024). Bias-field digitized counterdiabatic quantum optimization. arXiv preprint arXiv:2405.13898](https://arxiv.org/abs/2405.13898).\n", - "- Review [Chandarana, P., et al. (2025). Runtime Quantum Advantage with Digital Quantum Optimization. arXiv preprint arXiv:2505.08663](https://arxiv.org/abs/2505.08663)." - ] - }, - { - "cell_type": "markdown", - "id": "f73ef6c4", - "metadata": {}, - "source": [ - "## Additional information" - ] - }, - { - "cell_type": "markdown", - "id": "52b5221c", - "metadata": {}, - "source": [ - "Iskay, like our company name Kipu Quantum, is a Peruvian word. Although we are a startup from Germany, these words come from the native country of one of our co-founders, where the Quipu was one of the very first calculation machines developed by mankind 2000 years BCE." - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/docs/functions/colibritd-pde/_toc.json b/docs/functions/colibritd-pde/_toc.json new file mode 100644 index 000000000000..f907acb2c352 --- /dev/null +++ b/docs/functions/colibritd-pde/_toc.json @@ -0,0 +1,50 @@ +{ + "parentUrl": "/docs/guides/functions", + "parentLabel": "Qiskit Functions", + "title": "QUICK-PDE: A Qiskit Function by ColibriTD", + "collapsed": true, + "children": [ + { + "title": "", + "collapsible": false, + "children": [ + { + "title": "Overview", + "url": "/docs/functions/colibritd-pde" + }, + { + "title": "Get started", + "url": "/docs/functions/colibritd-pde/get-started" + }, + { + "title": "Advanced techniques with QUICK-PDE", + "url": "/docs/functions/colibritd-pde/performance-tuning" + }, + { + "title": "Changelog", + "url": "/docs/functions/colibritd-pde/changelog" + } + ] + }, + { + "title": "Tutorials", + "collapsible": false, + "children": [ + { + "title": "Model a flowing non-viscous fluid using QUICK-PDE", + "url": "/docs/tutorials/colibritd-pde" + } + ] + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "/docs/api/functions/colibritd-pde" + } + ] + } + ] +} diff --git a/docs/functions/colibritd-pde/changelog.mdx b/docs/functions/colibritd-pde/changelog.mdx new file mode 100644 index 000000000000..78ab15cd8967 --- /dev/null +++ b/docs/functions/colibritd-pde/changelog.mdx @@ -0,0 +1,6 @@ +--- +title: Changelog +description: Changelog for QUICK-PDE. +--- + +*This section is under development. ColibriTD is encouraged to maintain a changelog here as new features and updates are released.* diff --git a/docs/functions/colibritd-pde/get-started.ipynb b/docs/functions/colibritd-pde/get-started.ipynb new file mode 100644 index 000000000000..f4a23866a553 --- /dev/null +++ b/docs/functions/colibritd-pde/get-started.ipynb @@ -0,0 +1,272 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "page-frontmatter", + "metadata": {}, + "source": [ + "---\ntitle: Get started with QUICK-PDE\ndescription: Get started with QUICK-PDE — authenticate, load the function, and run CFD and material deformation examples.\n---" + ] + }, + { + "cell_type": "markdown", + "id": "73390a19", + "metadata": {}, + "source": [ + "## Setup and load function\n\nFill out the [form to request access to the QUICK-PDE function](https://forms.cloud.microsoft/e/3Wi9cbjQPK). Then, assuming you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment, select the function as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "95a715d2", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", + "\n", + "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n", + "\n", + "quick = catalog.load(\"colibritd/quick-pde\")" + ] + }, + { + "cell_type": "markdown", + "id": "e8837f5f", + "metadata": {}, + "source": [ + "## Run your first workload\n\nTo get started, try one of the following examples:" + ] + }, + { + "cell_type": "markdown", + "id": "446ac943", + "metadata": {}, + "source": [ + "### Computational Fluid Dynamics (CFD)\n", + "\n", + "When initial conditions are set to $u(0,x) = x$, the results are as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d56e1440", + "metadata": {}, + "outputs": [], + "source": [ + "# launch the simulation with initial conditions u(0,x) = a*x + b\n", + "job = quick.run(use_case=\"cfd\", physical_parameters={\"a\": 1.0, \"b\": 0.0})" + ] + }, + { + "cell_type": "markdown", + "id": "03998691", + "metadata": {}, + "source": [ + "Check your Qiskit Function workload's [status](/docs/guides/functions#check-job-status) or return [results](/docs/guides/functions#retrieve-results) as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "856fe992", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'QUEUED'" + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "print(job.status())\n", + "solution = job.result()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c42aba9b", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "\n", + "_ = plt.figure()\n", + "ax = plt.axes(projection=\"3d\")\n", + "\n", + "# plot the solution using the 3d plotting capabilities of pyplot\n", + "t, x = np.meshgrid(solution[\"samples\"][\"t\"], solution[\"samples\"][\"x\"])\n", + "ax.plot_surface(\n", + " t,\n", + " x,\n", + " solution[\"functions\"][\"u\"],\n", + " edgecolor=\"royalblue\",\n", + " lw=0.25,\n", + " rstride=26,\n", + " cstride=26,\n", + " alpha=0.3,\n", + ")\n", + "ax.scatter(t, x, solution[\"functions\"][\"u\"], marker=\".\")\n", + "ax.set(xlabel=\"t\", ylabel=\"x\", zlabel=\"u(t,x)\")\n", + "\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "dbbd4509", + "metadata": {}, + "source": [ + "### Material deformation\n", + "\n", + "The material deformation use case requires the physical parameters of your material and the applied force, as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a568e325", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "# select the properties of your material\n", + "job = quick.run(\n", + " use_case=\"md\",\n", + " physical_parameters={\n", + " \"t\": 12.0,\n", + " \"K\": 100.0,\n", + " \"n\": 4.0,\n", + " \"b\": 10.0,\n", + " \"epsilon_0\": 0.1,\n", + " \"sigma_0\": 5.0,\n", + " },\n", + ")\n", + "\n", + "# plot the result\n", + "solution = job.result()\n", + "\n", + "_ = plt.figure()\n", + "stress_plot = plt.subplot(211)\n", + "plt.plot(solution[\"samples\"][\"x\"], solution[\"functions\"][\"u\"])\n", + "strain_plot = plt.subplot(212)\n", + "plt.plot(solution[\"samples\"][\"x\"], solution[\"functions\"][\"sigma\"])\n", + "\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "f1cfa869", + "metadata": {}, + "source": [ + "The following is an example of how to get the value of the function for a specific set of coordinates:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c5193114", + "metadata": {}, + "outputs": [], + "source": [ + "# u(t=0.2, x=0.7) == 2\n", + "assert solution[\"samples\"][\"t\"][1] == 0.2\n", + "assert solution[\"samples\"][\"x\"][2] == 0.7\n", + "assert solution[\"functions\"][\"u\"][1, 2] == 2" + ] + }, + { + "cell_type": "markdown", + "id": "04236c83", + "metadata": {}, + "source": [ + "## Fetch error messages\n", + "\n", + "If your workload status is `ERROR`, use `job.error_message()` to fetch the error message to help debug, as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "90c6de7c", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{\"error\": [\"qiskit.exceptions.QiskitError: 'Unknown argument \\\"physical_params\\\", did you make a typo? -- https://docs.quantum.ibm.com/errors#1804'\\n\"]}\n", + "___\n", + "qiskit.exceptions.QiskitError: 'Unknown argument \"physical_params\", did you make a typo? -- https://docs.quantum.ibm.com/errors#1804'\n", + "\n" + ] + } + ], + "source": [ + "job = quick.run(use_case=\"mdf\", physical_params={})\n", + "\n", + "print(job.error_message())\n", + "\n", + "\n", + "# or write a wrapper around it for a more human readable version\n", + "def pprint_error(job):\n", + " print(\"\".join(eval(job.error_message())[\"error\"]))\n", + "\n", + "\n", + "print(\"___\")\n", + "pprint_error(job)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/functions/application-functions/colibritd-pde.ipynb b/docs/functions/colibritd-pde/index.ipynb similarity index 53% rename from docs/functions/application-functions/colibritd-pde.ipynb rename to docs/functions/colibritd-pde/index.ipynb index 4e4e3924a370..5388c857b268 100644 --- a/docs/functions/application-functions/colibritd-pde.ipynb +++ b/docs/functions/colibritd-pde/index.ipynb @@ -24,16 +24,6 @@ "*See the [API reference](/docs/api/functions/colibritd-pde)*" ] }, - { - "cell_type": "markdown", - "id": "b9852687", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [] - }, { "cell_type": "markdown", "id": "01701579", @@ -111,249 +101,6 @@ "| Hypoelastic 1D tensile test | 18 | `RANDOM` | $10^{-2}$ | 123 | 100 |" ] }, - { - "cell_type": "markdown", - "id": "73390a19", - "metadata": {}, - "source": [ - "## Get started\n", - "\n", - "Fill out the [form to request access to the QUICK-PDE function](https://forms.cloud.microsoft/e/3Wi9cbjQPK). Then, assuming you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment, select the function as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "95a715d2", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", - "\n", - "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n", - "\n", - "quick = catalog.load(\"colibritd/quick-pde\")" - ] - }, - { - "cell_type": "markdown", - "id": "e8837f5f", - "metadata": {}, - "source": [ - "## Examples\n", - "\n", - "To get started, try one of the following examples:" - ] - }, - { - "cell_type": "markdown", - "id": "446ac943", - "metadata": {}, - "source": [ - "### Computational Fluid Dynamics (CFD)\n", - "\n", - "When initial conditions are set to $u(0,x) = x$, the results are as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "d56e1440", - "metadata": {}, - "outputs": [], - "source": [ - "# launch the simulation with initial conditions u(0,x) = a*x + b\n", - "job = quick.run(use_case=\"cfd\", physical_parameters={\"a\": 1.0, \"b\": 0.0})" - ] - }, - { - "cell_type": "markdown", - "id": "03998691", - "metadata": {}, - "source": [ - "Check your Qiskit Function workload's [status](/docs/guides/functions#check-job-status) or return [results](/docs/guides/functions#retrieve-results) as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "856fe992", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "'QUEUED'" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "print(job.status())\n", - "solution = job.result()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "c42aba9b", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "import numpy as np\n", - "import matplotlib.pyplot as plt\n", - "\n", - "_ = plt.figure()\n", - "ax = plt.axes(projection=\"3d\")\n", - "\n", - "# plot the solution using the 3d plotting capabilities of pyplot\n", - "t, x = np.meshgrid(solution[\"samples\"][\"t\"], solution[\"samples\"][\"x\"])\n", - "ax.plot_surface(\n", - " t,\n", - " x,\n", - " solution[\"functions\"][\"u\"],\n", - " edgecolor=\"royalblue\",\n", - " lw=0.25,\n", - " rstride=26,\n", - " cstride=26,\n", - " alpha=0.3,\n", - ")\n", - "ax.scatter(t, x, solution[\"functions\"][\"u\"], marker=\".\")\n", - "ax.set(xlabel=\"t\", ylabel=\"x\", zlabel=\"u(t,x)\")\n", - "\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "id": "dbbd4509", - "metadata": {}, - "source": [ - "### Material deformation\n", - "\n", - "The material deformation use case requires the physical parameters of your material and the applied force, as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "a568e325", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "import matplotlib.pyplot as plt\n", - "\n", - "# select the properties of your material\n", - "job = quick.run(\n", - " use_case=\"md\",\n", - " physical_parameters={\n", - " \"t\": 12.0,\n", - " \"K\": 100.0,\n", - " \"n\": 4.0,\n", - " \"b\": 10.0,\n", - " \"epsilon_0\": 0.1,\n", - " \"sigma_0\": 5.0,\n", - " },\n", - ")\n", - "\n", - "# plot the result\n", - "solution = job.result()\n", - "\n", - "_ = plt.figure()\n", - "stress_plot = plt.subplot(211)\n", - "plt.plot(solution[\"samples\"][\"x\"], solution[\"functions\"][\"u\"])\n", - "strain_plot = plt.subplot(212)\n", - "plt.plot(solution[\"samples\"][\"x\"], solution[\"functions\"][\"sigma\"])\n", - "\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "id": "f1cfa869", - "metadata": {}, - "source": [ - "The following is an example of how to get the value of the function for a specific set of coordinates:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "c5193114", - "metadata": {}, - "outputs": [], - "source": [ - "# u(t=0.2, x=0.7) == 2\n", - "assert solution[\"samples\"][\"t\"][1] == 0.2\n", - "assert solution[\"samples\"][\"x\"][2] == 0.7\n", - "assert solution[\"functions\"][\"u\"][1, 2] == 2" - ] - }, - { - "cell_type": "markdown", - "id": "04236c83", - "metadata": {}, - "source": [ - "## Fetch error messages\n", - "\n", - "If your workload status is `ERROR`, use `job.error_message()` to fetch the error message to help debug, as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "90c6de7c", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "{\"error\": [\"qiskit.exceptions.QiskitError: 'Unknown argument \\\"physical_params\\\", did you make a typo? -- https://docs.quantum.ibm.com/errors#1804'\\n\"]}\n", - "___\n", - "qiskit.exceptions.QiskitError: 'Unknown argument \"physical_params\", did you make a typo? -- https://docs.quantum.ibm.com/errors#1804'\n", - "\n" - ] - } - ], - "source": [ - "job = quick.run(use_case=\"mdf\", physical_params={})\n", - "\n", - "print(job.error_message())\n", - "\n", - "\n", - "# or write a wrapper around it for a more human readable version\n", - "def pprint_error(job):\n", - " print(\"\".join(eval(job.error_message())[\"error\"]))\n", - "\n", - "\n", - "print(\"___\")\n", - "pprint_error(job)" - ] - }, { "cell_type": "markdown", "id": "e9ec2e67", diff --git a/docs/functions/colibritd-pde/performance-tuning.mdx b/docs/functions/colibritd-pde/performance-tuning.mdx new file mode 100644 index 000000000000..4c6f182333fa --- /dev/null +++ b/docs/functions/colibritd-pde/performance-tuning.mdx @@ -0,0 +1,26 @@ +--- +title: Advanced techniques with QUICK-PDE +description: Practical guidance for configuring resolution, optimizer, and shot settings for QUICK-PDE. +--- + +*ColibriTD is encouraged to expand this page with vendor-specific tuning guidance. The suggestions below are derived from the API reference and are intended as a starting point.* + +## Spatial resolution: nb_qubits and depth + +`nb_qubits` directly sets the spatial resolution of the PDE solution — more qubits capture finer-grained features but require more QPU resources. `depth` controls the ansatz expressibility. Increasing either improves solution quality at the cost of circuit size and execution time. + +For initial experiments, start with the minimum `nb_qubits` needed to represent your problem's relevant features, then scale up. + +## Choosing an optimizer + +The `optimizer` parameter selects the classical optimizer used in the variational loop. Faster optimizers (fewer function evaluations) are cheaper but may find lower-quality solutions. Use `optimizer_options` to tune convergence criteria. ColibriTD is encouraged to document which optimizers work best for each `use_case`. + +## Shots + +`shots` controls the measurement statistics per circuit evaluation. For PDE solving, shot noise affects the variational loss landscape — too few shots can cause the optimizer to converge to a spurious minimum. Start with a higher shot count and reduce once you have a stable optimization. + +## Mode + +The `mode` parameter controls how the function is submitted (for example, session vs batch). Use batch mode for parameter sweeps; use session mode for iterative optimization workflows. + +See the [API reference](/docs/api/functions/colibritd-pde) for full parameter details. diff --git a/docs/functions/global-data-quantum-optimizer/_toc.json b/docs/functions/global-data-quantum-optimizer/_toc.json new file mode 100644 index 000000000000..08ccea070c12 --- /dev/null +++ b/docs/functions/global-data-quantum-optimizer/_toc.json @@ -0,0 +1,50 @@ +{ + "parentUrl": "/docs/guides/functions", + "parentLabel": "Qiskit Functions", + "title": "Quantum Portfolio Optimizer: A Qiskit Function by Global Data Quantum", + "collapsed": true, + "children": [ + { + "title": "", + "collapsible": false, + "children": [ + { + "title": "Overview", + "url": "/docs/functions/global-data-quantum-optimizer" + }, + { + "title": "Get started", + "url": "/docs/functions/global-data-quantum-optimizer/get-started" + }, + { + "title": "Advanced techniques with the Quantum Portfolio Optimizer", + "url": "/docs/functions/global-data-quantum-optimizer/performance-tuning" + }, + { + "title": "Changelog", + "url": "/docs/functions/global-data-quantum-optimizer/changelog" + } + ] + }, + { + "title": "Tutorials", + "collapsible": false, + "children": [ + { + "title": "Dynamic portfolio optimization with Global Data Quantum's Portfolio Optimizer", + "url": "/docs/tutorials/global-data-quantum-optimizer" + } + ] + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "/docs/api/functions/global-data-quantum-optimizer" + } + ] + } + ] +} diff --git a/docs/functions/global-data-quantum-optimizer/changelog.mdx b/docs/functions/global-data-quantum-optimizer/changelog.mdx new file mode 100644 index 000000000000..3b43207e7d64 --- /dev/null +++ b/docs/functions/global-data-quantum-optimizer/changelog.mdx @@ -0,0 +1,6 @@ +--- +title: Changelog +description: Changelog for the Quantum Portfolio Optimizer. +--- + +*This section is under development. Global Data Quantum is encouraged to maintain a changelog here as new features and updates are released.* diff --git a/docs/functions/application-functions/global-data-quantum-optimizer.ipynb b/docs/functions/global-data-quantum-optimizer/get-started.ipynb similarity index 65% rename from docs/functions/application-functions/global-data-quantum-optimizer.ipynb rename to docs/functions/global-data-quantum-optimizer/get-started.ipynb index b1f96a471327..cd2b9f4fb53e 100644 --- a/docs/functions/application-functions/global-data-quantum-optimizer.ipynb +++ b/docs/functions/global-data-quantum-optimizer/get-started.ipynb @@ -2,78 +2,10 @@ "cells": [ { "cell_type": "markdown", - "id": "7b51ae77-8333-41c8-b6e1-90f2155a7cb7", + "id": "page-frontmatter", "metadata": {}, "source": [ - "---\n", - "title: Quantum Portfolio Optimizer - A Qiskit Function by Global Data Quantum\n", - "description: A Qiskit Function to solve Dynamic Portfolio Optimization problems using a fine-tuned implementation of the VQE.\n", - "---\n", - "\n", - "\n", - "# Quantum Portfolio Optimizer: A Qiskit Function by Global Data Quantum\n", - "\n", - "{/* cspell:ignore rebalance, GBPJPY, TMBMKDE */}\n", - "\n", - "*See the [API reference](/docs/api/functions/global-data-quantum-optimizer)*" - ] - }, - { - "cell_type": "markdown", - "id": "a95af5a5-933c-4f11-a841-65483946a528", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [] - }, - { - "cell_type": "markdown", - "id": "0466d79d-52b1-4ae4-bdbe-94357784cf7f", - "metadata": {}, - "source": [ - "\n", - "Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "f350e597-000e-4c64-8e5d-c5b95851d26c", - "metadata": {}, - "source": [ - "## Overview\n", - "\n", - "The Quantum Portfolio Optimizer is a Qiskit Function that tackles the dynamic portfolio optimization problem, a standard problem in finance that aims to rebalance periodic investments across a set of assets, to maximize returns and minimize risks. By deploying cutting-edge quantum optimization techniques, this function simplifies the process so that users, with no expertise in quantum computing, can benefit from its advantages in finding optimal investment trajectories. Ideal for portfolio managers, researchers in quantitative finance, and individual investors, this tool enables back-testing of trading strategies in portfolio optimization." - ] - }, - { - "cell_type": "markdown", - "id": "977a893a-9bbe-47f9-b4be-d9f6b8d27a72", - "metadata": {}, - "source": [ - "## Function description" - ] - }, - { - "cell_type": "markdown", - "id": "9038f89a-7452-45bf-a96c-8a5ba8b061d0", - "metadata": {}, - "source": [ - "The Quantum Portfolio Optimizer function uses the Variational Quantum Eigensolver (VQE) algorithm to solve a Quadratic Unconstrained Binary Optimization (QUBO) problem, addressing dynamic portfolio optimization problems. Users simply need to provide the asset price data and define the investment constraint, then the function runs the quantum optimization process that returns a set of optimized investment trajectories.\n", - "\n", - "The process consists of four main stages. First, the input data is mapped to a quantum-compatible problem, constructing the QUBO of the dynamic portfolio optimization problem, and transforming it into a quantum operator (Ising Hamiltonian). Next, the input problem and the VQE algorithm are adapted to be run in the quantum hardware. The VQE algorithm is then run on the quantum hardware, and finally, the results are post-processed to provide the optimal investment trajectories. The system also includes a noise-aware ([SQD](/docs/guides/qiskit-addons-sqd)-based) post-processing to maximize the quality of the output.\n", - "\n", - "This Qiskit Function is based on the [published manuscript](https://arxiv.org/abs/2412.19150) by Global Data Quantum." - ] - }, - { - "cell_type": "markdown", - "id": "3667fa72-ebef-476a-94a1-553389889623", - "metadata": {}, - "source": [ - "![Visualization of the workflow of the function](/docs/images/guides/global-data-quantum-optimizer/function_workflow.svg)" + "---\ntitle: Get started with the Quantum Portfolio Optimizer\ndescription: Get started with the Quantum Portfolio Optimizer — authenticate, load the function, and run a dynamic portfolio optimization example.\n---" ] }, { @@ -81,7 +13,7 @@ "id": "32a1bfa7-0e6d-4e64-9169-3b285597cfe1", "metadata": {}, "source": [ - "# Get started" + "## Setup and load function" ] }, { @@ -112,7 +44,7 @@ "id": "0503669b-15e6-4533-b4ef-7f6c9e7d9f4f", "metadata": {}, "source": [ - "## Example: Dynamic portfolio optimization with seven assets" + "## Run your first workload" ] }, { @@ -485,88 +417,6 @@ "source": [ "As shown in the figure (blue solid line), the cost distribution for our Variational Quantum Eigensolver (post-processed with SQD) approach is sharply concentrated at lower objective cost values, indicating good optimization performance. In contrast, the noisy baseline exhibits a broader distribution, centered around higher cost values. The gray dashed vertical line represents the mean value of the random distribution, further highlighting the consistency of the function in returning optimized investment strategies. For an additional comparison, the black dashed line in the figure corresponds to the solution obtained with the Gurobi optimizer (free version). All these results are further explored in the benchmarks below for the \"Mixed Assets\" example evaluated with the \"Tailored\" ansatz." ] - }, - { - "cell_type": "markdown", - "id": "de293919-a802-4ebe-95e3-173083268741", - "metadata": {}, - "source": [ - "# Benchmarks" - ] - }, - { - "cell_type": "markdown", - "id": "bb44f36c-de99-44ed-921b-003ec3030e86", - "metadata": {}, - "source": [ - "This function was tested under different configurations of resolution qubits, ansatz circuits, and groupings of assets from various sectors: a mix of different assets (Set 1), oil derivatives (Set 2), and IBEX35 (Set 3). See more details in the following table.\n", - "\n", - "| Set | Date | Assets |\n", - "|-----------|------------|------------------------------------------------------------------------|\n", - "| **Set 1** | 01/01/2023 | 8801.T, CL=F, GBPJPY=X, ITX.MC, META, TMBMKDE-10Y, XS2239553048 |\n", - "| **Set 2** | 01/06/2023 | CL=F, BZ=F, HO=F, NG=F, XOM, RB=F, 2222.SR |\n", - "| **Set 3** | 01/11/2022 | ACS.MC, ITX.MC, FER.MC, ELE.MC, SCYR.MC, AENA.MC, AMS.MC |\n", - "\n", - "Two key metrics were used to evaluate solution quality.\n", - "1. The objective cost, which measures optimization efficiency by comparing the cost function value from each experiment with results from Gurobi (free version).\n", - "2. The Sharpe ratio, which captures the risk-adjusted return of each portfolio, offering insight into the financial performance of the solutions.\n", - "\n", - "Together, these metrics benchmark both computational and financial aspects of the quantum-generated portfolios.\n", - "\n", - "\n", - "| Example | Qubits | Ansatz | Depth | Runtime Usage (s) | Total usage (s) | Objective cost | Sharpe | Gurobi objective cost | Gurobi Sharpe |\n", - "|-------------------------------|--------|-------------------------------|--------|-------------------|------------------|----------------|--------|------------------------|----------------|\n", - "| Mixed Assets (Set 1, 4 time steps, 4-bit) | 112 | Tailored | 83 | 12735 | 13095 | -3.78 | 24.82 | -4.25 | 24.71 |\n", - "| Mixed Assets (Set 1,4 time steps, 4 time steps, 4-bit) | 112 | Real Amplitudes | 359 | 11739 | 11903 | -3.39 | 23.64 | -4.25 | 24.71 |\n", - "| Oil Derivatives (Set 2, 4 time steps, 3-bit)| 84 | Optimized Real Amplitudes | 78 | 6180 | 6350 | -3.73 | 19.13 | -4.19 | 21.71 |\n", - "| IBEX35 (Set 3, 4 time steps, 2-bit) | 56 | Optimized Real Amplitudes | 96 | 3314 | 3523 | -3.67 | 14.48 | -4.11 | 16.44 |\n", - "\n", - "\n", - "\n", - "Results show that the quantum optimizer, with problem-specific ansatzes, effectively identifies efficient investment strategies across various portfolio types." - ] - }, - { - "cell_type": "markdown", - "id": "2db3bd86-393e-4e88-851c-fd496f956aed", - "metadata": {}, - "source": [ - "Below we detail both the population size and the number of generations specified in the `optimizer_options` dictionary. All other parameters were set to their default values.\n", - "\n", - "| **Example** | ``population_size`` | ``num_generations`` |\n", - "|----------------------------|----------------------|----------------------|\n", - "| Mixed Assets Portfolio | 90 | 20 |\n", - "| Mixed Assets Portfolio | 92 | 20 |\n", - "| Oil Derivatives Portfolio | 120 | 20 |\n", - "| IBEX35 Portfolio | 40 | 20 |\n", - "\n", - "The number of generations was set to 20, as this value was found to be sufficient to reach convergence. Additionally, the default values for the optimizer's internal parameters were left unchanged, as they consistently provided good performance and are generally recommended by the literature and implementation guidelines." - ] - }, - { - "cell_type": "markdown", - "id": "021187a8-c6f9-4f31-89f8-32dbb85ec5f6", - "metadata": {}, - "source": [ - "# Get support\n", - "If you need help, you can send an email to qpo.support@globaldataquantum.com. In your message, provide the function job ID." - ] - }, - { - "cell_type": "markdown", - "id": "0a6148bb-1b04-4ad8-bbaf-3cba2b41b037", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - "* Read [the associated research paper](https://arxiv.org/pdf/2412.19150).\n", - "* - Visit the [API reference](/docs/api/functions/global-data-quantum-optimizer) for this Qiskit Function.\n", - "* Request access to the function by filling in [this form](https://globaldatum.io/qiskit-function/#form).\n", - "* Try the [Dynamic Portfolio Optimization](/docs/tutorials/global-data-quantum-optimizer) tutorial.\n", - "\n", - "" - ] } ], "metadata": { diff --git a/docs/functions/global-data-quantum-optimizer/index.ipynb b/docs/functions/global-data-quantum-optimizer/index.ipynb new file mode 100644 index 000000000000..fc3c6ede9864 --- /dev/null +++ b/docs/functions/global-data-quantum-optimizer/index.ipynb @@ -0,0 +1,173 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "7b51ae77-8333-41c8-b6e1-90f2155a7cb7", + "metadata": {}, + "source": [ + "---\n", + "title: Quantum Portfolio Optimizer - A Qiskit Function by Global Data Quantum\n", + "description: A Qiskit Function to solve Dynamic Portfolio Optimization problems using a fine-tuned implementation of the VQE.\n", + "---\n", + "\n", + "\n", + "# Quantum Portfolio Optimizer: A Qiskit Function by Global Data Quantum\n", + "\n", + "{/* cspell:ignore rebalance, GBPJPY, TMBMKDE */}\n", + "\n", + "*See the [API reference](/docs/api/functions/global-data-quantum-optimizer)*" + ] + }, + { + "cell_type": "markdown", + "id": "0466d79d-52b1-4ae4-bdbe-94357784cf7f", + "metadata": {}, + "source": [ + "\n", + "Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "f350e597-000e-4c64-8e5d-c5b95851d26c", + "metadata": {}, + "source": [ + "## Overview\n", + "\n", + "The Quantum Portfolio Optimizer is a Qiskit Function that tackles the dynamic portfolio optimization problem, a standard problem in finance that aims to rebalance periodic investments across a set of assets, to maximize returns and minimize risks. By deploying cutting-edge quantum optimization techniques, this function simplifies the process so that users, with no expertise in quantum computing, can benefit from its advantages in finding optimal investment trajectories. Ideal for portfolio managers, researchers in quantitative finance, and individual investors, this tool enables back-testing of trading strategies in portfolio optimization." + ] + }, + { + "cell_type": "markdown", + "id": "977a893a-9bbe-47f9-b4be-d9f6b8d27a72", + "metadata": {}, + "source": [ + "## Function description" + ] + }, + { + "cell_type": "markdown", + "id": "9038f89a-7452-45bf-a96c-8a5ba8b061d0", + "metadata": {}, + "source": [ + "The Quantum Portfolio Optimizer function uses the Variational Quantum Eigensolver (VQE) algorithm to solve a Quadratic Unconstrained Binary Optimization (QUBO) problem, addressing dynamic portfolio optimization problems. Users simply need to provide the asset price data and define the investment constraint, then the function runs the quantum optimization process that returns a set of optimized investment trajectories.\n", + "\n", + "The process consists of four main stages. First, the input data is mapped to a quantum-compatible problem, constructing the QUBO of the dynamic portfolio optimization problem, and transforming it into a quantum operator (Ising Hamiltonian). Next, the input problem and the VQE algorithm are adapted to be run in the quantum hardware. The VQE algorithm is then run on the quantum hardware, and finally, the results are post-processed to provide the optimal investment trajectories. The system also includes a noise-aware ([SQD](/docs/guides/qiskit-addons-sqd)-based) post-processing to maximize the quality of the output.\n", + "\n", + "This Qiskit Function is based on the [published manuscript](https://arxiv.org/abs/2412.19150) by Global Data Quantum." + ] + }, + { + "cell_type": "markdown", + "id": "3667fa72-ebef-476a-94a1-553389889623", + "metadata": {}, + "source": [ + "![Visualization of the workflow of the function](/docs/images/guides/global-data-quantum-optimizer/function_workflow.svg)" + ] + }, + { + "cell_type": "markdown", + "id": "de293919-a802-4ebe-95e3-173083268741", + "metadata": {}, + "source": [ + "# Benchmarks" + ] + }, + { + "cell_type": "markdown", + "id": "bb44f36c-de99-44ed-921b-003ec3030e86", + "metadata": {}, + "source": [ + "This function was tested under different configurations of resolution qubits, ansatz circuits, and groupings of assets from various sectors: a mix of different assets (Set 1), oil derivatives (Set 2), and IBEX35 (Set 3). See more details in the following table.\n", + "\n", + "| Set | Date | Assets |\n", + "|-----------|------------|------------------------------------------------------------------------|\n", + "| **Set 1** | 01/01/2023 | 8801.T, CL=F, GBPJPY=X, ITX.MC, META, TMBMKDE-10Y, XS2239553048 |\n", + "| **Set 2** | 01/06/2023 | CL=F, BZ=F, HO=F, NG=F, XOM, RB=F, 2222.SR |\n", + "| **Set 3** | 01/11/2022 | ACS.MC, ITX.MC, FER.MC, ELE.MC, SCYR.MC, AENA.MC, AMS.MC |\n", + "\n", + "Two key metrics were used to evaluate solution quality.\n", + "1. The objective cost, which measures optimization efficiency by comparing the cost function value from each experiment with results from Gurobi (free version).\n", + "2. The Sharpe ratio, which captures the risk-adjusted return of each portfolio, offering insight into the financial performance of the solutions.\n", + "\n", + "Together, these metrics benchmark both computational and financial aspects of the quantum-generated portfolios.\n", + "\n", + "\n", + "| Example | Qubits | Ansatz | Depth | Runtime Usage (s) | Total usage (s) | Objective cost | Sharpe | Gurobi objective cost | Gurobi Sharpe |\n", + "|-------------------------------|--------|-------------------------------|--------|-------------------|------------------|----------------|--------|------------------------|----------------|\n", + "| Mixed Assets (Set 1, 4 time steps, 4-bit) | 112 | Tailored | 83 | 12735 | 13095 | -3.78 | 24.82 | -4.25 | 24.71 |\n", + "| Mixed Assets (Set 1,4 time steps, 4 time steps, 4-bit) | 112 | Real Amplitudes | 359 | 11739 | 11903 | -3.39 | 23.64 | -4.25 | 24.71 |\n", + "| Oil Derivatives (Set 2, 4 time steps, 3-bit)| 84 | Optimized Real Amplitudes | 78 | 6180 | 6350 | -3.73 | 19.13 | -4.19 | 21.71 |\n", + "| IBEX35 (Set 3, 4 time steps, 2-bit) | 56 | Optimized Real Amplitudes | 96 | 3314 | 3523 | -3.67 | 14.48 | -4.11 | 16.44 |\n", + "\n", + "\n", + "\n", + "Results show that the quantum optimizer, with problem-specific ansatzes, effectively identifies efficient investment strategies across various portfolio types." + ] + }, + { + "cell_type": "markdown", + "id": "2db3bd86-393e-4e88-851c-fd496f956aed", + "metadata": {}, + "source": [ + "Below we detail both the population size and the number of generations specified in the `optimizer_options` dictionary. All other parameters were set to their default values.\n", + "\n", + "| **Example** | ``population_size`` | ``num_generations`` |\n", + "|----------------------------|----------------------|----------------------|\n", + "| Mixed Assets Portfolio | 90 | 20 |\n", + "| Mixed Assets Portfolio | 92 | 20 |\n", + "| Oil Derivatives Portfolio | 120 | 20 |\n", + "| IBEX35 Portfolio | 40 | 20 |\n", + "\n", + "The number of generations was set to 20, as this value was found to be sufficient to reach convergence. Additionally, the default values for the optimizer's internal parameters were left unchanged, as they consistently provided good performance and are generally recommended by the literature and implementation guidelines." + ] + }, + { + "cell_type": "markdown", + "id": "021187a8-c6f9-4f31-89f8-32dbb85ec5f6", + "metadata": {}, + "source": [ + "# Get support\n", + "If you need help, you can send an email to qpo.support@globaldataquantum.com. In your message, provide the function job ID." + ] + }, + { + "cell_type": "markdown", + "id": "0a6148bb-1b04-4ad8-bbaf-3cba2b41b037", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + "* Read [the associated research paper](https://arxiv.org/pdf/2412.19150).\n", + "* - Visit the [API reference](/docs/api/functions/global-data-quantum-optimizer) for this Qiskit Function.\n", + "* Request access to the function by filling in [this form](https://globaldatum.io/qiskit-function/#form).\n", + "* Try the [Dynamic Portfolio Optimization](/docs/tutorials/global-data-quantum-optimizer) tutorial.\n", + "\n", + "" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/functions/global-data-quantum-optimizer/performance-tuning.mdx b/docs/functions/global-data-quantum-optimizer/performance-tuning.mdx new file mode 100644 index 000000000000..a5e38a674863 --- /dev/null +++ b/docs/functions/global-data-quantum-optimizer/performance-tuning.mdx @@ -0,0 +1,28 @@ +--- +title: Advanced techniques with the Quantum Portfolio Optimizer +description: Practical guidance for configuring ansatz, optimizer, and QUBO settings for the Quantum Portfolio Optimizer. +--- + +*Global Data Quantum is encouraged to expand this page with vendor-specific tuning guidance. The suggestions below are derived from the API reference and are intended as a starting point.* + +## QUBO settings: resolution qubits + +`qubo_settings` controls how the portfolio problem is encoded as a QUBO. The number of resolution qubits determines how finely asset weights can be represented — more qubits improve precision but increase circuit size. The benchmark data on the Overview page shows how this tradeoff plays out in practice; use it as a starting point for sizing. + +## Ansatz selection + +`ansatz_settings` supports multiple ansatz types including `'Tailored'`. The `'Tailored'` ansatz is adapted to the problem structure and generally outperforms a generic hardware-efficient ansatz for portfolio problems. Global Data Quantum is encouraged to document the other available types and when to use each. + +## Optimizer settings + +`optimizer_settings` exposes population size, number of generations, and related parameters for the classical optimizer. The benchmarks show that increasing population size and generations improves solution quality — document the recommended ranges for different portfolio sizes here. + +## Warm-starting with previous_session_id + +If you have a previous run at a lower resolution, pass its `previous_session_id` to warm-start the optimizer. This can significantly reduce the number of iterations needed to converge. + +## Post-processing + +`apply_postprocess=True` applies classical post-processing to improve the solution. This is recommended for most use cases and adds negligible overhead. + +See the [API reference](/docs/api/functions/global-data-quantum-optimizer) for full parameter details. diff --git a/docs/functions/index.ipynb b/docs/functions/index.ipynb deleted file mode 100644 index ea08514b9a0b..000000000000 --- a/docs/functions/index.ipynb +++ /dev/null @@ -1,137 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "2ee21f3f-2a40-486f-9721-d8a358a87aa1", - "metadata": {}, - "source": [ - "---\n", - "title: Introduction to Qiskit Functions\n", - "description: Explore IBM Qiskit Functions Catalog, abstracted circuit function and application function services designed to accelerate research and application prototyping.\n", - "---\n", - "\n", - "\n", - "{/* cspell:ignore Jarman, HIVQE, Cadavid, Chandarana, Leclerc, Sachdeva, HUBO, Filippov, Downfolding, Aharonov, Mundada, Yamauchi, supersymmetric, Paterakis, Gharibyan, Jaffali, Pellow */}" - ] - }, - { - "cell_type": "markdown", - "id": "97b94d47-ba58-4251-91f2-93097e50f2c9", - "metadata": {}, - "source": [ - "# Introduction to Qiskit Functions\n", - "\n", - "* Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "a4c425ca-c6c6-4232-b4b9-b2a365d10ad9", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [ - "\n", - "\n", - "\n", - "The code on this page was developed using the following requirements.\n", - "We recommend using these versions or newer.\n", - "\n", - "```\n", - "qiskit[all]~=1.4.1\n", - "qiskit-ibm-runtime~=0.37.0\n", - "qiskit-ibm-catalog~=0.4\n", - "```\n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "1fe03d0f-c7bb-439b-b98e-91ca400b62fc", - "metadata": {}, - "source": [ - "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.\n", - "\n", - "![Overview of Qiskit Functions](/docs/images/guides/functions/functions-overview.svg)\n", - "Functions come in two forms:\n", - "\n", - "| Type | What does it do? | Example inputs and outputs | Who is it for? |\n", - "| - | - | - | - |\n", - "| Circuit function | Simplified interface for running circuits. Abstracts transpilation, error suppression, and error mitigation | **Input**: Abstract `PUB` objects
**Output**: Mitigated expectation values | Researchers using Qiskit to discover new algorithms and applications, without needing to focus on optimizing for hardware or handling error. Circuit functions can be used to build custom application functions. |\n", - "| Application function | Covers higher-level tasks, such as exploring algorithms and domain-specific use cases. Abstracts quantum workflow to solve tasks, with classical inputs and outputs | **Input**: Molecules, graphs
**Output**: Ground + excited state energy, optimal values for cost function | Researchers in non-quantum domains, integrating quantum into existing large-scale classical workflows, without needing to map classical data to quantum circuits. |" - ] - }, - { - "cell_type": "markdown", - "id": "5e5b0531-f286-4573-8b1e-664ca5496d2d", - "metadata": {}, - "source": [ - "Functions are provided by IBM® and third-party partners. Each is performant for specific workload characteristics and has unique performance-tuning options.\n", - "\n", - "## Overview of available functions\n", - "\n", - "\n", - "### Circuit functions\n", - "\n", - "| Name | Provider | Recommended use | Unique benefits |\n", - "|---|---|---|---|\n", - "| Tensor-Network Error Mitigation

  • [Guide](/docs/guides/algorithmiq-tem)
  • [API reference](/docs/api/functions/algorithmiq-tem)
| Algorithmiq | Workloads that have low-weight observables and loop-free circuits. | Reduces measurement overhead and variance, outperforming standard error mitigation baselines such as Zero Noise Extrapolation (ZNE) and Probabilistic Error Cancellation (PEC) for relevant circuit classes. |\n", - "| QESEM: Error Suppression and Error Mitigation

  • [Guide](/docs/guides/qedma-qesem)
  • [API reference](/docs/api/functions/qedma-qesem)
| Qedma | Workloads that include circuits with fractional or parameterized gates, high-weight observables, and workflows that require unbiased expectation values and accurate runtime estimates. | Produces unbiased expectation values with lower variance and resource overhead, outperforming ZNE and PEC for relevant circuit classes. |\n", - "| Performance Management

  • [Guide](/docs/guides/q-ctrl-performance-management)
  • [API reference](/docs/api/functions/q-ctrl-performance-management)
| Q-CTRL | Workloads that contain parametric circuits, deep circuits, or require many circuit executions. | Automatically applies AI-driven error suppression to quantum algorithms, maximizing the performance of IBM devices to deliver accurate results while reducing the number of shots, compute time, and cost required.

Zero-overhead method that improves execution accuracy for the Sampler and the Estimator primitives, compatible with any weight of observables. |\n", - "\n", - "\n", - "### Application functions\n", - "\n", - "| Name | Provider | Recommended use | Unique benefits |\n", - "|---|---|---|---|\n", - "| QUICK-PDE

  • [Guide](/docs/guides/colibritd-pde)
  • [API reference](/docs/api/functions/colibritd-pde)
| ColibriTD | Use quantum computation for multi-physics PDEs.

Prepare simulation workflows for quantum hardware, while keeping full control over both quantum and physical modeling parameters. | Offers a robust hybrid VQA framework that delivers precise, scalable PDE solutions through advanced solution encoding and spectral methods, making it an ideal entry point for teams trying to build quantum-ready simulation capabilities. |\n", - "| Quantum Portfolio Optimizer

  • [Guide](/docs/guides/global-data-quantum-optimizer)
  • [API reference](/docs/api/functions/global-data-quantum-optimizer)
| Global Data Quantum | Workloads for financial optimization, seeking optimal portfolio strategies over time while minimizing risk and maximizing returns, enabling trading strategy back-testing. | Solves combinatorial optimization problems through a highly specialized adaptation of the VQE quantum algorithm for this financial use case, using optimized execution strategies and optimizers, along with noise-aware error mitigation techniques tailored to portfolio optimization. |\n", - "| HI-VQE Chemistry

  • [Guide](/docs/guides/qunova-chemistry)
  • [API reference](/docs/api/functions/qunova-chemistry)
| Qunova Computing | Workloads in computational chemistry, molecular simulation, materials science, or any Hamiltonian simulation that require solving many-body electronic structure problems. | Solves molecular electronic structures by using enhanced SQD with achieving chemical accuracy (1 kcal/mol, 1.6 mHa) for problems modeled with 40 to 60 qubits, outperforming some classical solutions on supercomputers or standard SQD in convergence speed or accuracy, respectively, by orders of magnitude. |\n", - "| Iskay Quantum Optimizer

  • [Guide](/docs/guides/kipu-optimization)
  • [API reference](/docs/api/functions/kipu-optimization)
| Kipu Quantum | Optimization workloads such as scheduling, logistics, routing, and QUBO/HUBO problems.

| Integrated tunable classical pre- and post-processing methods for the quantum optimization routine.

Delivers runtime advantage over classical solvers (CPLEX, simulated annealing, and tabu search) on selected HUBO benchmarks.

Market Split `ms_5_100`, a hard challenge, solved within hours (see [this tutorial](/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer)). |\n", - "| Singularity Machine Learning

  • [Guide](/docs/guides/multiverse-computing-singularity)
  • [API reference](/docs/api/functions/multiverse-computing-singularity)
| Multiverse Computing | Classical machine learning classification workflows that could benefit from improved accuracy or computational efficiency by leveraging quantum optimization executed on IBM hardware. | Delivers accuracy comparable to or exceeding classical models such as Random Forest or XGBoost, while operating with significantly fewer learners and a more compact ensemble.

Powered by quantum-optimized voting, it selects the most informative learners and refines decision boundaries, resulting in greater efficiency, reduced model complexity, and more robust performance. |\n", - "| Optimization Solver

  • [Guide](/docs/guides/q-ctrl-optimization-solver)
  • [API reference](/docs/api/functions/q-ctrl-optimization-solver)
| Q-CTRL | Binary optimization problems or any combinatorial problem that can be mapped to a binary cost function.

Cost functions of any order and problem sizes up to the maximum device scale are supported. | Noise-aware, end-to-end quantum optimization solution that enables inputs of high-level problem definitions and automatically finds accurate solutions to classically challenging combinatorial problems on utility-scale quantum hardware.

It abstracts away complexity by handling error suppression, efficient mapping, and hybrid quantum-classical optimization to solve optimization tasks at full device scale without deep quantum expertise. |\n" - ] - }, - { - "cell_type": "markdown", - "id": "709b39ca-5dbd-42c0-830c-1248c2e5d63c", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - "\n", - "- [Explore circuit functions](/docs/guides/algorithmiq-tem) to build new algorithms and applications, without needing to manage transpilation or error handling.\n", - "- [Explore application functions](/docs/guides/q-ctrl-optimization-solver) to solve domain-specific tasks, with classical inputs and outputs.\n", - "- See the [API reference documentation](/docs/api/functions/index) for Qiskit Functions.\n", - "- For hands-on experience, try out some [tutorials](/docs/tutorials/index#leverage-qiskit-capabilities) that demonstrate Qiskit Functions.\n", - "" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3" - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/functions/kipu-optimization/_toc.json b/docs/functions/kipu-optimization/_toc.json new file mode 100644 index 000000000000..c0b32d026f3c --- /dev/null +++ b/docs/functions/kipu-optimization/_toc.json @@ -0,0 +1,50 @@ +{ + "parentUrl": "/docs/guides/functions", + "parentLabel": "Qiskit Functions", + "title": "Iskay Quantum Optimizer: A Qiskit Function by Kipu Quantum", + "collapsed": true, + "children": [ + { + "title": "", + "collapsible": false, + "children": [ + { + "title": "Overview", + "url": "/docs/functions/kipu-optimization" + }, + { + "title": "Get started", + "url": "/docs/functions/kipu-optimization/get-started" + }, + { + "title": "Advanced techniques with the Iskay Quantum Optimizer", + "url": "/docs/functions/kipu-optimization/performance-tuning" + }, + { + "title": "Changelog", + "url": "/docs/functions/kipu-optimization/changelog" + } + ] + }, + { + "title": "Tutorials", + "collapsible": false, + "children": [ + { + "title": "Solve the Market Split problem with Kipu Quantum's Iskay Quantum Optimizer", + "url": "/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer" + } + ] + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "/docs/api/functions/kipu-optimization" + } + ] + } + ] +} diff --git a/docs/functions/kipu-optimization/changelog.mdx b/docs/functions/kipu-optimization/changelog.mdx new file mode 100644 index 000000000000..b30e736fa5f9 --- /dev/null +++ b/docs/functions/kipu-optimization/changelog.mdx @@ -0,0 +1,6 @@ +--- +title: Changelog +description: Changelog for the Iskay Quantum Optimizer. +--- + +*This section is under development. Kipu Quantum is encouraged to maintain a changelog here as new features and updates are released.* diff --git a/docs/functions/kipu-optimization/get-started.ipynb b/docs/functions/kipu-optimization/get-started.ipynb new file mode 100644 index 000000000000..e01008566073 --- /dev/null +++ b/docs/functions/kipu-optimization/get-started.ipynb @@ -0,0 +1,448 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "page-frontmatter", + "metadata": {}, + "source": [ + "---\ntitle: Get started with the Iskay Quantum Optimizer\ndescription: Get started with the Iskay Quantum Optimizer — authenticate, load the function, and run optimization examples.\n---" + ] + }, + { + "cell_type": "markdown", + "id": "73390a19", + "metadata": {}, + "source": [ + "## Setup and load function\n\nIn this documentation, we will go through the steps of using the Iskay Quantum Optimizer. In the process we will quickly show how to load the function from the catalog and how to convert your problem to a valid input, all while showing how you can experiment with different optional parameters.\n\nFor a more detailed example, please check out the tutorial [Solve the Market Split problem with Kipu Quantum's Iskay Quantum Optimizer](/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer), where we work through the whole process of using Iskay Solver to address the Market Split problem, which represents a real-world resource allocation challenge where markets must be partitioned into balanced sales regions to meet exact demand targets.\n\nAuthenticate using your API key, found on the [IBM Quantum Platform dashboard](http://quantum.cloud.ibm.com/), and select the Qiskit Function as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0e4fd124", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# ruff: noqa: F821" + ] + }, + { + "cell_type": "markdown", + "id": "e5cd4ac8", + "metadata": {}, + "source": [ + "\n", + "The following code assumes that you have saved your credentials. If you have not, follow the instructions in [save your IBM Cloud account](/docs/guides/functions#install-qiskit-functions-catalog-client) to authenticate with your API key.\n", + "" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "95a715d2", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", + "\n", + "catalog = QiskitFunctionsCatalog(\n", + " channel=\"ibm_quantum_platform\",\n", + " instance=\"INSTANCE_CRN\",\n", + " # For `token`, use the 44-character API_KEY you created\n", + " # and saved from the IBM Quantum Platform Home dashboard\n", + " token=\"YOUR_API_KEY\",\n", + ")\n", + "\n", + "# Access Function\n", + "optimizer = catalog.load(\"kipu-quantum/iskay-quantum-optimizer\")" + ] + }, + { + "cell_type": "markdown", + "id": "kipu-optimization-examples-heading", + "metadata": {}, + "source": [ + "## Run your first workload" + ] + }, + { + "cell_type": "markdown", + "id": "d4ca2590", + "metadata": {}, + "source": [ + "## Example 1: Simple cost function\n", + "\n", + "Consider the cost function in spin formulation:\n", + "$$\n", + "C(x_0, x_1, x_2, x_3, x_4) = 1 + 1.5x_0 + 2x_1 + 1.3x_2 + 2.5x_0x_3 + 3.5x_1x_4 + 4x_0x_1x_2\n", + "$$\n", + "\n", + "where $(x_0, ..., x_4) \\in \\{-1, 1\\}^5$.\n", + "\n", + "The solution to this simple cost function is\n", + "$$\n", + "(x_0, x_1, x_2, x_3, x_4) = (-1, -1, -1, 1, 1)\n", + "$$\n", + "with minimum value $C^{*} = -6$" + ] + }, + { + "cell_type": "markdown", + "id": "a98e8232", + "metadata": {}, + "source": [ + "### 1. Create the objective function\n", + "\n", + "We start by creating a dictionary with the coefficients of the objective function as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "3b4a58b1", + "metadata": {}, + "outputs": [], + "source": [ + "objective_func = {\n", + " \"()\": 1,\n", + " \"(0,)\": 1.5,\n", + " \"(1,)\": 2,\n", + " \"(2,)\": 1.3,\n", + " \"(0, 3)\": 2.5,\n", + " \"(1, 4)\": 3.5,\n", + " \"(0, 1, 2)\": 4,\n", + "}" + ] + }, + { + "cell_type": "markdown", + "id": "ab63b08f", + "metadata": {}, + "source": [ + "### 2. Run the Optimizer\n", + "\n", + "We solve the problem by running the optimizer. Since $(x_0, ..., x_4) \\in \\{-1, 1\\}^5$ we must set `problem_type=spin`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "469ae361", + "metadata": {}, + "outputs": [], + "source": [ + "# Setup options to run the optimizer\n", + "options = {\"shots\": 5000, \"num_iterations\": 5, \"use_session\": True}\n", + "\n", + "arguments = {\n", + " \"problem\": objective_func,\n", + " \"problem_type\": \"spin\",\n", + " \"backend_name\": backend_name, # such as \"ibm_fez\"\n", + " \"options\": options,\n", + "}\n", + "\n", + "job = optimizer.run(**arguments)" + ] + }, + { + "cell_type": "markdown", + "id": "1e3a8542", + "metadata": {}, + "source": [ + "### 3. Retrieve the result\n", + "\n", + "The solution of the optimization problem is provided directly from the optimizer." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2f74d7e2", + "metadata": {}, + "outputs": [], + "source": [ + "print(job.result())" + ] + }, + { + "cell_type": "markdown", + "id": "c4d0a0f8", + "metadata": {}, + "source": [ + "This will show a dictionary of the form:\n", + "\n", + "```\n", + "{'solution': {'0': -1, '1': -1, '2': -1, '3': 1, '4': 1},\n", + " 'solution_info': {'bitstring': '11100',\n", + " 'cost': -13.8,\n", + " 'seed_transpiler': 42,\n", + " 'mapping': {0: 0, 1: 1, 2: 2, 3: 3, 4: 4}},\n", + " 'prob_type': 'spin'}\n", + "```\n", + "\n", + "Notice that the dictionary `solution` displays the result vector $(x_0, x_1, x_2, x_3, x_4) = (-1, -1, -1, 1, 1)$." + ] + }, + { + "cell_type": "markdown", + "id": "7eaa5cac", + "metadata": {}, + "source": [ + "## Example 2: MaxCut\n", + "\n", + "Many graph problems like MaxCut or Maximum independent set are NP-hard problems and ideal candidates for testing quantum algorithms and hardware. This example demonstrates solving the MaxCut problem of a 3-regular graph with the Quantum Optimizer.\n", + "\n", + "To run this example you must install the `networkx` package in addition to the `qiskit-ibm-catalog`. To install it, run the following command:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "9ea6d138", + "metadata": {}, + "outputs": [], + "source": [ + "# %pip install networkx numpy" + ] + }, + { + "cell_type": "markdown", + "id": "0c63487f", + "metadata": {}, + "source": [ + "### 1. Create the objective function\n", + "\n", + "Start by generating a random 3-regular graph. For this graph, we define the objective function of the MaxCut problem." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d1d4017f", + "metadata": {}, + "outputs": [], + "source": [ + "import networkx as nx\n", + "\n", + "# Create a random 3-regular graph\n", + "G = nx.random_regular_graph(3, 10, seed=42)\n", + "\n", + "\n", + "# Create the objective function for MaxCut in Ising formulation\n", + "def graph_to_ising_maxcut(G):\n", + " \"\"\"\n", + " Convert a NetworkX graph to an Ising Hamiltonian for the max-cut problem.\n", + " Args:\n", + " G (networkx.Graph): The input graph.\n", + " Returns:\n", + " dict: The objective function of the Ising model\n", + " \"\"\"\n", + " # Initialize the linear and quadratic coefficients\n", + " objective_func = {}\n", + " # Populate the coefficients\n", + " for i, j in G.edges:\n", + " objective_func[f\"({i}, {j})\"] = 0.5\n", + " return objective_func\n", + "\n", + "\n", + "objective_func = graph_to_ising_maxcut(G)" + ] + }, + { + "cell_type": "markdown", + "id": "3be09664", + "metadata": {}, + "source": [ + "### 2. Run the Optimizer\n", + "\n", + "Solve the problem by running the optimizer." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2499ab67", + "metadata": {}, + "outputs": [], + "source": [ + "options = {\"shots\": 5000, \"num_iterations\": 5, \"use_session\": True}\n", + "\n", + "arguments = {\n", + " \"problem\": objective_func,\n", + " \"problem_type\": \"spin\",\n", + " \"backend_name\": backend_name, # such as \"ibm_fez\"\n", + " \"options\": options,\n", + "}\n", + "\n", + "job = optimizer.run(**arguments)" + ] + }, + { + "cell_type": "markdown", + "id": "3548f6dc", + "metadata": {}, + "source": [ + "### 3. Retrieve the result\n", + "\n", + "Retrieve the result and map the solution bitstring back to the original graph nodes." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "169cbd6e", + "metadata": {}, + "outputs": [], + "source": [ + "print(job.result())" + ] + }, + { + "cell_type": "markdown", + "id": "7f22d66a", + "metadata": {}, + "source": [ + "The solution to the Maxcut problem is directly contained in the `solution` sub-dictionary of the result object" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "38309554", + "metadata": {}, + "outputs": [], + "source": [ + "maxcut_solution = job.result()[\"solution\"]" + ] + }, + { + "cell_type": "markdown", + "id": "19a664c4", + "metadata": {}, + "source": [ + "## Example 3: Benchmark instances" + ] + }, + { + "cell_type": "markdown", + "id": "98545ce3", + "metadata": {}, + "source": [ + "The benchmark instances are available on GitHub: [Kipu benchmark instances](https://github.com/Kipu-Quantum-GmbH/benchmark-instances).\n", + "\n", + "The instances can be loaded using the `pygithub` library. To install it, run the following command:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1d8777e4", + "metadata": {}, + "outputs": [], + "source": [ + "# %pip install pygithub" + ] + }, + { + "cell_type": "markdown", + "id": "e3a03447", + "metadata": {}, + "source": [ + "The paths for the benchmark instances are:\n", + "\n", + "**Maxcut:**\n", + "- `'maxcut/maxcut_regular_3_100_nodes_weighted.json'`\n", + "- `'maxcut/maxcut_regular_3_140_nodes_weighted.json'`\n", + "- `'maxcut/maxcut_regular_3_150_nodes_weighted.json'`\n", + "- `'maxcut/maxcut_regular_4_130_nodes_weighted.json'`\n", + "\n", + "**HUBO:**\n", + "- `'HUBO/hubo1_marrakesh.json'`\n", + "- `'HUBO/hubo2_marrakesh.json'`\n", + "\n", + "To reproduce the performance of the benchmark for the HUBO instances, select the backend `ibm_marrakesh` and set `direct_qubit_mapping` to `True` in the `options` sub-dictionary." + ] + }, + { + "cell_type": "markdown", + "id": "adbed9be", + "metadata": {}, + "source": [ + "The following example runs the Maxcut instance with 150 nodes." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "da681a18", + "metadata": {}, + "outputs": [], + "source": [ + "from github import Github\n", + "import urllib\n", + "import json\n", + "import ast\n", + "\n", + "repo = \"Kipu-Quantum-GmbH/benchmark-instances\"\n", + "path = \"maxcut/maxcut_regular_3_150_nodes_weighted.json\"\n", + "gh = Github()\n", + "repo = gh.get_repo(repo)\n", + "branch = \"main\"\n", + "file = repo.get_contents(urllib.parse.quote(path), ref=branch)\n", + "\n", + "# load json file with benchmark problem\n", + "problem_json = json.loads(file.decoded_content)\n", + "\n", + "# convert objective function to compatible format\n", + "objective_func = {\n", + " key: ast.literal_eval(value) for key, value in problem_json.items()\n", + "}\n", + "\n", + "\n", + "# Setup configuration to run the optimizer\n", + "options = {\n", + " \"shots\": 5_000,\n", + " \"num_iterations\": 5,\n", + " \"use_session\": True,\n", + " \"direct_qubit_mapping\": False,\n", + "}\n", + "\n", + "arguments = {\n", + " \"problem\": objective_func,\n", + " \"problem_type\": \"spin\",\n", + " \"backend_name\": \"\",\n", + " \"options\": options,\n", + "}\n", + "\n", + "job = optimizer.run(**arguments)\n", + "\n", + "result = job.result()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/functions/kipu-optimization/index.ipynb b/docs/functions/kipu-optimization/index.ipynb new file mode 100644 index 000000000000..c9b36fd29169 --- /dev/null +++ b/docs/functions/kipu-optimization/index.ipynb @@ -0,0 +1,189 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "f7d9993f", + "metadata": {}, + "source": [ + "---\n", + "title: Iskay Quantum Optimizer - A Qiskit Function by Kipu Quantum\n", + "description: Efficiently solve optimization problems with Kipu Quantum's Iskay Quantum Optimizer, available on the IBM Qiskit Functions Catalog\n", + "---\n", + "\n", + "{/* cspell:ignore Kipu, DCQO, QUBO, HUBO, counterdiabatic, Iskay, bitflips, Cadavid, Chandarana */}" + ] + }, + { + "cell_type": "markdown", + "id": "dde95705", + "metadata": {}, + "source": [ + "# Iskay Quantum Optimizer - A Qiskit Function by Kipu Quantum\n", + "\n", + "*See the [API reference](/docs/api/functions/kipu-optimization)*" + ] + }, + { + "cell_type": "markdown", + "id": "c60ba821", + "metadata": {}, + "source": [ + "\n", + "* Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", + "\n", + "\n", + "## Overview\n", + "\n", + "With the Iskay Quantum Optimizer by Kipu Quantum, you can tackle complex optimization problems using IBM® quantum computers. This solver leverages Kipu's cutting-edge [bf-DCQO algorithm](https://doi.org/10.48550/arXiv.2409.04477) requiring only the objective function as input to automatically deliver problem solutions. It can handle optimization problems involving up to 156 qubits, enabling the use of all qubits of the IBM quantum devices. The Optimizer uses a 1-to-1 mapping between classical variables and qubits, which allows you to tackle optimization problems with up to 156 binary variables.\n", + "\n", + "The Optimizer enables the solving of unconstrained binary optimization problems. In addition to the commonly used QUBO (Quadratic Unconstrained Binary Optimization) formulation, it also supports higher-order (HUBO) optimization problems. The solver utilizes a non-variational quantum algorithm, performing most of the computation on quantum devices.\n", + "\n", + "The following provides more details about the used algorithm and a brief guide on how to use the function, as well as benchmarking results on various problem instances of different sizes and complexities." + ] + }, + { + "cell_type": "markdown", + "id": "5f761442", + "metadata": {}, + "source": [ + "## Description\n", + "\n", + "The Optimizer is a ready-to-use implementation of cutting-edge quantum optimization algorithms. It solves optimization problems by running highly-compressed quantum circuits on quantum hardware. This compression is achieved by introducing counterdiabatic terms into the underlying time evolution of the quantum system. The algorithm executes several iterations of hardware runs to obtain the final solutions and combines it with post-processing. These steps are seamlessly integrated into the Optimizer's workflow and are executed automatically.\n", + "\n", + "### How does the Quantum Optimizer work?\n", + "This section outlines the basics of the implemented bf-DCQO algorithm. An introduction to the algorithm can also be found on the [Qiskit YouTube channel](https://www.youtube.com/watch?v=33QmsXhIlpU&t=1223s).\n", + "\n", + "The algorithm is based on the time evolution of a quantum system which is transformed over time, where the problem solution is encoded in the ground state of the quantum system at the end of the evolution. According to the [adiabatic theorem](https://en.wikipedia.org/wiki/Adiabatic_theorem), this evolution has to be slow to ensure the system remains in its ground state. Digitizing this evolution is the basis of digitized quantum adiabatic computation (DQA) and the infamous QAOA algorithm. However, the required slow evolution is not feasible for increasing problem sizes since it results in an increasing circuit depth. By using counterdiabatic protocols, you can suppress unwanted excitations occurring during short evolution times while remaining in the ground state. Here, digitizing this shorter evolution time results in quantum circuits with shorter depth and fewer entangling gates.\n", + "\n", + "The circuits of the bf-DCQO algorithms typically use up to ten times fewer entangling gates than DQA, and three to four times fewer entangling gates than standard QAOA implementations. Because of the smaller number of gates, fewer errors occur during the circuit execution on hardware. Hence, the optimizer does not require using techniques like error suppression or error mitigation. Implementing them in future versions can enhance the solution quality even further.\n", + "\n", + "Although the bf-DCQO algorithm uses iterations, it is non-variational. After each iteration of the algorithm, the distribution of states is measured. The obtained distribution is used to calculate a so-called bias-field. The bias-field allows starting the next iteration from an energy state near the previously found solution. In this way, the algorithm moves with each iteration to solutions of lower energy. Typically, approximately ten iterations are sufficient to converge to a solution, in total requiring a much lower number of iterations than variational algorithms, which is on the order of approximately 100 iterations.\n", + "\n", + "The optimizer combines the bf-DCQO algorithm with classical post-processing. After measuring the distribution of states, a local search is performed. During the local search, the bits of the measured solution are randomly flipped. After the flip, the energy of the new bitstring is evaluated. If the energy is lower, the bitstring is kept as the new solution. The local search only scales linearly with the number of qubits; hence, it is computationally cheap. Since the post-processing corrects local bitflips, it compensates for bit-flip errors that often are the result of hardware imperfections and readout errors.\n", + "\n", + "### Workflow\n", + "\n", + "A schematic of the workflow of the Quantum Optimizer follows.\n", + "\n", + "![Workflow](/docs/images/guides/kipu-optimization/workflow.svg \"Workflow of the Quantum Optimizer\")\n", + "\n", + "By using the Quantum Optimizer, solving an optimization problem on quantum hardware can be reduced to\n", + "* Formulate the objective function of the problem\n", + "* Access the Optimizer via Qiskit Functions\n", + "* Run the Optimizer and collect the result" + ] + }, + { + "cell_type": "markdown", + "id": "b34fe075", + "metadata": {}, + "source": [ + "## Benchmarks\n", + "\n", + "The benchmark metrics below show that the Optimizer effectively addresses problems involving up to 156 qubits and offer a general overview of the optimizer's accuracy and scalability across different problem types. Note that actual performance metrics may vary depending on specific problem characteristics, such as the number of variables, the density and locality of terms in the objective function, and the polynomial order.\n", + "\n", + "The following table includes the approximation ratio (AR), a metric defined as follows:\n", + "$$\n", + "AR = \\frac{C^{*} - C_\\textrm{max}}{C_{\\textrm{min}} - C_{\\textrm{max}}},\n", + "$$\n", + "where $C$ is the objective function, $C_{\\textrm{min}}$, $C_{\\textrm{max}}$ are its minimum and maximum values, and $C^{*}$ is the cost of the best solution found, respectively. Therefore, AR=100\\% means that the ground state of the problem has been obtained.\n", + "\n", + "\n", + "| Example | Number of qubits | Approximation Ratio | Total time (s) | Runtime usage (s) | Total Number of shots | Number of iterations |\n", + "| ----------------- | :--------------: | :------: | :------------: | :---------------: | :-------------------: | :------------------: |\n", + "| Unweighted MaxCut | 28 | 100% | 180 | 30 | 30k | 5 |\n", + "| Unweighted MaxCut | 30 | 100% | 180 | 30 | 30k | 5 |\n", + "| Unweighted MaxCut | 32 | 100% | 180 | 30 | 30k | 5 |\n", + "| Unweighted MaxCut | 80 | 100% | 480 | 60 | 90k | 9 |\n", + "| Unweighted MaxCut | 100 | 100% | 330 | 60 | 60k | 6 |\n", + "| Unweighted MaxCut | 120 | 100% | 370 | 60 | 60k | 6 |\n", + "| HUBO 1 | 156 | 100% | 600 | 70 | 100k | 10 |\n", + "| HUBO 2 | 156 | 100% | 600 | 70 | 100k | 10 |\n", + "\n", + "- The MaxCut instances with 28, 30, and 32 qubits were run on ibm_sherbrooke. Instances with 80, 100, and 120 were run on a Heron r2 processor.\n", + "- The HUBO instances were also run on a Heron r2 processor.\n", + "\n", + "All the benchmark instances are accessible on GitHub (see [Kipu benchmark instances](https://github.com/Kipu-Quantum-GmbH/benchmark-instances)). An example to run these instances can be found in [Example 3: Benchmark instances](#example-3-benchmark-instances)." + ] + }, + { + "cell_type": "markdown", + "id": "664476ff", + "metadata": {}, + "source": [ + "## Use cases\n", + "\n", + "Typical use cases for the Optimization solver are combinatorial optimization problems. You can solve problems from many industries like finance, pharmaceutics, or logistics. Some examples follow.\n", + "* Portfolio optimization (QUBO): [scientific publication](https://doi.org/10.1103/PhysRevApplied.22.054037) and [white paper](https://kipu-quantum.com/zope64/kipu_2024/content/e3915/e3916/e4187/White-Paper-2-Financial-modeling-on-quantum-computers-using-digitally-compressed-algorithms-1.pdf)\n", + "* Protein folding (HUBO): [scientific publication](https://doi.org/10.1103/PhysRevApplied.20.014024)\n", + "* Logistics scheduling (QUBO): [scientific publication](https://doi.org/10.1103/PhysRevApplied.22.064068)\n", + "* Network optimization: [webinar](https://www.youtube.com/watch?v=w5SrCIK88No)\n", + "* Market split (QUBO): [tutorial](/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer)\n", + "\n", + "If you are interested in tackling a specific use case and develop a dedicated mapping, we can assist you. [Contact us](https://share-eu1.hsforms.com/2Ff8cgWvTR9ukT_fPoaNhDw2dqpz5)." + ] + }, + { + "cell_type": "markdown", + "id": "e9ec2e67", + "metadata": {}, + "source": [ + "## Get support\n", + "\n", + "For support, contact support@kipu-quantum.com." + ] + }, + { + "cell_type": "markdown", + "id": "5a6a25c8", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "- [Request access to the Quantum Optimizer by Kipu Quantum](https://share-eu1.hsforms.com/2Ff8cgWvTR9ukT_fPoaNhDw2dqpz5).\n", + "- Visit the [API reference](/docs/api/functions/kipu-optimization) for this Qiskit Function.\n", + "- Try the [Solve the Market Split problem with Kipu Quantum's Iskay Quantum Optimizer](/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer) tutorial.\n", + "- Review [Romero, S. V., et al. (2025). Bias-Field Digitized Counterdiabatic Quantum Algorithm for Higher-Order Binary Optimization. arXiv preprint arXiv:2409.04477](https://arxiv.org/abs/2409.04477).\n", + "- Review [Cadavid, A. G., et al. (2024). Bias-field digitized counterdiabatic quantum optimization. arXiv preprint arXiv:2405.13898](https://arxiv.org/abs/2405.13898).\n", + "- Review [Chandarana, P., et al. (2025). Runtime Quantum Advantage with Digital Quantum Optimization. arXiv preprint arXiv:2505.08663](https://arxiv.org/abs/2505.08663)." + ] + }, + { + "cell_type": "markdown", + "id": "f73ef6c4", + "metadata": {}, + "source": [ + "## Additional information" + ] + }, + { + "cell_type": "markdown", + "id": "52b5221c", + "metadata": {}, + "source": [ + "Iskay, like our company name Kipu Quantum, is a Peruvian word. Although we are a startup from Germany, these words come from the native country of one of our co-founders, where the Quipu was one of the very first calculation machines developed by mankind 2000 years BCE." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/functions/kipu-optimization/performance-tuning.ipynb b/docs/functions/kipu-optimization/performance-tuning.ipynb new file mode 100644 index 000000000000..7e9370c00b04 --- /dev/null +++ b/docs/functions/kipu-optimization/performance-tuning.ipynb @@ -0,0 +1,71 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "page-frontmatter", + "metadata": {}, + "source": [ + "---\ntitle: Advanced techniques with the Iskay Quantum Optimizer\ndescription: Custom configuration options for the Iskay Quantum Optimizer.\n---" + ] + }, + { + "cell_type": "markdown", + "id": "4a8e24f7", + "metadata": {}, + "source": [ + "## Custom configuration example\n", + "\n", + "Here's how you might configure Iskay with different settings:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "712dbae3", + "metadata": {}, + "outputs": [], + "source": [ + "custom_options = {\n", + " \"shots\": 15_000, # Higher shot count for better statistics\n", + " \"num_iterations\": 12, # More iterations for solution refinement\n", + " \"preprocessing_level\": 1, # Light preprocessing for problem simplification\n", + " \"postprocessing_level\": 2, # Maximum postprocessing for solution quality\n", + " \"transpilation_level\": 3, # Use higher transpilation level to optimize circuit\n", + " \"seed_transpiler\": 42, # Fixed seed for reproducible results\n", + " \"job_tags\": [\"custom_config\"], # Custom tracking tags\n", + "}" + ] + }, + { + "cell_type": "markdown", + "id": "50690350", + "metadata": {}, + "source": [ + "**Seed optimization**: Note that `seed_transpiler` is set to `None` by default. This enables the transpiler's automatic optimization process. When `None`, the system will start a trial with multiple seeds and select the one that produces the best circuit depth, leveraging the full power of the `max_trials` parameter for each transpilation level.\n", + "\n", + "**Transpilation level performance**: Increasing the number of `max_trials` with higher values for `transpilation_level` will unavoidably increase the transpilation time, but it might not always change the final circuit - this depends heavily on the specific circuit structure and complexity. For some circuits/problems, however, the difference between 10 trials (level 1) and 50 trials (level 5) can be dramatic, so exploring these parameters might be the key to successfully finding a solution." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/functions/multiverse-computing-singularity/_toc.json b/docs/functions/multiverse-computing-singularity/_toc.json new file mode 100644 index 000000000000..5d450e88e46f --- /dev/null +++ b/docs/functions/multiverse-computing-singularity/_toc.json @@ -0,0 +1,50 @@ +{ + "parentUrl": "/docs/guides/functions", + "parentLabel": "Qiskit Functions", + "title": "Singularity Machine Learning: A Qiskit Function by Multiverse Computing", + "collapsed": true, + "children": [ + { + "title": "", + "collapsible": false, + "children": [ + { + "title": "Overview", + "url": "/docs/functions/multiverse-computing-singularity" + }, + { + "title": "Get started", + "url": "/docs/functions/multiverse-computing-singularity/get-started" + }, + { + "title": "Advanced techniques with Singularity Machine Learning", + "url": "/docs/functions/multiverse-computing-singularity/performance-tuning" + }, + { + "title": "Changelog", + "url": "/docs/functions/multiverse-computing-singularity/changelog" + } + ] + }, + { + "title": "Tutorials", + "collapsible": false, + "children": [ + { + "title": "Hybrid quantum-enhanced ensemble classification (grid stability workflow)", + "url": "/docs/tutorials/sml-classification" + } + ] + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "/docs/api/functions/multiverse-computing-singularity" + } + ] + } + ] +} diff --git a/docs/functions/multiverse-computing-singularity/changelog.mdx b/docs/functions/multiverse-computing-singularity/changelog.mdx new file mode 100644 index 000000000000..7d2eab42a4b8 --- /dev/null +++ b/docs/functions/multiverse-computing-singularity/changelog.mdx @@ -0,0 +1,48 @@ +--- +title: Changelog +description: Changelog for Singularity Machine Learning. +--- + +### 4 June 2025 +- Upgraded `QuantumEnhancedEnsembleClassifier` with the following updates: + - Added onsite/alpha regularization. You can specify `regularization_type` to be `onsite` or `alpha` + - Added auto-regularization. You can set `regularization` to `auto` to use auto-regularization + - Added `optimization_data` parameter to the `fit` method to choose optimization data for quantum optimization. You can use one of these options: `train`, `validation`, or `both` + - Improved overall performance +- Added detailed status tracking for running jobs + +### 20 May 2025 +- Standardized error handling + +### 18 March 2025 +- Upgraded qiskit-serverless to 0.20.0 and base image to 0.20.1 + +### 14 February 2025 +- Upgraded base image to 0.19.1 + +### 6 February 2025 +- Upgraded qiskit-serverless to 0.19.0 and base image to 0.19.0 + +### 13 November 2024 +- Release of Singularity Machine Learning - Classification + +## Get support + +For any questions, [reach out to Multiverse Computing](mailto:singularity@multiversecomputing.com). + +Be sure to include the following information: + +- The Qiskit Function Job ID (`job.job_id`) +- A detailed description of the issue +- Any relevant error messages or codes +- Steps to reproduce the issue + +## Next steps + + + +- Request access to [Multiverse Computing's Singularity Machine Learning Classification function](https://quantum.cloud.ibm.com/functions?id=multiverse-singularity). +- Visit the [API reference](/docs/api/functions/multiverse-computing-singularity) for this Qiskit Function. +- Review [Leclerc, L., et al. (2023). Financial risk management on a neutral atom quantum processor. Physical Review Research, 5, 043117](https://journals.aps.org/prresearch/pdf/10.1103/PhysRevResearch.5.043117). + + diff --git a/docs/functions/application-functions/multiverse-computing-singularity.ipynb b/docs/functions/multiverse-computing-singularity/get-started.ipynb similarity index 58% rename from docs/functions/application-functions/multiverse-computing-singularity.ipynb rename to docs/functions/multiverse-computing-singularity/get-started.ipynb index f388fda44aa4..dc8306695653 100644 --- a/docs/functions/application-functions/multiverse-computing-singularity.ipynb +++ b/docs/functions/multiverse-computing-singularity/get-started.ipynb @@ -2,127 +2,10 @@ "cells": [ { "cell_type": "markdown", - "id": "fe74e692", + "id": "page-frontmatter", "metadata": {}, "source": [ - "---\n", - "title: Singularity Machine Learning - Classification by Multiverse Computing\n", - "description: A Qiskit Function to create and train a hybrid quantum ensemble classifier from multiple learners and optimizes them for diversity and generalization with QAOA\n", - "---\n", - "\n", - "{/* cspell:ignore hyperparameters, sparsify, sparsification, Leclerc */}" - ] - }, - { - "cell_type": "markdown", - "id": "dde95705", - "metadata": {}, - "source": [ - "# Singularity Machine Learning - Classification: A Qiskit Function by Multiverse Computing\n", - "\n", - "*See the [API reference](/docs/api/functions/multiverse-computing-singularity)*" - ] - }, - { - "cell_type": "markdown", - "id": "99db0bb4", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [ - "{/*\n", - " DO NOT EDIT THIS CELL!!!\n", - " This cell's content is generated automatically by a script. Anything you add\n", - " here will be removed next time the notebook is run. To add new content, create\n", - " a new cell before or after this one.\n", - "*/}\n", - "\n", - "\n", - "\n", - "\n", - "The code on this page was developed using the following requirements.\n", - "We recommend using these versions or newer.\n", - "\n", - "```\n", - "scikit-learn~=1.8.0\n", - "```\n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "9985b8f4", - "metadata": {}, - "source": [ - "\n", - "* Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", - "\n", - "\n", - "## Overview\n", - "\n", - "With the \"Singularity Machine Learning - Classification\" function, you can solve real-world machine learning problems on quantum hardware without requiring quantum expertise. This Application function, based on ensemble methods, is a hybrid classifier. It leverages classical methods like boosting, bagging, and stacking for initial ensemble training. Subsequently, quantum algorithms such as variational quantum eigensolver (VQE) and quantum approximate optimization algorithm (QAOA) are employed to enhance the trained ensemble's diversity, generalization capabilities, and overall complexity.\n", - "\n", - "Unlike other quantum machine learning solutions, this function is capable of handling large-scale datasets with millions of examples and features without being limited by the number of qubits in the target QPU. The number of qubits only determines the size of the ensemble that can be trained. It is also highly flexible, and can be used to solve classification problems across a wide range of domains, including finance, healthcare, and cybersecurity." - ] - }, - { - "cell_type": "markdown", - "id": "353e72a4", - "metadata": {}, - "source": [ - "It consistently achieves high accuracies on classically challenging problems involving high-dimensional, noisy, and imbalanced datasets." - ] - }, - { - "cell_type": "markdown", - "id": "339c5737", - "metadata": {}, - "source": [ - "![How it works](/docs/images/guides/multiverse-computing-singularity/how_it_works.avif)" - ] - }, - { - "cell_type": "markdown", - "id": "0639e5e5", - "metadata": {}, - "source": [ - "It is built for:\n", - "1. Engineers and data scientists at companies seeking to enhance their tech offerings by integrating quantum machine learning into their products and services,\n", - "2. Researchers at quantum research labs exploring quantum machine learning applications and looking to leverage quantum computing for classification tasks, and\n", - "3. Students and teachers at educational institutions in courses like machine learning, and who are looking to demonstrate the advantages of quantum computing.\n", - "\n", - "The following example showcases its various functionalities, including `create`, `list`, `fit`, and `predict`, and demonstrates its usage in a synthetic problem comprising two interleaving half circles, a notoriously challenging problem due to its nonlinear decision boundary." - ] - }, - { - "cell_type": "markdown", - "id": "ccf056e3", - "metadata": {}, - "source": [ - "{/* cspell:ignore quantumly */}\n", - "\n", - "## Function description\n", - "\n", - "This Qiskit Function allows users to solve binary classification problems using Singularity's quantum-enhanced ensemble classifier. Behind the scenes, it uses a hybrid approach to classically train an ensemble of classifiers on the labeled dataset, and then optimize it for maximum diversity and generalization using the Quantum Approximate Optimization Algorithm (QAOA) on IBM® QPUs. Through a user-friendly interface, users can configure a classifier according to their requirements, train it on the dataset of their choice, and use it to make predictions on a previously unseen dataset.\n", - "\n", - "To solve a generic classification problem:\n", - "1. Preprocess the dataset, and split it into training and testing sets. Optionally, you can further split the training set into training and validation sets. This can be achieved using [scikit-learn](https://scikit-learn.org/1.5/modules/generated/sklearn.model_selection.train_test_split.html).\n", - "2. If the training set is imbalanced, you can resample it to balance the classes using [imbalanced-learn](https://imbalanced-learn.org/stable/introduction.html#problem-statement-regarding-imbalanced-data-sets).\n", - "3. Upload the training, validation, and test sets separately to the function's storage using the catalog's `file_upload` method, passing it the relevant path each time.\n", - "4. Initialize the quantum classifier by using the function's `create` action, which accepts hyperparameters such as the number and types of learners, the regularization (lambda value), and optimization options including the number of layers, the type of classical optimizer, the quantum backend, and so on.\n", - "5. Train the quantum classifier on the training set using the function's `fit` action, passing it the labeled training set, and the validation set if applicable.\n", - "6. Make predictions on the previously unseen test set using the function's `predict` action." - ] - }, - { - "cell_type": "markdown", - "id": "26472870", - "metadata": {}, - "source": [ - "---" + "---\ntitle: Get started with Singularity Machine Learning\ndescription: Get started with Singularity Machine Learning — authenticate, load the function, and run classification examples.\n---" ] }, { @@ -130,9 +13,7 @@ "id": "73390a19", "metadata": {}, "source": [ - "## Get started\n", - "\n", - "Authenticate using your [IBM Quantum Platform API key](http://quantum.cloud.ibm.com/), and select the Qiskit Function as follows:" + "## Setup and load function\n\nAuthenticate using your [IBM Quantum Platform API key](http://quantum.cloud.ibm.com/), and select the Qiskit Function as follows:" ] }, { @@ -155,11 +36,7 @@ "id": "e8837f5f", "metadata": {}, "source": [ - "## Examples\n", - "\n", - "### Classify a dataset\n", - "\n", - "In this example, you'll use the \"Singularity Machine Learning - Classification\" function to classify a dataset consisting of two interleaving, moon-shaped half-circles. The dataset is synthetic, two-dimensional, and labeled with binary labels. It is created to be challenging for algorithms such as centroid-based clustering and linear classification." + "## Run your first workload\n\n### Classify a dataset\n\nIn this example, you'll use the \"Singularity Machine Learning - Classification\" function to classify a dataset consisting of two interleaving, moon-shaped half-circles. The dataset is synthetic, two-dimensional, and labeled with binary labels. It is created to be challenging for algorithms such as centroid-based clustering and linear classification." ] }, { @@ -619,82 +496,6 @@ ")\n", "print(\"Usage metadata: \", result[\"metadata\"][\"resource_usage\"])" ] - }, - { - "cell_type": "markdown", - "id": "5cc6f2b3", - "metadata": {}, - "source": [ - "## Benchmarks\n", - "\n", - "These benchmarks show that the classifier can achieve extremely high accuracies on challenging problems. They also show that increasing the number of learners in the ensemble (number of qubits) can lead to increased accuracy.\n", - "\n", - "\"Classical accuracy\" refers to the accuracy obtained using corresponding classical state of the art which, in this case, is an AdaBoost classifier based on an ensemble of size 75. \"Quantum accuracy\", on the other hand, refers to the accuracy obtained using the \"Singularity Machine Learning - Classification\".\n", - "\n", - "| Problem | Dataset Size | Ensemble Size | Number of Qubits | Classical Accuracy | Quantum Accuracy | Improvement |\n", - "|-------------|-------------|-------------|-------------|-------------|-------------|-------------|\n", - "| Grid stability | 5000 examples, 12 features | 55 | 55 | 76% | 91% | 15% |\n", - "| Grid stability | 5000 examples, 12 features | 65 | 65 | 76% | 92% | 16% |\n", - "| Grid stability | 5000 examples, 12 features | 75 | 75 | 76% | 94% | 18% |\n", - "| Grid stability | 5000 examples, 12 features | 85 | 85 | 76% | 94% | 18% |\n", - "| Grid stability | 5000 examples, 12 features | 100 | 100 | 76% | 95% | 19% |\n", - "\n", - "----\n", - "\n", - "As quantum hardware evolves and scales, the implications for our quantum classifier become increasingly significant. While the number of qubits does impose limitations on the size of the ensemble that can be utilized, it does not restrict the volume of data that can be processed. This powerful capability enables the classifier to efficiently handle datasets containing millions of data points and thousands of features. Importantly, the constraints related to ensemble size can be addressed through the implementation of a large-scale version of the classifier. By leveraging an iterative outer-loop approach, the ensemble can be dynamically expanded, enhancing flexibility and overall performance. However, it's worth noting that this feature has not yet been implemented in the current version of the classifier." - ] - }, - { - "cell_type": "markdown", - "id": "cddff465", - "metadata": {}, - "source": [ - "## Changelog\n", - "\n", - "### 4 June 2025\n", - "- Upgraded `QuantumEnhancedEnsembleClassifier` with the following updates:\n", - " - Added onsite/alpha regularization. You can specify `regularization_type` to be `onsite` or `alpha`\n", - " - Added auto-regularization. You can set `regularization` to `auto` to use auto-regularization\n", - " - Added `optimization_data` parameter to the `fit` method to choose optimization data for quantum optimization. You can use one of these options: `train`, `validation`, or `both`\n", - " - Improved overall performance\n", - "- Added detailed status tracking for running jobs\n", - "\n", - "### 20 May 2025\n", - "- Standardized error handling\n", - "\n", - "### 18 March 2025\n", - "- Upgraded qiskit-serverless to 0.20.0 and base image to 0.20.1\n", - "\n", - "### 14 February 2025\n", - "- Upgraded base image to 0.19.1\n", - "\n", - "### 6 February 2025\n", - "- Upgraded qiskit-serverless to 0.19.0 and base image to 0.19.0\n", - "\n", - "### 13 November 2024\n", - "- Release of Singularity Machine Learning - Classification\n", - "\n", - "## Get support\n", - "\n", - "For any questions, [reach out to Multiverse Computing](mailto:singularity@multiversecomputing.com).\n", - "\n", - "Be sure to include the following information:\n", - "\n", - "- The Qiskit Function Job ID (`job.job_id`)\n", - "- A detailed description of the issue\n", - "- Any relevant error messages or codes\n", - "- Steps to reproduce the issue\n", - "\n", - "## Next steps\n", - "\n", - "\n", - "\n", - "- Request access to [Multiverse Computing's Singularity Machine Learning Classification function](https://quantum.cloud.ibm.com/functions?id=multiverse-singularity).\n", - "- Visit the [API reference](/docs/api/functions/multiverse-computing-singularity) for this Qiskit Function.\n", - "- Review [Leclerc, L., et al. (2023). Financial risk management on a neutral atom quantum processor. Physical Review Research, 5, 043117](https://journals.aps.org/prresearch/pdf/10.1103/PhysRevResearch.5.043117).\n", - "\n", - "" - ] } ], "metadata": { diff --git a/docs/functions/multiverse-computing-singularity/index.ipynb b/docs/functions/multiverse-computing-singularity/index.ipynb new file mode 100644 index 000000000000..c65de491d101 --- /dev/null +++ b/docs/functions/multiverse-computing-singularity/index.ipynb @@ -0,0 +1,174 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "fe74e692", + "metadata": {}, + "source": [ + "---\n", + "title: Singularity Machine Learning - Classification by Multiverse Computing\n", + "description: A Qiskit Function to create and train a hybrid quantum ensemble classifier from multiple learners and optimizes them for diversity and generalization with QAOA\n", + "---\n", + "\n", + "{/* cspell:ignore hyperparameters, sparsify, sparsification, Leclerc */}" + ] + }, + { + "cell_type": "markdown", + "id": "dde95705", + "metadata": {}, + "source": [ + "# Singularity Machine Learning - Classification: A Qiskit Function by Multiverse Computing\n", + "\n", + "*See the [API reference](/docs/api/functions/multiverse-computing-singularity)*" + ] + }, + { + "cell_type": "markdown", + "id": "99db0bb4", + "metadata": { + "tags": [ + "version-info" + ] + }, + "source": [ + "{/*\n", + " DO NOT EDIT THIS CELL!!!\n", + " This cell's content is generated automatically by a script. Anything you add\n", + " here will be removed next time the notebook is run. To add new content, create\n", + " a new cell before or after this one.\n", + "*/}\n", + "\n", + "\n", + "\n", + "\n", + "The code on this page was developed using the following requirements.\n", + "We recommend using these versions or newer.\n", + "\n", + "```\n", + "scikit-learn~=1.8.0\n", + "```\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "9985b8f4", + "metadata": {}, + "source": [ + "\n", + "* Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", + "\n", + "\n", + "## Overview\n", + "\n", + "With the \"Singularity Machine Learning - Classification\" function, you can solve real-world machine learning problems on quantum hardware without requiring quantum expertise. This Application function, based on ensemble methods, is a hybrid classifier. It leverages classical methods like boosting, bagging, and stacking for initial ensemble training. Subsequently, quantum algorithms such as variational quantum eigensolver (VQE) and quantum approximate optimization algorithm (QAOA) are employed to enhance the trained ensemble's diversity, generalization capabilities, and overall complexity.\n", + "\n", + "Unlike other quantum machine learning solutions, this function is capable of handling large-scale datasets with millions of examples and features without being limited by the number of qubits in the target QPU. The number of qubits only determines the size of the ensemble that can be trained. It is also highly flexible, and can be used to solve classification problems across a wide range of domains, including finance, healthcare, and cybersecurity." + ] + }, + { + "cell_type": "markdown", + "id": "353e72a4", + "metadata": {}, + "source": [ + "It consistently achieves high accuracies on classically challenging problems involving high-dimensional, noisy, and imbalanced datasets." + ] + }, + { + "cell_type": "markdown", + "id": "339c5737", + "metadata": {}, + "source": [ + "![How it works](/docs/images/guides/multiverse-computing-singularity/how_it_works.avif)" + ] + }, + { + "cell_type": "markdown", + "id": "0639e5e5", + "metadata": {}, + "source": [ + "It is built for:\n", + "1. Engineers and data scientists at companies seeking to enhance their tech offerings by integrating quantum machine learning into their products and services,\n", + "2. Researchers at quantum research labs exploring quantum machine learning applications and looking to leverage quantum computing for classification tasks, and\n", + "3. Students and teachers at educational institutions in courses like machine learning, and who are looking to demonstrate the advantages of quantum computing.\n", + "\n", + "The following example showcases its various functionalities, including `create`, `list`, `fit`, and `predict`, and demonstrates its usage in a synthetic problem comprising two interleaving half circles, a notoriously challenging problem due to its nonlinear decision boundary." + ] + }, + { + "cell_type": "markdown", + "id": "ccf056e3", + "metadata": {}, + "source": [ + "{/* cspell:ignore quantumly */}\n", + "\n", + "## Function description\n", + "\n", + "This Qiskit Function allows users to solve binary classification problems using Singularity's quantum-enhanced ensemble classifier. Behind the scenes, it uses a hybrid approach to classically train an ensemble of classifiers on the labeled dataset, and then optimize it for maximum diversity and generalization using the Quantum Approximate Optimization Algorithm (QAOA) on IBM® QPUs. Through a user-friendly interface, users can configure a classifier according to their requirements, train it on the dataset of their choice, and use it to make predictions on a previously unseen dataset.\n", + "\n", + "To solve a generic classification problem:\n", + "1. Preprocess the dataset, and split it into training and testing sets. Optionally, you can further split the training set into training and validation sets. This can be achieved using [scikit-learn](https://scikit-learn.org/1.5/modules/generated/sklearn.model_selection.train_test_split.html).\n", + "2. If the training set is imbalanced, you can resample it to balance the classes using [imbalanced-learn](https://imbalanced-learn.org/stable/introduction.html#problem-statement-regarding-imbalanced-data-sets).\n", + "3. Upload the training, validation, and test sets separately to the function's storage using the catalog's `file_upload` method, passing it the relevant path each time.\n", + "4. Initialize the quantum classifier by using the function's `create` action, which accepts hyperparameters such as the number and types of learners, the regularization (lambda value), and optimization options including the number of layers, the type of classical optimizer, the quantum backend, and so on.\n", + "5. Train the quantum classifier on the training set using the function's `fit` action, passing it the labeled training set, and the validation set if applicable.\n", + "6. Make predictions on the previously unseen test set using the function's `predict` action." + ] + }, + { + "cell_type": "markdown", + "id": "26472870", + "metadata": {}, + "source": [ + "---" + ] + }, + { + "cell_type": "markdown", + "id": "5cc6f2b3", + "metadata": {}, + "source": [ + "## Benchmarks\n", + "\n", + "These benchmarks show that the classifier can achieve extremely high accuracies on challenging problems. They also show that increasing the number of learners in the ensemble (number of qubits) can lead to increased accuracy.\n", + "\n", + "\"Classical accuracy\" refers to the accuracy obtained using corresponding classical state of the art which, in this case, is an AdaBoost classifier based on an ensemble of size 75. \"Quantum accuracy\", on the other hand, refers to the accuracy obtained using the \"Singularity Machine Learning - Classification\".\n", + "\n", + "| Problem | Dataset Size | Ensemble Size | Number of Qubits | Classical Accuracy | Quantum Accuracy | Improvement |\n", + "|-------------|-------------|-------------|-------------|-------------|-------------|-------------|\n", + "| Grid stability | 5000 examples, 12 features | 55 | 55 | 76% | 91% | 15% |\n", + "| Grid stability | 5000 examples, 12 features | 65 | 65 | 76% | 92% | 16% |\n", + "| Grid stability | 5000 examples, 12 features | 75 | 75 | 76% | 94% | 18% |\n", + "| Grid stability | 5000 examples, 12 features | 85 | 85 | 76% | 94% | 18% |\n", + "| Grid stability | 5000 examples, 12 features | 100 | 100 | 76% | 95% | 19% |\n", + "\n", + "----\n", + "\n", + "As quantum hardware evolves and scales, the implications for our quantum classifier become increasingly significant. While the number of qubits does impose limitations on the size of the ensemble that can be utilized, it does not restrict the volume of data that can be processed. This powerful capability enables the classifier to efficiently handle datasets containing millions of data points and thousands of features. Importantly, the constraints related to ensemble size can be addressed through the implementation of a large-scale version of the classifier. By leveraging an iterative outer-loop approach, the ensemble can be dynamically expanded, enhancing flexibility and overall performance. However, it's worth noting that this feature has not yet been implemented in the current version of the classifier." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/functions/multiverse-computing-singularity/performance-tuning.mdx b/docs/functions/multiverse-computing-singularity/performance-tuning.mdx new file mode 100644 index 000000000000..6cc1be675e3f --- /dev/null +++ b/docs/functions/multiverse-computing-singularity/performance-tuning.mdx @@ -0,0 +1,24 @@ +--- +title: Advanced techniques with Singularity Machine Learning +description: Practical guidance for tuning learner count, regularization, and ensemble settings for Singularity. +--- + +*Multiverse Computing is encouraged to expand this page with vendor-specific tuning guidance. The suggestions below are derived from the API reference and are intended as a starting point.* + +## Number of learners (num_learners) + +`num_learners` sets the size of the quantum ensemble — each learner maps to a qubit. The benchmark data on the Overview page shows that increasing `num_learners` improves accuracy on challenging datasets. However, more learners means larger circuits and higher QPU cost. Start with a small ensemble to validate your pipeline, then scale up. + +## Learner composition + +Use `learners_types` and `learners_proportions` to mix different quantum classifier types within the ensemble. Multiverse Computing is encouraged to document which learner type combinations work best for specific data characteristics (for example, high-dimensional vs sparse datasets). + +## Regularization + +`regularization_type` and `regularization` control overfitting prevention. For small or noisy datasets, stronger regularization is recommended. The `regularization_desired_ratio` and `regularization_upper_bound` parameters offer finer control — Multiverse Computing is encouraged to provide guidance on typical values by dataset size. + +## Voting strategy + +`voting` controls how the ensemble combines individual learner predictions. For imbalanced datasets, adjusting `prob_threshold` can improve recall on the minority class. + +See the [API reference](/docs/api/functions/multiverse-computing-singularity) for the full parameter list across all actions (`create`, `fit`, `predict`, `fit_predict`, `create_fit_predict`). diff --git a/docs/functions/q-ctrl-optimization-solver/_toc.json b/docs/functions/q-ctrl-optimization-solver/_toc.json new file mode 100644 index 000000000000..58cef700366b --- /dev/null +++ b/docs/functions/q-ctrl-optimization-solver/_toc.json @@ -0,0 +1,54 @@ +{ + "parentUrl": "/docs/guides/functions", + "parentLabel": "Qiskit Functions", + "title": "Optimization Solver: A Qiskit Function by Q-CTRL Fire Opal", + "collapsed": true, + "children": [ + { + "title": "", + "collapsible": false, + "children": [ + { + "title": "Overview", + "url": "/docs/functions/q-ctrl-optimization-solver" + }, + { + "title": "Get started", + "url": "/docs/functions/q-ctrl-optimization-solver/get-started" + }, + { + "title": "Advanced techniques with Q-CTRL Optimization Solver", + "url": "/docs/functions/q-ctrl-optimization-solver/performance-tuning" + }, + { + "title": "Changelog", + "url": "/docs/functions/q-ctrl-optimization-solver/changelog" + } + ] + }, + { + "title": "Tutorials", + "collapsible": false, + "children": [ + { + "title": "Higher-order binary optimization with Q-CTRL's Optimization Solver", + "url": "/docs/tutorials/solve-higher-order-binary-optimization-problems-with-q-ctrls-optimization-solver" + }, + { + "title": "Quantum Phase Estimation with Q-CTRL's Qiskit Functions", + "url": "/docs/tutorials/quantum-phase-estimation-qctrl" + } + ] + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "/docs/api/functions/q-ctrl-optimization-solver" + } + ] + } + ] +} diff --git a/docs/functions/q-ctrl-optimization-solver/changelog.mdx b/docs/functions/q-ctrl-optimization-solver/changelog.mdx new file mode 100644 index 000000000000..4d1c7bdacac3 --- /dev/null +++ b/docs/functions/q-ctrl-optimization-solver/changelog.mdx @@ -0,0 +1,6 @@ +--- +title: Changelog +description: Changelog for Q-CTRL Optimization Solver. +--- + +- 2026-02-11: We now have support for `ibm_miami` diff --git a/docs/functions/application-functions/q-ctrl-optimization-solver.ipynb b/docs/functions/q-ctrl-optimization-solver/get-started.ipynb similarity index 55% rename from docs/functions/application-functions/q-ctrl-optimization-solver.ipynb rename to docs/functions/q-ctrl-optimization-solver/get-started.ipynb index 9b3c720556c3..956764cbcca6 100644 --- a/docs/functions/application-functions/q-ctrl-optimization-solver.ipynb +++ b/docs/functions/q-ctrl-optimization-solver/get-started.ipynb @@ -2,128 +2,10 @@ "cells": [ { "cell_type": "markdown", - "id": "11ea9666", + "id": "page-frontmatter", "metadata": {}, "source": [ - "---\n", - "title: Optimization Solver - A Qiskit Function by Q-CTRL Fire Opal\n", - "description: Start solving utility-scale optimization problems with the Fire Opal Optimization Solver by Q-CTRL\n", - "---\n", - "\n", - "{/* cspell:ignore Sachdeva */}" - ] - }, - { - "cell_type": "markdown", - "id": "dde95705", - "metadata": {}, - "source": [ - "# Optimization Solver: A Qiskit Function by Q-CTRL Fire Opal\n", - "\n", - "*See the [API reference](/docs/api/functions/q-ctrl-optimization-solver)*\n", - "\n", - "\n", - " Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "40c2085c", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [ - "{/*\n", - " DO NOT EDIT THIS CELL!!!\n", - " This cell's content is generated automatically by a script. Anything you add\n", - " here will be removed next time the notebook is run. To add new content, create\n", - " a new cell before or after this one.\n", - "*/}\n", - "\n", - "\n", - "\n", - "\n", - "The code on this page was developed using the following requirements.\n", - "We recommend using these versions or newer.\n", - "\n", - "```\n", - "qiskit-ibm-runtime~=0.46.1\n", - "sympy~=1.14.0\n", - "```\n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "e30c7881", - "metadata": {}, - "source": [ - "## Overview\n", - "\n", - "With the Fire Opal Optimization Solver, you can solve utility-scale optimization problems on quantum hardware without requiring quantum expertise. Simply input the high-level problem definition, and the Solver takes care of the rest. The entire workflow is noise-aware and leverages [Fire Opal's Performance Management](/docs/guides/q-ctrl-performance-management) under the hood. The Solver consistently delivers accurate solutions to classically challenging problems, even at full-device scale on the largest IBM® QPUs.\n", - "\n", - "The Solver is flexible and can be used to solve combinatorial optimization problems defined as objective functions or arbitrary graphs. Problems do not have to be mapped to device topology. Both unconstrained and constrained problems are solvable, given that constraints can be formulated as penalty terms. The examples included in this guide demonstrate how to solve an unconstrained and a constrained utility-scale optimization problem using different Solver input types. The first example involves a max-cut problem defined on a 156-node, 3-Regular graph, while the second example tackles a 50-node Minimum Vertex Cover problem defined by a cost function.\n", - "\n", - "To get access to the Optimization Solver, [contact Q-CTRL](https://form.typeform.com/to/uOAVDnGg?typeform-source=q-ctrl.com)." - ] - }, - { - "cell_type": "markdown", - "id": "5f761442", - "metadata": {}, - "source": [ - "## Function description\n", - "\n", - "The Solver fully optimizes and automates the entire algorithm, from error suppression at the hardware level to efficient problem mapping and closed-loop classical optimization. Behind the scenes, the Solver's pipeline reduces errors at every stage, enabling the enhanced performance required to meaningfully scale. The underlying workflow is inspired by the Quantum Approximate Optimization Algorithm (QAOA), which is a hybrid quantum-classical algorithm. For a detailed summary of the full Optimization Solver workflow, refer to [the published manuscript](https://arxiv.org/abs/2406.01743).\n", - "\n", - "\n", - "![Visualization of the Optimization Solver workflow](/docs/images/guides/qctrl-optimization/solver_workflow.svg)\n", - "\n", - "To solve a generic problem with the Optimization Solver:\n", - "1. Define your problem as an objective function, a graph, or `SparsePauliOp` spin chain.\n", - "2. Connect to the function through the Qiskit Functions Catalog.\n", - "3. Run the problem with the Solver and retrieve results." - ] - }, - { - "cell_type": "markdown", - "id": "d20af236", - "metadata": {}, - "source": [ - "### Accepted problem formats\n", - "\n", - "- Polynomial expression representation of an objective function. Ideally created in Python with an existing SymPy Poly object and formatted into a string using [sympy.srepr](https://docs.sympy.org/latest/tutorials/intro-tutorial/printing.html#srepr).\n", - "- Graph representation of a specific problem type. The graph should be created using the networkx library in Python. It should then converted to a string by using the networkx function `[nx.readwrite.json_graph.adjacency_data](http://nx.readwrite.json_graph.adjacency_data.)`.\n", - "- Spin chain representation of a specific problem. The spin chain should be represented as a `SparsePauliOp` object; see the [documentation](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp) for more details.\n", - "\n", - "\n", - "If you want to use a backend that this function does not currently support, [reach out to Q-CTRL](https://form.typeform.com/to/iuujEAEI?typeform-source=q-ctrl.com) to add support.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "1165f4f0", - "metadata": {}, - "source": [ - "## Benchmarks\n", - "\n", - "[Published benchmarking results](https://arxiv.org/abs/2406.01743) show that the Solver successfully solves problems with over 120 qubits, even outperforming previously published results on quantum annealing and trapped-ion devices. The following benchmark metrics provide a rough indication of the accuracy and scaling of problem types based on a few examples. Actual metrics may differ based on various problem features, such as the number of terms in the objective function (density) and their locality, number of variables, and polynomial order.\n", - "\n", - "The \"Number of qubits\" indicated is not a hard limitation but represents rough thresholds where you can expect extremely consistent solution accuracy. Larger problem sizes have been successfully solved, and testing beyond these limits is encouraged.\n", - "\n", - "Arbitrary qubit connectivity is supported across all problem types.\n", - "\n", - "| Problem type | Number of qubits | Example | Accuracy | Total time (s) | Runtime usage (s) | Number of iterations\n", - "| --------- | ---------------- | -------------------------- | -------- | ---------- | ------------- |---- |\n", - "| Sparsely-connected quadratic problems | 156 | 3-regular max-cut| 100% | 1764 | 293 | 16 |\n", - "| Higher-order binary optimization | 156 | Ising spin-glass model | 100% | 1461 | 272 | 16 |\n", - "| Densely-connected quadratic problems | 50 | Fully-connected max-cut| 100% | 1758 | 268 | 12 |\n", - "| Constrained problem with penalty terms | 50 | Weighted Minimum Vertex Cover with 8% edge density | 100% | 1074 | 215 | 10 |" + "---\ntitle: Get started with Q-CTRL Optimization Solver\ndescription: Get started with Q-CTRL Optimization Solver — authenticate, load the function, and run unconstrained and constrained optimization examples.\n---" ] }, { @@ -131,9 +13,7 @@ "id": "73390a19", "metadata": {}, "source": [ - "## Get started\n", - "\n", - "First, authenticate using your [IBM Quantum API key](http://quantum.cloud.ibm.com/). Then, select the Qiskit Function as follows. (This snippet assumes you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment.)" + "## Setup and load function\n\nFirst, authenticate using your [IBM Quantum API key](http://quantum.cloud.ibm.com/). Then, select the Qiskit Function as follows. (This snippet assumes you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment.)" ] }, { @@ -156,8 +36,7 @@ "id": "e8837f5f", "metadata": {}, "source": [ - "## Example: Unconstrained optimization\n", - "Run the [maximum cut](https://en.wikipedia.org/wiki/Maximum_cut) (max-cut) problem. The following example demonstrates the Solver's capabilities on a 156-node, 3-regular unweighted graph max-cut problem, but you can also solve weighted graph problems." + "## Run your first workload\nRun the [maximum cut](https://en.wikipedia.org/wiki/Maximum_cut) (max-cut) problem. The following example demonstrates the Solver's capabilities on a 156-node, 3-regular unweighted graph max-cut problem, but you can also solve weighted graph problems." ] }, { @@ -566,48 +445,6 @@ "# Print results\n", "print(f\"Solution cost: {qctrl_cost}\")" ] - }, - { - "cell_type": "markdown", - "id": "e9ec2e67", - "metadata": {}, - "source": [ - "## Get support\n", - "\n", - "For any questions or issues, [reach out to Q-CTRL](https://form.typeform.com/to/iuujEAEI?typeform-source=q-ctrl.com)." - ] - }, - { - "cell_type": "markdown", - "id": "993aa226c6ec9f5e", - "metadata": {}, - "source": [ - "## Changelog\n", - "\n", - "- 2026-02-11: We now have support for `ibm_miami`" - ] - }, - { - "cell_type": "markdown", - "id": "5a6a25c8", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - "\n", - "- Request access to [Q-CTRL Optimization Solver](https://quantum.cloud.ibm.com/functions?id=q-ctrl-optimization-solver).\n", - "- Visit the [API reference](/docs/api/functions/q-ctrl-optimization-solver) for this Qiskit Function.\n", - "- Try the [Solve higher-order binary optimization problems with Q-CTRL's Optimization Solver](/docs/tutorials/solve-higher-order-binary-optimization-problems-with-q-ctrls-optimization-solver) tutorial.\n", - "- Review [Sachdeva, N., et al. (2024). Quantum optimization using a 127-qubit gate-model IBM quantum computer can outperform quantum annealers for nontrivial binary optimization problems. arXiv preprint arXiv:2406.01743](https://arxiv.org/abs/2406.01743).\n", - "- Review [Loco, D., et al. (2026). Practical protein-pocket hydration-site prediction for drug discovery on a quantum computer. arXiv preprint arXiv:2512.08390](https://arxiv.org/abs/2512.08390).\n", - "- Review the [Mazda](https://q-ctrl.com/case-study/tackling-a-costly-bottleneck-in-automotive-design) case study.\n", - "- Review the [Network Rail](https://q-ctrl.com/case-study/accelerating-the-schedule-for-quantum-enhanced-rail) case study.\n", - "- Review the [Australian Army](https://q-ctrl.com/case-study/improving-army-logistics-with-quantum-computing) case study.\n", - "- Review the [Transport for New South Wales](https://q-ctrl.com/case-study/delivering-quantum-computing-for-faster-commuting) case study.\n", - "\n", - "" - ] } ], "metadata": { diff --git a/docs/functions/q-ctrl-optimization-solver/index.ipynb b/docs/functions/q-ctrl-optimization-solver/index.ipynb new file mode 100644 index 000000000000..5b66d960af76 --- /dev/null +++ b/docs/functions/q-ctrl-optimization-solver/index.ipynb @@ -0,0 +1,183 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "11ea9666", + "metadata": {}, + "source": [ + "---\n", + "title: Optimization Solver - A Qiskit Function by Q-CTRL Fire Opal\n", + "description: Start solving utility-scale optimization problems with the Fire Opal Optimization Solver by Q-CTRL\n", + "---\n", + "\n", + "{/* cspell:ignore Sachdeva */}" + ] + }, + { + "cell_type": "markdown", + "id": "dde95705", + "metadata": {}, + "source": [ + "# Optimization Solver: A Qiskit Function by Q-CTRL Fire Opal\n", + "\n", + "*See the [API reference](/docs/api/functions/q-ctrl-optimization-solver)*\n", + "\n", + "\n", + " Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "40c2085c", + "metadata": { + "tags": [ + "version-info" + ] + }, + "source": [ + "{/*\n", + " DO NOT EDIT THIS CELL!!!\n", + " This cell's content is generated automatically by a script. Anything you add\n", + " here will be removed next time the notebook is run. To add new content, create\n", + " a new cell before or after this one.\n", + "*/}\n", + "\n", + "\n", + "\n", + "\n", + "The code on this page was developed using the following requirements.\n", + "We recommend using these versions or newer.\n", + "\n", + "```\n", + "qiskit-ibm-runtime~=0.46.1\n", + "sympy~=1.14.0\n", + "```\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "e30c7881", + "metadata": {}, + "source": [ + "## Overview\n", + "\n", + "With the Fire Opal Optimization Solver, you can solve utility-scale optimization problems on quantum hardware without requiring quantum expertise. Simply input the high-level problem definition, and the Solver takes care of the rest. The entire workflow is noise-aware and leverages [Fire Opal's Performance Management](/docs/guides/q-ctrl-performance-management) under the hood. The Solver consistently delivers accurate solutions to classically challenging problems, even at full-device scale on the largest IBM® QPUs.\n", + "\n", + "The Solver is flexible and can be used to solve combinatorial optimization problems defined as objective functions or arbitrary graphs. Problems do not have to be mapped to device topology. Both unconstrained and constrained problems are solvable, given that constraints can be formulated as penalty terms. The examples included in this guide demonstrate how to solve an unconstrained and a constrained utility-scale optimization problem using different Solver input types. The first example involves a max-cut problem defined on a 156-node, 3-Regular graph, while the second example tackles a 50-node Minimum Vertex Cover problem defined by a cost function.\n", + "\n", + "To get access to the Optimization Solver, [contact Q-CTRL](https://form.typeform.com/to/uOAVDnGg?typeform-source=q-ctrl.com)." + ] + }, + { + "cell_type": "markdown", + "id": "5f761442", + "metadata": {}, + "source": [ + "## Function description\n", + "\n", + "The Solver fully optimizes and automates the entire algorithm, from error suppression at the hardware level to efficient problem mapping and closed-loop classical optimization. Behind the scenes, the Solver's pipeline reduces errors at every stage, enabling the enhanced performance required to meaningfully scale. The underlying workflow is inspired by the Quantum Approximate Optimization Algorithm (QAOA), which is a hybrid quantum-classical algorithm. For a detailed summary of the full Optimization Solver workflow, refer to [the published manuscript](https://arxiv.org/abs/2406.01743).\n", + "\n", + "\n", + "![Visualization of the Optimization Solver workflow](/docs/images/guides/qctrl-optimization/solver_workflow.svg)\n", + "\n", + "To solve a generic problem with the Optimization Solver:\n", + "1. Define your problem as an objective function, a graph, or `SparsePauliOp` spin chain.\n", + "2. Connect to the function through the Qiskit Functions Catalog.\n", + "3. Run the problem with the Solver and retrieve results." + ] + }, + { + "cell_type": "markdown", + "id": "d20af236", + "metadata": {}, + "source": [ + "### Accepted problem formats\n", + "\n", + "- Polynomial expression representation of an objective function. Ideally created in Python with an existing SymPy Poly object and formatted into a string using [sympy.srepr](https://docs.sympy.org/latest/tutorials/intro-tutorial/printing.html#srepr).\n", + "- Graph representation of a specific problem type. The graph should be created using the networkx library in Python. It should then converted to a string by using the networkx function `[nx.readwrite.json_graph.adjacency_data](http://nx.readwrite.json_graph.adjacency_data.)`.\n", + "- Spin chain representation of a specific problem. The spin chain should be represented as a `SparsePauliOp` object; see the [documentation](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp) for more details.\n", + "\n", + "\n", + "If you want to use a backend that this function does not currently support, [reach out to Q-CTRL](https://form.typeform.com/to/iuujEAEI?typeform-source=q-ctrl.com) to add support.\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "1165f4f0", + "metadata": {}, + "source": [ + "## Benchmarks\n", + "\n", + "[Published benchmarking results](https://arxiv.org/abs/2406.01743) show that the Solver successfully solves problems with over 120 qubits, even outperforming previously published results on quantum annealing and trapped-ion devices. The following benchmark metrics provide a rough indication of the accuracy and scaling of problem types based on a few examples. Actual metrics may differ based on various problem features, such as the number of terms in the objective function (density) and their locality, number of variables, and polynomial order.\n", + "\n", + "The \"Number of qubits\" indicated is not a hard limitation but represents rough thresholds where you can expect extremely consistent solution accuracy. Larger problem sizes have been successfully solved, and testing beyond these limits is encouraged.\n", + "\n", + "Arbitrary qubit connectivity is supported across all problem types.\n", + "\n", + "| Problem type | Number of qubits | Example | Accuracy | Total time (s) | Runtime usage (s) | Number of iterations\n", + "| --------- | ---------------- | -------------------------- | -------- | ---------- | ------------- |---- |\n", + "| Sparsely-connected quadratic problems | 156 | 3-regular max-cut| 100% | 1764 | 293 | 16 |\n", + "| Higher-order binary optimization | 156 | Ising spin-glass model | 100% | 1461 | 272 | 16 |\n", + "| Densely-connected quadratic problems | 50 | Fully-connected max-cut| 100% | 1758 | 268 | 12 |\n", + "| Constrained problem with penalty terms | 50 | Weighted Minimum Vertex Cover with 8% edge density | 100% | 1074 | 215 | 10 |" + ] + }, + { + "cell_type": "markdown", + "id": "e9ec2e67", + "metadata": {}, + "source": [ + "## Get support\n", + "\n", + "For any questions or issues, [reach out to Q-CTRL](https://form.typeform.com/to/iuujEAEI?typeform-source=q-ctrl.com)." + ] + }, + { + "cell_type": "markdown", + "id": "5a6a25c8", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + "\n", + "- Request access to [Q-CTRL Optimization Solver](https://quantum.cloud.ibm.com/functions?id=q-ctrl-optimization-solver).\n", + "- Visit the [API reference](/docs/api/functions/q-ctrl-optimization-solver) for this Qiskit Function.\n", + "- Try the [Solve higher-order binary optimization problems with Q-CTRL's Optimization Solver](/docs/tutorials/solve-higher-order-binary-optimization-problems-with-q-ctrls-optimization-solver) tutorial.\n", + "- Review [Sachdeva, N., et al. (2024). Quantum optimization using a 127-qubit gate-model IBM quantum computer can outperform quantum annealers for nontrivial binary optimization problems. arXiv preprint arXiv:2406.01743](https://arxiv.org/abs/2406.01743).\n", + "- Review [Loco, D., et al. (2026). Practical protein-pocket hydration-site prediction for drug discovery on a quantum computer. arXiv preprint arXiv:2512.08390](https://arxiv.org/abs/2512.08390).\n", + "- Review the [Mazda](https://q-ctrl.com/case-study/tackling-a-costly-bottleneck-in-automotive-design) case study.\n", + "- Review the [Network Rail](https://q-ctrl.com/case-study/accelerating-the-schedule-for-quantum-enhanced-rail) case study.\n", + "- Review the [Australian Army](https://q-ctrl.com/case-study/improving-army-logistics-with-quantum-computing) case study.\n", + "- Review the [Transport for New South Wales](https://q-ctrl.com/case-study/delivering-quantum-computing-for-faster-commuting) case study.\n", + "\n", + "" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/functions/q-ctrl-optimization-solver/performance-tuning.mdx b/docs/functions/q-ctrl-optimization-solver/performance-tuning.mdx new file mode 100644 index 000000000000..56e95880fdef --- /dev/null +++ b/docs/functions/q-ctrl-optimization-solver/performance-tuning.mdx @@ -0,0 +1,24 @@ +--- +title: Advanced techniques with Q-CTRL Optimization Solver +description: Practical guidance for problem formulation and configuration when using the Q-CTRL Optimization Solver. +--- + +*Q-CTRL is encouraged to expand this page with vendor-specific tuning guidance. The suggestions below are derived from the API reference and are intended as a starting point.* + +## Problem formulation is the primary lever + +The Optimization Solver has a minimal API — the main configuration decision is how you formulate and encode your problem. The quality of the QUBO string representation directly affects solution quality. For constrained problems, the penalty term weight (see the constrained optimization example) needs to be tuned: too low and constraints are violated; too high and the solver focuses only on constraints. + +## Unconstrained vs constrained problems + +Set `problem_type` accordingly. Constrained problems require encoding constraints as penalty terms in the QUBO — the weight of these terms relative to the objective is a key tuning parameter not exposed directly in the API. See the constrained example on the Examples page for a starting point. + +## Session reuse + +Use `session_id` to group related jobs within a session. This reduces overhead when submitting multiple optimization runs (for example, parameter sweeps or warm-starting). + +## Problem size + +Q-CTRL is encouraged to document the relationship between problem size (number of variables), backend selection, and expected solution quality. The benchmarks on the Overview page provide some data; expand with guidance on scaling limits. + +See the [API reference](/docs/api/functions/q-ctrl-optimization-solver) for full parameter details. diff --git a/docs/functions/q-ctrl-performance-management/_toc.json b/docs/functions/q-ctrl-performance-management/_toc.json new file mode 100644 index 000000000000..7f292fac70db --- /dev/null +++ b/docs/functions/q-ctrl-performance-management/_toc.json @@ -0,0 +1,50 @@ +{ + "parentUrl": "/docs/guides/functions", + "parentLabel": "Qiskit Functions", + "title": "Q-CTRL Performance Management", + "collapsed": true, + "children": [ + { + "title": "", + "collapsible": false, + "children": [ + { + "title": "Overview", + "url": "/docs/functions/q-ctrl-performance-management" + }, + { + "title": "Get started", + "url": "/docs/functions/q-ctrl-performance-management/get-started" + }, + { + "title": "Advanced techniques with Q-CTRL Performance Management", + "url": "/docs/functions/q-ctrl-performance-management/performance-tuning" + }, + { + "title": "Changelog", + "url": "/docs/functions/q-ctrl-performance-management/changelog" + } + ] + }, + { + "title": "Tutorials", + "collapsible": false, + "children": [ + { + "title": "Transverse-Field Ising Model with Q-CTRL's Performance Management", + "url": "/docs/tutorials/transverse-field-ising-model" + } + ] + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "/docs/api/functions/q-ctrl-performance-management" + } + ] + } + ] +} diff --git a/docs/functions/q-ctrl-performance-management/changelog.mdx b/docs/functions/q-ctrl-performance-management/changelog.mdx new file mode 100644 index 000000000000..f3e2a51b59c4 --- /dev/null +++ b/docs/functions/q-ctrl-performance-management/changelog.mdx @@ -0,0 +1,7 @@ +--- +title: Changelog +description: Changelog for Q-CTRL Performance Management. +--- + +- 2026-02-20: Deprecation Notice - the `provider_job_ids` metadata field will be deprecated in 30 days in version 0.13.0. Users can access the job ID through `job_id()` method of the runtime service. +- 2026-02-11: We now have support for `ibm_miami`, and added execution metadata to the `PubResult`. diff --git a/docs/functions/circuit-functions/q-ctrl-performance-management.ipynb b/docs/functions/q-ctrl-performance-management/get-started.ipynb similarity index 98% rename from docs/functions/circuit-functions/q-ctrl-performance-management.ipynb rename to docs/functions/q-ctrl-performance-management/get-started.ipynb index 889491b78e61..31ce532c0371 100644 --- a/docs/functions/circuit-functions/q-ctrl-performance-management.ipynb +++ b/docs/functions/q-ctrl-performance-management/get-started.ipynb @@ -2,129 +2,10 @@ "cells": [ { "cell_type": "markdown", - "id": "dde95705", + "id": "page-frontmatter", "metadata": {}, "source": [ - "---\n", - "title: Performance Management - A Qiskit Function by Q-CTRL Fire Opal\n", - "description: Apply automated error suppression using Fire Opal Performance Management by Q-CTRL\n", - "---\n", - "\n", - "\n", - "{/* cspell:ignore fontsize, Mundada, Yamauchi, supersymmetric, Paterakis, Gharibyan */}\n", - "\n", - "# Performance Management: A Qiskit Function by Q-CTRL Fire Opal\n", - "\n", - "*See the [API reference](/docs/api/functions/q-ctrl-performance-management)*\n", - "\n", - "\n", - " Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "ace2ed13", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [ - "{/*\n", - " DO NOT EDIT THIS CELL!!!\n", - " This cell's content is generated automatically by a script. Anything you add\n", - " here will be removed next time the notebook is run. To add new content, create\n", - " a new cell before or after this one.\n", - "*/}\n", - "\n", - "\n", - "\n", - "\n", - "The code on this page was developed using the following requirements.\n", - "We recommend using these versions or newer.\n", - "\n", - "```\n", - "qiskit[all]~=2.3.1\n", - "qiskit-ibm-runtime~=0.45.1\n", - "```\n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "c1732b45", - "metadata": {}, - "source": [ - "## Overview\n", - "\n", - "Fire Opal Performance Management makes it simple for anyone to achieve meaningful results from quantum computers at scale without needing to be quantum hardware experts. When running circuits with Fire Opal Performance Management, AI-driven error suppression techniques are automatically applied, enabling the scaling of larger problems with more gates and qubits. This approach reduces the number of shots required to reach the correct answer, with no added overhead — resulting in significant savings in both compute time and cost.\n", - "\n", - "Performance Management suppresses errors and increases the probability of getting the correct answer on noisy hardware. In other words, it increases the signal-to-noise ratio. The following image shows how increased accuracy enabled by Performance Management can reduce the need for additional shots in the case of a 10-qubit Quantum Fourier Transform algorithm. With only 30 shots, Q-CTRL reaches the 99% confidence threshold, whereas the default (`QiskitRuntime` Sampler, `optimization_level`=3 and `resilience_level`=1, `ibm_sherbrooke`) requires 170,000 shots. By getting the right answer faster, you save significant compute runtime.\n", - "\n", - "![Visualization of the improved runtime](/docs/images/guides/qctrl-performance-management/achieve_more.svg)\n", - "\n", - "The Performance Management function can be used with any algorithm, and you can easily use it in place of the standard [Qiskit Runtime primitives](/docs/guides/primitives). Behind the scenes, multiple error suppression techniques work together to prevent errors from happening at runtime. All Fire Opal pipeline methods are pre-configured and algorithm-agnostic, meaning you always get the best performance out of the box.\n", - "\n", - "To get access to Performance Management, [contact Q-CTRL](https://form.typeform.com/to/uOAVDnGg?typeform-source=q-ctrl.com)." - ] - }, - { - "cell_type": "markdown", - "id": "5f761442", - "metadata": {}, - "source": [ - "## Description\n", - "\n", - "Fire Opal Performance Management has two options for execution that are similar to the Qiskit Runtime primitives, so you can easily swap in the Q-CTRL Sampler and Estimator. The general workflow for using the Performance Management function is:\n", - "1. Define your circuit (and operators in the case of the Estimator).\n", - "2. Run the circuit.\n", - "3. Retrieve the results.\n", - "\n", - "To reduce hardware noise, Fire Opal employs a range of AI-driven error suppression techniques depicted in the following image. With Fire Opal, the entire pipeline is completely automated with zero need for configuration.\n", - "\n", - "Fire Opal's pipeline eliminates the need for additional overhead, such as increased quantum runtime or extra physical qubits. Note that classical processing time remains a factor (refer to the [Benchmarks](#benchmarks) section for estimates, where \"Total time\" reflects both classical and quantum processing). In contrast to error mitigation, which requires overhead in the form of sampling, Fire Opal's error suppression works at both the gate and pulse levels to address various sources of noise and to prevent the likelihood of an error occurring. By preventing errors, the need for expensive post-processing is eliminated.\n", - "\n", - "The following image depicts the error suppression methods automated by Fire Opal Performance Management.\n", - "\n", - "![Visualization of the error suppression pipeline](/docs/images/guides/qctrl-performance-management/error_suppression.svg)\n", - "\n", - "The function offers two primitives, Sampler and Estimator, and the inputs and outputs of both extend the implemented spec for [Qiskit Runtime V2 primitives](/docs/guides/primitive-input-output#pubs)." - ] - }, - { - "cell_type": "markdown", - "id": "64534d1a", - "metadata": {}, - "source": [ - "## Benchmarks\n", - "\n", - "[Published algorithmic benchmarking](https://journals.aps.org/prapplied/abstract/10.1103/PhysRevApplied.20.024034) results demonstrate significant performance improvement across various algorithms, including Bernstein-Vazirani, quantum Fourier transform, Grover’s search, quantum approximate optimization algorithm, and variational quantum eigensolver. The rest of this section provides more details about types of algorithms you can run, as well as the expected performance and runtimes.\n", - "\n", - "The following independent studies demonstrate how Q-CTRL's Performance Management enables algorithmic research at record-breaking scale:\n", - "- [Parametrized Energy-Efficient Quantum Kernels for Network Service Fault Diagnosis](https://arxiv.org/abs/2405.09724v1) - up to 50-qubit quantum kernel learning\n", - "- [Tensor-based quantum phase difference estimation for large-scale demonstration](https://arxiv.org/abs/2408.04946) - up to 33-qubit quantum phase estimation\n", - "- [Hierarchical Learning for Quantum ML: Novel Training Technique for Large-Scale Variational Quantum Circuits](https://arxiv.org/abs/2311.12929) - up to 21-qubit quantum data loading\n", - "\n", - "The following table provides a rough guide on accuracy and runtimes from prior benchmarking runs on `ibm_fez`. Performance on other devices may vary. The usage time is based on an assumption of 10,000 shots per circuit. The \"Number of qubits\" indicated is not a hard limitation but represents rough thresholds where you can expect extremely consistent solution accuracy. Larger problem sizes have been successfully solved, and testing beyond these limits is encouraged.\n", - "\n", - "\n", - "| Example | Number of qubits | Accuracy | Measure of accuracy | Total time (s) | Runtime usage (s) | Primitive (Mode) |\n", - "| --------- | ---------------- | -------------------------- | -------- | ---------- | ------------- |------------- |\n", - "| Bernstein–Vazirani | 50Q | 100% | Success Rate (Percentage of runs where the correct answer is the highest count bitstring) | 10 | 8 | Sampler |\n", - "| Quantum Fourier Transform | 30Q | 100% | Success Rate (Percentage of runs where the correct answer is the highest count bitstring) | 10 | 8 | Sampler |\n", - "| Quantum Phase Estimation | 30Q | 99.9998% | Accuracy of the angle found: `1- abs(real_angle - angle_found)/pi` | 10 | 8 | Sampler |\n", - "| Quantum simulation: Ising model (15 steps) | 20Q | 99.775% | $A$ (defined below) | 60 (per step) | 15 (per step) | Estimator |\n", - "| Quantum simulation 2: molecular dynamics (20 time points) | 34Q | 96.78% | $A_{mean}$ (defined below) | 10 (per time point) | 6 (per time point) | Estimator |\n", - "\n", - "Defining the accuracy of the measurement of an expectation value - the metric $A$ is defined as follows:\n", - "$$\n", - "A = 1 - \\frac{|\\epsilon^{ideal} - \\epsilon^{meas}|}{\\epsilon^{ideal}_{max} - \\epsilon^{ideal}_{min}},\n", - "$$\n", - "where $ \\epsilon^{ideal} $ = ideal expectation value, $ \\epsilon^{meas} $ = measured expectation value, $\\epsilon^{ideal}_{max} $ = ideal maximum value, and $\\epsilon^{ideal}_{min}$ = ideal minimum value. $A_{mean}$ is simply the average of the value of $A$ across multiple measurements.\n", - "\n", - "This metric is used because it is invariant to global shifts and scaling in the range of attainable values. In other words, regardless of whether you shift the range of possible expectation values higher or lower or increase the spread, the value of $A$ should remain consistent." + "---\ntitle: Get started with Q-CTRL Performance Management\ndescription: Get started with Q-CTRL Performance Management — authenticate, load the function, and run Estimator and Sampler primitive examples.\n---" ] }, { @@ -132,10 +13,7 @@ "id": "870af0fe", "metadata": {}, "source": [ - "## Get started\n", - "\n", - "Fire Opal Performance Management uses Qiskit v`2.0.0`, which is the recommended version. Supported versions are Qiskit >=v`2.0.0`.\n", - "Authenticate using your [IBM Quantum Platform API key](http://quantum.cloud.ibm.com/), and select the Qiskit Function as follows. (This snippet assumes you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment.)" + "## Setup and load function\n\nFire Opal Performance Management uses Qiskit v`2.0.0`, which is the recommended version. Supported versions are Qiskit >=v`2.0.0`.\nAuthenticate using your [IBM Quantum Platform API key](http://quantum.cloud.ibm.com/), and select the Qiskit Function as follows. (This snippet assumes you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment.)" ] }, { @@ -163,6 +41,14 @@ "" ] }, + { + "cell_type": "markdown", + "id": "q-ctrl-performance-management-examples-heading", + "metadata": {}, + "source": [ + "## Run your first workload" + ] + }, { "cell_type": "markdown", "id": "2947b5c3", @@ -613,56 +499,6 @@ "source": [ "plot_top_bitstrings(counts, hidden_bitstring)" ] - }, - { - "cell_type": "markdown", - "id": "d8104000b3d94c69", - "metadata": {}, - "source": [ - "## Changelog\n", - "\n", - "- 2026-02-20: Deprecation Notice - the `provider_job_ids` metadata field will be deprecated in 30 days in version 0.13.0. Users can access the job ID through `job_id()` method of the runtime service.\n", - "- 2026-02-11: We now have support for `ibm_miami`, and added execution metadata to the `PubResult`." - ] - }, - { - "cell_type": "markdown", - "id": "bb33258d", - "metadata": {}, - "source": [ - "## Get support\n", - "\n", - "For any questions or issues, [contact Q-CTRL](https://form.typeform.com/to/iuujEAEI)." - ] - }, - { - "cell_type": "markdown", - "id": "2fe4a6ea", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - "\n", - "- Request access to [Q-CTRL Performance Management](https://quantum.cloud.ibm.com/functions?id=q-ctrl-performance-management).\n", - "- Visit the [API reference](/docs/api/functions/q-ctrl-performance-management) for this Qiskit Function.\n", - "- Try the [Transverse-Field Ising Model with Q-CTRL's Performance Management](/docs/tutorials/transverse-field-ising-model) tutorial.\n", - "- Try the [Quantum Phase Estimation with Q-CTRL's Qiskit Functions](/docs/tutorials/quantum-phase-estimation-qctrl) tutorial\n", - "- Review [Mundada P. S., et al. (2023). Experimental Benchmarking of an Automated Deterministic Error-Suppression Workflow for Quantum Algorithms. Physical Review Applied, 20, 2](https://quantum-journal.org/papers/q-2023-07-25-1067/).\n", - "- Review [Kanno, S., et al. (2025). Tensor-based quantum phase difference estimation for large-scale demonstration. arXiv preprint arXiv:2408.04946](https://arxiv.org/abs/2408.04946).\n", - "- Review [SoftBank Corp, Demonstration Experiment of a Communication Service Fault Diagnosis System Using Quantum Machine Learning (blog), 30 August, 2024](https://www.softbank.jp/en/corp/technology/research/topics/102/).\n", - "- Review [Yamauchi, H., et al. (2024). Parametrized Energy-Efficient Quantum Kernels for Network Service Fault Diagnosis. arXiv preprint arXiv:2405.09724v1](https://arxiv.org/abs/2405.09724v1).\n", - "- Review [Yamauchi, H., et al. (2025). Quantum spectroscopy of topological dynamics via a supersymmetric Hamiltonian. arXiv preprint arXiv:2511.23169v1](https://arxiv.org/abs/2511.23169v1).\n", - "- Review [Wang, Y., et al. (2025). Δ-Motif: Subgraph Isomorphism at Scale via Data-Centric Parallelism. arXiv preprint arXiv:2508.21287](https://arxiv.org/abs/2508.21287).\n", - "- Review [Paterakis, N. G., et al. (2025). Quantum Computing in the Computational Landscape of Power Electronics: Vision and Reality. arXiv preprint arXiv:2507.02577](https://arxiv.org/abs/2507.02577).\n", - "- Review [Gharibyan, H., et al. (2023). Hierarchical Learning for Quantum ML: Novel Training Technique for Large-Scale Variational Quantum Circuits. arXiv preprint arXiv:2311.12929](https://arxiv.org/abs/2311.12929).\n", - "- Review the [Mitsubishi Chemical Corp case study](https://q-ctrl.com/case-study/unlocking-new-performance-capability-in-quantum-chemistry).\n", - "- Review the [Redacted bank case study](https://q-ctrl.com/case-study/reducing-quantum-compute-costs-2-500x-with-fire-opal).\n", - "- Review the [BlueQubit case study](https://q-ctrl.com/case-study/enabling-data-loading-for-quantum-machine-learning-with-fire-opal).\n", - "\n", - "\n", - "" - ] } ], "metadata": { diff --git a/docs/functions/q-ctrl-performance-management/index.ipynb b/docs/functions/q-ctrl-performance-management/index.ipynb new file mode 100644 index 000000000000..6df39e74636f --- /dev/null +++ b/docs/functions/q-ctrl-performance-management/index.ipynb @@ -0,0 +1,191 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "dde95705", + "metadata": {}, + "source": [ + "---\n", + "title: Performance Management - A Qiskit Function by Q-CTRL Fire Opal\n", + "description: Apply automated error suppression using Fire Opal Performance Management by Q-CTRL\n", + "---\n", + "\n", + "\n", + "{/* cspell:ignore fontsize, Mundada, Yamauchi, supersymmetric, Paterakis, Gharibyan */}\n", + "\n", + "# Performance Management: A Qiskit Function by Q-CTRL Fire Opal\n", + "\n", + "*See the [API reference](/docs/api/functions/q-ctrl-performance-management)*\n", + "\n", + "\n", + " Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "ace2ed13", + "metadata": { + "tags": [ + "version-info" + ] + }, + "source": [ + "{/*\n", + " DO NOT EDIT THIS CELL!!!\n", + " This cell's content is generated automatically by a script. Anything you add\n", + " here will be removed next time the notebook is run. To add new content, create\n", + " a new cell before or after this one.\n", + "*/}\n", + "\n", + "\n", + "\n", + "\n", + "The code on this page was developed using the following requirements.\n", + "We recommend using these versions or newer.\n", + "\n", + "```\n", + "qiskit[all]~=2.3.1\n", + "qiskit-ibm-runtime~=0.45.1\n", + "```\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "c1732b45", + "metadata": {}, + "source": [ + "## Overview\n", + "\n", + "Fire Opal Performance Management makes it simple for anyone to achieve meaningful results from quantum computers at scale without needing to be quantum hardware experts. When running circuits with Fire Opal Performance Management, AI-driven error suppression techniques are automatically applied, enabling the scaling of larger problems with more gates and qubits. This approach reduces the number of shots required to reach the correct answer, with no added overhead \u2014 resulting in significant savings in both compute time and cost.\n", + "\n", + "Performance Management suppresses errors and increases the probability of getting the correct answer on noisy hardware. In other words, it increases the signal-to-noise ratio. The following image shows how increased accuracy enabled by Performance Management can reduce the need for additional shots in the case of a 10-qubit Quantum Fourier Transform algorithm. With only 30 shots, Q-CTRL reaches the 99% confidence threshold, whereas the default (`QiskitRuntime` Sampler, `optimization_level`=3 and `resilience_level`=1, `ibm_sherbrooke`) requires 170,000 shots. By getting the right answer faster, you save significant compute runtime.\n", + "\n", + "![Visualization of the improved runtime](/docs/images/guides/qctrl-performance-management/achieve_more.svg)\n", + "\n", + "The Performance Management function can be used with any algorithm, and you can easily use it in place of the standard [Qiskit Runtime primitives](/docs/guides/primitives). Behind the scenes, multiple error suppression techniques work together to prevent errors from happening at runtime. All Fire Opal pipeline methods are pre-configured and algorithm-agnostic, meaning you always get the best performance out of the box.\n", + "\n", + "To get access to Performance Management, [contact Q-CTRL](https://form.typeform.com/to/uOAVDnGg?typeform-source=q-ctrl.com)." + ] + }, + { + "cell_type": "markdown", + "id": "5f761442", + "metadata": {}, + "source": [ + "## Description\n", + "\n", + "Fire Opal Performance Management has two options for execution that are similar to the Qiskit Runtime primitives, so you can easily swap in the Q-CTRL Sampler and Estimator. The general workflow for using the Performance Management function is:\n", + "1. Define your circuit (and operators in the case of the Estimator).\n", + "2. Run the circuit.\n", + "3. Retrieve the results.\n", + "\n", + "To reduce hardware noise, Fire Opal employs a range of AI-driven error suppression techniques depicted in the following image. With Fire Opal, the entire pipeline is completely automated with zero need for configuration.\n", + "\n", + "Fire Opal's pipeline eliminates the need for additional overhead, such as increased quantum runtime or extra physical qubits. Note that classical processing time remains a factor (refer to the [Benchmarks](#benchmarks) section for estimates, where \"Total time\" reflects both classical and quantum processing). In contrast to error mitigation, which requires overhead in the form of sampling, Fire Opal's error suppression works at both the gate and pulse levels to address various sources of noise and to prevent the likelihood of an error occurring. By preventing errors, the need for expensive post-processing is eliminated.\n", + "\n", + "The following image depicts the error suppression methods automated by Fire Opal Performance Management.\n", + "\n", + "![Visualization of the error suppression pipeline](/docs/images/guides/qctrl-performance-management/error_suppression.svg)\n", + "\n", + "The function offers two primitives, Sampler and Estimator, and the inputs and outputs of both extend the implemented spec for [Qiskit Runtime V2 primitives](/docs/guides/primitive-input-output#pubs)." + ] + }, + { + "cell_type": "markdown", + "id": "64534d1a", + "metadata": {}, + "source": [ + "## Benchmarks\n", + "\n", + "[Published algorithmic benchmarking](https://journals.aps.org/prapplied/abstract/10.1103/PhysRevApplied.20.024034) results demonstrate significant performance improvement across various algorithms, including Bernstein-Vazirani, quantum Fourier transform, Grover\u2019s search, quantum approximate optimization algorithm, and variational quantum eigensolver. The rest of this section provides more details about types of algorithms you can run, as well as the expected performance and runtimes.\n", + "\n", + "The following independent studies demonstrate how Q-CTRL's Performance Management enables algorithmic research at record-breaking scale:\n", + "- [Parametrized Energy-Efficient Quantum Kernels for Network Service Fault Diagnosis](https://arxiv.org/abs/2405.09724v1) - up to 50-qubit quantum kernel learning\n", + "- [Tensor-based quantum phase difference estimation for large-scale demonstration](https://arxiv.org/abs/2408.04946) - up to 33-qubit quantum phase estimation\n", + "- [Hierarchical Learning for Quantum ML: Novel Training Technique for Large-Scale Variational Quantum Circuits](https://arxiv.org/abs/2311.12929) - up to 21-qubit quantum data loading\n", + "\n", + "The following table provides a rough guide on accuracy and runtimes from prior benchmarking runs on `ibm_fez`. Performance on other devices may vary. The usage time is based on an assumption of 10,000 shots per circuit. The \"Number of qubits\" indicated is not a hard limitation but represents rough thresholds where you can expect extremely consistent solution accuracy. Larger problem sizes have been successfully solved, and testing beyond these limits is encouraged.\n", + "\n", + "\n", + "| Example | Number of qubits | Accuracy | Measure of accuracy | Total time (s) | Runtime usage (s) | Primitive (Mode) |\n", + "| --------- | ---------------- | -------------------------- | -------- | ---------- | ------------- |------------- |\n", + "| Bernstein\u2013Vazirani | 50Q | 100% | Success Rate (Percentage of runs where the correct answer is the highest count bitstring) | 10 | 8 | Sampler |\n", + "| Quantum Fourier Transform | 30Q | 100% | Success Rate (Percentage of runs where the correct answer is the highest count bitstring) | 10 | 8 | Sampler |\n", + "| Quantum Phase Estimation | 30Q | 99.9998% | Accuracy of the angle found: `1- abs(real_angle - angle_found)/pi` | 10 | 8 | Sampler |\n", + "| Quantum simulation: Ising model (15 steps) | 20Q | 99.775% | $A$ (defined below) | 60 (per step) | 15 (per step) | Estimator |\n", + "| Quantum simulation 2: molecular dynamics (20 time points) | 34Q | 96.78% | $A_{mean}$ (defined below) | 10 (per time point) | 6 (per time point) | Estimator |\n", + "\n", + "Defining the accuracy of the measurement of an expectation value - the metric $A$ is defined as follows:\n", + "$$\n", + "A = 1 - \\frac{|\\epsilon^{ideal} - \\epsilon^{meas}|}{\\epsilon^{ideal}_{max} - \\epsilon^{ideal}_{min}},\n", + "$$\n", + "where $ \\epsilon^{ideal} $ = ideal expectation value, $ \\epsilon^{meas} $ = measured expectation value, $\\epsilon^{ideal}_{max} $ = ideal maximum value, and $\\epsilon^{ideal}_{min}$ = ideal minimum value. $A_{mean}$ is simply the average of the value of $A$ across multiple measurements.\n", + "\n", + "This metric is used because it is invariant to global shifts and scaling in the range of attainable values. In other words, regardless of whether you shift the range of possible expectation values higher or lower or increase the spread, the value of $A$ should remain consistent." + ] + }, + { + "cell_type": "markdown", + "id": "bb33258d", + "metadata": {}, + "source": [ + "## Get support\n", + "\n", + "For any questions or issues, [contact Q-CTRL](https://form.typeform.com/to/iuujEAEI)." + ] + }, + { + "cell_type": "markdown", + "id": "2fe4a6ea", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + "\n", + "- Request access to [Q-CTRL Performance Management](https://quantum.cloud.ibm.com/functions?id=q-ctrl-performance-management).\n", + "- Visit the [API reference](/docs/api/functions/q-ctrl-performance-management) for this Qiskit Function.\n", + "- Try the [Transverse-Field Ising Model with Q-CTRL's Performance Management](/docs/tutorials/transverse-field-ising-model) tutorial.\n", + "- Try the [Quantum Phase Estimation with Q-CTRL's Qiskit Functions](/docs/tutorials/quantum-phase-estimation-qctrl) tutorial\n", + "- Review [Mundada P. S., et al. (2023). Experimental Benchmarking of an Automated Deterministic Error-Suppression Workflow for Quantum Algorithms. Physical Review Applied, 20, 2](https://quantum-journal.org/papers/q-2023-07-25-1067/).\n", + "- Review [Kanno, S., et al. (2025). Tensor-based quantum phase difference estimation for large-scale demonstration. arXiv preprint arXiv:2408.04946](https://arxiv.org/abs/2408.04946).\n", + "- Review [SoftBank Corp, Demonstration Experiment of a Communication Service Fault Diagnosis System Using Quantum Machine Learning (blog), 30 August, 2024](https://www.softbank.jp/en/corp/technology/research/topics/102/).\n", + "- Review [Yamauchi, H., et al. (2024). Parametrized Energy-Efficient Quantum Kernels for Network Service Fault Diagnosis. arXiv preprint arXiv:2405.09724v1](https://arxiv.org/abs/2405.09724v1).\n", + "- Review [Yamauchi, H., et al. (2025). Quantum spectroscopy of topological dynamics via a supersymmetric Hamiltonian. arXiv preprint arXiv:2511.23169v1](https://arxiv.org/abs/2511.23169v1).\n", + "- Review [Wang, Y., et al. (2025). \u0394-Motif: Subgraph Isomorphism at Scale via Data-Centric Parallelism. arXiv preprint arXiv:2508.21287](https://arxiv.org/abs/2508.21287).\n", + "- Review [Paterakis, N. G., et al. (2025). Quantum Computing in the Computational Landscape of Power Electronics: Vision and Reality. arXiv preprint arXiv:2507.02577](https://arxiv.org/abs/2507.02577).\n", + "- Review [Gharibyan, H., et al. (2023). Hierarchical Learning for Quantum ML: Novel Training Technique for Large-Scale Variational Quantum Circuits. arXiv preprint arXiv:2311.12929](https://arxiv.org/abs/2311.12929).\n", + "- Review the [Mitsubishi Chemical Corp case study](https://q-ctrl.com/case-study/unlocking-new-performance-capability-in-quantum-chemistry).\n", + "- Review the [Redacted bank case study](https://q-ctrl.com/case-study/reducing-quantum-compute-costs-2-500x-with-fire-opal).\n", + "- Review the [BlueQubit case study](https://q-ctrl.com/case-study/enabling-data-loading-for-quantum-machine-learning-with-fire-opal).\n", + "\n", + "\n", + "" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/functions/q-ctrl-performance-management/performance-tuning.mdx b/docs/functions/q-ctrl-performance-management/performance-tuning.mdx new file mode 100644 index 000000000000..64c62f104347 --- /dev/null +++ b/docs/functions/q-ctrl-performance-management/performance-tuning.mdx @@ -0,0 +1,25 @@ +--- +title: Advanced techniques with Q-CTRL Performance Management +description: Practical guidance for choosing between Estimator and Sampler, and tuning shots and precision. +--- + +*Q-CTRL is encouraged to expand this page with vendor-specific tuning guidance. The suggestions below are derived from the API reference and are intended as a starting point.* + +## Estimator vs Sampler: which to use + +The function exposes both an Estimator primitive (`estimator.run()`) and a Sampler primitive (`sampler.run()`). Choose based on your workload: + +- **Estimator** — use when you need expectation values of observables (for example, energy estimation, variational algorithms). Supports `default_precision` to target a specific error bound. +- **Sampler** — use when you need bitstring distributions or measurement outcomes (for example, combinatorial optimization, classification tasks). Controlled via `default_shots`. + +You cannot mix primitives within a session — pick the one that matches your algorithm's output type. + +## Precision vs shots + +For the Estimator, set either `default_precision` or `default_shots` — not both. Use `default_precision` when you have an accuracy target; use `default_shots` when you have a budget constraint. + +## Session reuse + +Use `session_id` to attach subsequent jobs to an already-open session, reducing session-open overhead across batched workloads. + +See the [API reference](/docs/api/functions/q-ctrl-performance-management) for full parameter details. diff --git a/docs/functions/qedma-qesem/_toc.json b/docs/functions/qedma-qesem/_toc.json new file mode 100644 index 000000000000..6e392aa99ebb --- /dev/null +++ b/docs/functions/qedma-qesem/_toc.json @@ -0,0 +1,50 @@ +{ + "parentUrl": "/docs/guides/functions", + "parentLabel": "Qiskit Functions", + "title": "Qedma QESEM", + "collapsed": true, + "children": [ + { + "title": "", + "collapsible": false, + "children": [ + { + "title": "Overview", + "url": "/docs/functions/qedma-qesem" + }, + { + "title": "Get started", + "url": "/docs/functions/qedma-qesem/get-started" + }, + { + "title": "Advanced techniques with Qedma QESEM", + "url": "/docs/functions/qedma-qesem/performance-tuning" + }, + { + "title": "Changelog", + "url": "/docs/functions/qedma-qesem/changelog" + } + ] + }, + { + "title": "Tutorials", + "collapsible": false, + "children": [ + { + "title": "Simulate 2D tilted-field Ising with the QESEM function", + "url": "/docs/tutorials/qedma-2d-ising-with-qesem" + } + ] + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "/docs/api/functions/qedma-qesem" + } + ] + } + ] +} diff --git a/docs/functions/qedma-qesem/changelog.mdx b/docs/functions/qedma-qesem/changelog.mdx new file mode 100644 index 000000000000..420793b583cb --- /dev/null +++ b/docs/functions/qedma-qesem/changelog.mdx @@ -0,0 +1,6 @@ +--- +title: Changelog +description: Changelog for the QESEM Qiskit Function. +--- + +*This section is under development. Qedma is encouraged to maintain a changelog here as new features and updates are released.* diff --git a/docs/functions/qedma-qesem/get-started.ipynb b/docs/functions/qedma-qesem/get-started.ipynb new file mode 100644 index 000000000000..4e6293f79265 --- /dev/null +++ b/docs/functions/qedma-qesem/get-started.ipynb @@ -0,0 +1,242 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "page-frontmatter", + "metadata": {}, + "source": [ + "---\ntitle: Get started with Qedma QESEM\ndescription: Get started with QESEM — authenticate, load the function, and run examples including QPU time estimation and expectation value computation.\n---" + ] + }, + { + "cell_type": "markdown", + "id": "d6fb65de", + "metadata": {}, + "source": [ + "## Setup and load function\n\nAuthenticate using your [IBM Quantum Platform API key](http://quantum.cloud.ibm.com/), and select the QESEM Qiskit Function as follows. (This snippet assumes you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment.)" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "95a715d2", + "metadata": {}, + "outputs": [], + "source": [ + "import qiskit\n", + "\n", + "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", + "\n", + "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n", + "\n", + "qesem_function = catalog.load(\"qedma/qesem\")" + ] + }, + { + "cell_type": "markdown", + "id": "5f0120d8", + "metadata": {}, + "source": [ + "## Run your first workload\n\nTo get started, try this basic example of estimating the required QPU time to run QESEM for a given `pub`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2fb4efc4", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# This cell is hidden from users\n", + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend_name = service.least_busy().name" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d56e1440", + "metadata": {}, + "outputs": [], + "source": [ + "circ = qiskit.QuantumCircuit(5)\n", + "circ.cx(0, 1)\n", + "circ.cx(2, 3)\n", + "circ.cx(1, 2)\n", + "circ.cx(3, 4)\n", + "\n", + "avg_magnetization = qiskit.quantum_info.SparsePauliOp.from_sparse_list(\n", + " [(\"Z\", [q], 1 / 5) for q in range(5)], num_qubits=5\n", + ")\n", + "other_observable = qiskit.quantum_info.SparsePauliOp.from_sparse_list(\n", + " [(\"ZZ\", [0, 1], 1.0), (\"XZ\", [1, 4], 0.5)], num_qubits=5\n", + ")\n", + "\n", + "time_estimation_job = qesem_function.run(\n", + " pubs=[(circ, [avg_magnetization, other_observable])],\n", + " options={\n", + " \"estimate_time_only\": \"analytical\",\n", + " },\n", + " backend_name=backend_name, # E.g. \"ibm_fez\"\n", + ")\n", + "\n", + "time_estimate_result = time_estimation_job.result()" + ] + }, + { + "cell_type": "markdown", + "id": "ae10a4c8", + "metadata": {}, + "source": [ + "The following example executes a QESEM job:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e7351d6b", + "metadata": {}, + "outputs": [], + "source": [ + "sample_job = qesem_function.run(\n", + " pubs=[(circ, [avg_magnetization, other_observable])],\n", + " backend_name=backend_name, # E.g. \"ibm_fez\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "dfe99043", + "metadata": {}, + "source": [ + "You can use the familiar Qiskit Serverless APIs to check your Qiskit Function workload's status or return results:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "856fe992", + "metadata": {}, + "outputs": [], + "source": [ + "print(sample_job.status())\n", + "result = sample_job.result()" + ] + }, + { + "cell_type": "markdown", + "id": "5ec8053b", + "metadata": {}, + "source": [ + "The following code snippet describes how to retrieve the QPU time estimation (`estimate_time_only` is set):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "48821756", + "metadata": {}, + "outputs": [], + "source": [ + "print(\n", + " f\"The estimated QPU time for this PUB is: \"\n", + " f\"\\n{time_estimate_result[0].metadata}\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "a9e51542", + "metadata": {}, + "source": [ + "The following code snippet demonstrates how to retrieve the mitigation results (when `estimate_time_only` is not set) and execution metrics. These contain essential data that enables a deeper understanding of how different parameters impact the QESEM execution. It may also be relevant when writing a paper based on your research." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fda5f739", + "metadata": {}, + "outputs": [], + "source": [ + "results = result[0]\n", + "print(f\"Mitigated expectation values: \\n{results.data.evs}\")\n", + "print(f\"Mitigated error-bar: \\n{results.data.stds}\")\n", + "noisy_results = results.metadata[\"noisy_results\"]\n", + "print(f\"Noisy expectation values: \\n{noisy_results.evs}\")\n", + "print(f\"Noisy error-bar: \\n{noisy_results.stds}\")\n", + "print(f\"Total QPU time: \\n {results.metadata['total_qpu_time']}\")\n", + "print(\n", + " f\"Gates fidelity measured during the experiment: \"\n", + " f\"\\n {results.metadata['gate_fidelities']}\"\n", + ")\n", + "print(\n", + " f\"Total shots / mitigation shots: \\n \"\n", + " f\"{results.metadata['total_shots']} / \"\n", + " f\"{results.metadata['mitigation_shots']}\"\n", + ")\n", + "print(\"Transpiled circuits:\")\n", + "for i, circuit in enumerate(results.metadata[\"transpiled_circs\"]):\n", + " print(f\"Circuit {i}:\")\n", + " print(f\" Circuit: \\n {circuit['circuit']}\")\n", + " print(f\" Qubit mapping: \\n {circuit['qubit_map']}\")\n", + " print(f\" Measurement bases: \\n {circuit['num_measurement_bases']}\")" + ] + }, + { + "cell_type": "markdown", + "id": "35aed54a", + "metadata": {}, + "source": [ + "## Fetch error messages\n", + "\n", + "If your workload status is ERROR, use `job.result()` to fetch the error message to fetch the error message as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d95a3f30", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "PrimitiveResult([PubResult(data=DataBin(), metadata={'time_estimation_sec': 12600})], metadata={})\n" + ] + } + ], + "source": [ + "print(sample_job.result())" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/functions/circuit-functions/qedma-qesem.ipynb b/docs/functions/qedma-qesem/index.ipynb similarity index 69% rename from docs/functions/circuit-functions/qedma-qesem.ipynb rename to docs/functions/qedma-qesem/index.ipynb index e0b9da8410bf..3f25bf090a49 100644 --- a/docs/functions/circuit-functions/qedma-qesem.ipynb +++ b/docs/functions/qedma-qesem/index.ipynb @@ -23,16 +23,6 @@ "*See the [API reference](/docs/api/functions/qedma-qesem)*" ] }, - { - "cell_type": "markdown", - "id": "6256578e", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [] - }, { "cell_type": "markdown", "id": "13528739", @@ -111,219 +101,6 @@ "The VQE circuit was developed together with researchers from the Center for Quantum Technology and Applications at the Deutsches Elektronen-Synchrotron (DESY). The target observable here was a Hamiltonian consisting of a large number of non-commuting Pauli strings, emphasizing QESEM's optimized performance for multi-basis observables. Mitigation was applied to a classically-optimized ansatz; although these results are still unpublished, results of the same quality will be obtained for different circuits with similar structural properties." ] }, - { - "cell_type": "markdown", - "id": "d6fb65de", - "metadata": {}, - "source": [ - "## Get started\n", - "\n", - "Authenticate using your [IBM Quantum Platform API key](http://quantum.cloud.ibm.com/), and select the QESEM Qiskit Function as follows. (This snippet assumes you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment.)" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "95a715d2", - "metadata": {}, - "outputs": [], - "source": [ - "import qiskit\n", - "\n", - "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", - "\n", - "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n", - "\n", - "qesem_function = catalog.load(\"qedma/qesem\")" - ] - }, - { - "cell_type": "markdown", - "id": "5f0120d8", - "metadata": {}, - "source": [ - "## Examples\n", - "\n", - "To get started, try this basic example of estimating the required QPU time to run QESEM for a given `pub`:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "2fb4efc4", - "metadata": { - "tags": [ - "remove-cell" - ] - }, - "outputs": [], - "source": [ - "# This cell is hidden from users\n", - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend_name = service.least_busy().name" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "d56e1440", - "metadata": {}, - "outputs": [], - "source": [ - "circ = qiskit.QuantumCircuit(5)\n", - "circ.cx(0, 1)\n", - "circ.cx(2, 3)\n", - "circ.cx(1, 2)\n", - "circ.cx(3, 4)\n", - "\n", - "avg_magnetization = qiskit.quantum_info.SparsePauliOp.from_sparse_list(\n", - " [(\"Z\", [q], 1 / 5) for q in range(5)], num_qubits=5\n", - ")\n", - "other_observable = qiskit.quantum_info.SparsePauliOp.from_sparse_list(\n", - " [(\"ZZ\", [0, 1], 1.0), (\"XZ\", [1, 4], 0.5)], num_qubits=5\n", - ")\n", - "\n", - "time_estimation_job = qesem_function.run(\n", - " pubs=[(circ, [avg_magnetization, other_observable])],\n", - " options={\n", - " \"estimate_time_only\": \"analytical\",\n", - " },\n", - " backend_name=backend_name, # E.g. \"ibm_fez\"\n", - ")\n", - "\n", - "time_estimate_result = time_estimation_job.result()" - ] - }, - { - "cell_type": "markdown", - "id": "ae10a4c8", - "metadata": {}, - "source": [ - "The following example executes a QESEM job:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "e7351d6b", - "metadata": {}, - "outputs": [], - "source": [ - "sample_job = qesem_function.run(\n", - " pubs=[(circ, [avg_magnetization, other_observable])],\n", - " backend_name=backend_name, # E.g. \"ibm_fez\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "dfe99043", - "metadata": {}, - "source": [ - "You can use the familiar Qiskit Serverless APIs to check your Qiskit Function workload's status or return results:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "856fe992", - "metadata": {}, - "outputs": [], - "source": [ - "print(sample_job.status())\n", - "result = sample_job.result()" - ] - }, - { - "cell_type": "markdown", - "id": "5ec8053b", - "metadata": {}, - "source": [ - "The following code snippet describes how to retrieve the QPU time estimation (`estimate_time_only` is set):" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "48821756", - "metadata": {}, - "outputs": [], - "source": [ - "print(\n", - " f\"The estimated QPU time for this PUB is: \"\n", - " f\"\\n{time_estimate_result[0].metadata}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "a9e51542", - "metadata": {}, - "source": [ - "The following code snippet demonstrates how to retrieve the mitigation results (when `estimate_time_only` is not set) and execution metrics. These contain essential data that enables a deeper understanding of how different parameters impact the QESEM execution. It may also be relevant when writing a paper based on your research." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "fda5f739", - "metadata": {}, - "outputs": [], - "source": [ - "results = result[0]\n", - "print(f\"Mitigated expectation values: \\n{results.data.evs}\")\n", - "print(f\"Mitigated error-bar: \\n{results.data.stds}\")\n", - "noisy_results = results.metadata[\"noisy_results\"]\n", - "print(f\"Noisy expectation values: \\n{noisy_results.evs}\")\n", - "print(f\"Noisy error-bar: \\n{noisy_results.stds}\")\n", - "print(f\"Total QPU time: \\n {results.metadata['total_qpu_time']}\")\n", - "print(\n", - " f\"Gates fidelity measured during the experiment: \"\n", - " f\"\\n {results.metadata['gate_fidelities']}\"\n", - ")\n", - "print(\n", - " f\"Total shots / mitigation shots: \\n \"\n", - " f\"{results.metadata['total_shots']} / \"\n", - " f\"{results.metadata['mitigation_shots']}\"\n", - ")\n", - "print(\"Transpiled circuits:\")\n", - "for i, circuit in enumerate(results.metadata[\"transpiled_circs\"]):\n", - " print(f\"Circuit {i}:\")\n", - " print(f\" Circuit: \\n {circuit['circuit']}\")\n", - " print(f\" Qubit mapping: \\n {circuit['qubit_map']}\")\n", - " print(f\" Measurement bases: \\n {circuit['num_measurement_bases']}\")" - ] - }, - { - "cell_type": "markdown", - "id": "35aed54a", - "metadata": {}, - "source": [ - "## Fetch error messages\n", - "\n", - "If your workload status is ERROR, use `job.result()` to fetch the error message to fetch the error message as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "d95a3f30", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "PrimitiveResult([PubResult(data=DataBin(), metadata={'time_estimation_sec': 12600})], metadata={})\n" - ] - } - ], - "source": [ - "print(sample_job.result())" - ] - }, { "cell_type": "markdown", "id": "e9ec2e67", diff --git a/docs/functions/qedma-qesem/performance-tuning.mdx b/docs/functions/qedma-qesem/performance-tuning.mdx new file mode 100644 index 000000000000..bf222c04a5df --- /dev/null +++ b/docs/functions/qedma-qesem/performance-tuning.mdx @@ -0,0 +1,22 @@ +--- +title: Advanced techniques with Qedma QESEM +description: Practical guidance for tuning accuracy, QPU time, and cost when using the QESEM Qiskit Function. +--- + +*Qedma is encouraged to expand this page with vendor-specific tuning guidance. The suggestions below are derived from the API reference and are intended as a starting point.* + +## Estimating QPU time before committing + +QESEM supports a dry-run mode via `estimate_time_only` in the Options. Use this before submitting a full job to get a QPU-time estimate and avoid unexpected costs on large circuits. + +## Backend and instance selection + +The `backend_name` and `instance` parameters control which QPU and Qiskit Runtime instance are used. QESEM's overhead scales with circuit size and backend noise characteristics — choosing a backend well-matched to your circuit connectivity reduces transpilation overhead. + +## Circuit size and accuracy + +QESEM's accuracy guarantees are demonstrated in the benchmarks on the Overview page. For circuits near the documented size limits, expect longer QPU times and consider whether a smaller sub-circuit experiment can validate the approach before scaling up. + +## Options reference + +See the [API reference](/docs/api/functions/qedma-qesem) for the full Options parameter list, including `estimate_time_only` and backend selection details. diff --git a/docs/functions/qunova-chemistry/_toc.json b/docs/functions/qunova-chemistry/_toc.json new file mode 100644 index 000000000000..e80618490223 --- /dev/null +++ b/docs/functions/qunova-chemistry/_toc.json @@ -0,0 +1,50 @@ +{ + "parentUrl": "/docs/guides/functions", + "parentLabel": "Qiskit Functions", + "title": "HI-VQE Chemistry: A Qiskit Function by Qunova Computing", + "collapsed": true, + "children": [ + { + "title": "", + "collapsible": false, + "children": [ + { + "title": "Overview", + "url": "/docs/functions/qunova-chemistry" + }, + { + "title": "Get started", + "url": "/docs/functions/qunova-chemistry/get-started" + }, + { + "title": "Advanced techniques with HI-VQE Chemistry", + "url": "/docs/functions/qunova-chemistry/performance-tuning" + }, + { + "title": "Changelog", + "url": "/docs/functions/qunova-chemistry/changelog" + } + ] + }, + { + "title": "Tutorials", + "collapsible": false, + "children": [ + { + "title": "Dissociation PES curves with Qunova HiVQE", + "url": "/docs/tutorials/qunova-hivqe" + } + ] + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "/docs/api/functions/qunova-chemistry" + } + ] + } + ] +} diff --git a/docs/functions/qunova-chemistry/changelog.mdx b/docs/functions/qunova-chemistry/changelog.mdx new file mode 100644 index 000000000000..f914c9d06a0b --- /dev/null +++ b/docs/functions/qunova-chemistry/changelog.mdx @@ -0,0 +1,6 @@ +--- +title: Changelog +description: Changelog for HI-VQE Chemistry. +--- + +*This section is under development. Qunova Computing is encouraged to maintain a changelog here as new features and updates are released.* diff --git a/docs/functions/qunova-chemistry/get-started.ipynb b/docs/functions/qunova-chemistry/get-started.ipynb new file mode 100644 index 000000000000..50ce06aad32f --- /dev/null +++ b/docs/functions/qunova-chemistry/get-started.ipynb @@ -0,0 +1,261 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "page-frontmatter", + "metadata": {}, + "source": [ + "---\ntitle: Get started with HI-VQE Chemistry\ndescription: Get started with HI-VQE Chemistry — authenticate, load the function, and compute molecular ground state energies.\n---" + ] + }, + { + "cell_type": "markdown", + "id": "73390a19", + "metadata": {}, + "source": [ + "## Setup and load function\n\nFirst, [request access to the function](https://forms.office.com/r/zN3hvMTqJ1).\nThen, authenticate using your [IBM Quantum® API key](http://quantum.cloud.ibm.com/) and, assuming you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment, select the Qiskit Function as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "95a715d2", + "metadata": {}, + "outputs": [], + "source": [ + "import reprlib\n", + "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", + "\n", + "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n", + "\n", + "function = catalog.load(\"qunova/hivqe-chemistry\")" + ] + }, + { + "cell_type": "markdown", + "id": "c3e0cc98", + "metadata": {}, + "source": [ + "## Run your first workload\n\nThe first example shows how to compute the ground state energy for an NH3 molecule using the HI-VQE algorithm." + ] + }, + { + "cell_type": "markdown", + "id": "b03aa968", + "metadata": {}, + "source": [ + "#### Define the molecular geometry and options\n", + "\n", + "The molecular geometry of NH3 is provided with Cartesian coordinates separated with \";\" for each atom." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "970dadd1", + "metadata": {}, + "outputs": [], + "source": [ + "# Define the molecule geometry\n", + "geometry = \"\"\"\n", + "N -0.85188 -0.02741 0.03141;\n", + "H 0.16545 0.00593 -0.01648;\n", + "H -1.16348 -0.39357 -0.86702;\n", + "H -1.16348 0.94228 0.06281;\n", + "\"\"\"" + ] + }, + { + "cell_type": "markdown", + "id": "64429e13", + "metadata": {}, + "source": [ + "Additional options can be defined and provided for molecular system in the following dictionary format." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "0f9e9a3c", + "metadata": {}, + "outputs": [], + "source": [ + "# Configure some options for the job.\n", + "molecule_options = {\"basis\": \"sto3g\"}\n", + "hivqe_options = {\"shots\": 100, \"max_iter\": 20}" + ] + }, + { + "cell_type": "markdown", + "id": "bf180336", + "metadata": {}, + "source": [ + "Execute the function with geometry and option inputs." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fdebf7f0", + "metadata": {}, + "outputs": [], + "source": [ + "# Run HI-VQE\n", + "job = function.run(\n", + " geometry=geometry,\n", + " # `backend_name` is the name of a backend with at least 16 qubits,\n", + " # for example, \"ibm_marrakesh\".\n", + " backend_name=backend_name,\n", + " max_states=2000,\n", + " max_expansion_states=10,\n", + " molecule_options=molecule_options,\n", + " hivqe_options=hivqe_options,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "75e46808-1638-4f14-bfe4-ea3eba2f738b", + "metadata": {}, + "source": [ + "It is a good idea to print the Function job ID so that it can be provided in support requests if something goes wrong." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "87585ede-2ec4-467a-a269-514f59026602", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Job ID: e5ced6f2-fd1d-4244-a6aa-bd27cfb0cdee\n" + ] + } + ], + "source": [ + "print(\"Job ID:\", job.job_id)" + ] + }, + { + "cell_type": "markdown", + "id": "608cf736", + "metadata": {}, + "source": [ + "This example then utilizes 16 qubits with 8 orbitals of sto3g basis for an NH3 molecule." + ] + }, + { + "cell_type": "markdown", + "id": "ad1c9bcb", + "metadata": {}, + "source": [ + "Check your Qiskit Function workload's [status](/docs/guides/functions#check-job-status) or return [results](/docs/guides/functions#retrieve-results) as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "b442c581", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "QUEUED\n" + ] + } + ], + "source": [ + "print(job.status())" + ] + }, + { + "cell_type": "markdown", + "id": "aef704b8", + "metadata": {}, + "source": [ + "After the job is completed, the results can be obtained with `result()` instance." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "f447e506", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{'eigenvector': [0.9824448589364075, 0.009527106392132133, 6.854074372058527e-08, 3.591500190038039e-07, 0.0012975231577544268, 2.310159709002111e-05, ...], 'energy': -55.52108557170985, 'energy_history': [-55.51901898989887, -55.52056881448526, -55.52065046778772, -55.520690696813716, -55.520691108428, -55.520708448092634, ...], 'energy_variance': 3.066239097617371e-10, ...}\n" + ] + } + ], + "source": [ + "result = job.result()\n", + "\n", + "# Output can be long, so we display a shortened representation\n", + "shortened_result = reprlib.repr(result)\n", + "print(shortened_result)" + ] + }, + { + "cell_type": "markdown", + "id": "2b6fb05c", + "metadata": {}, + "source": [ + "To access the ground state energy, use the \"energy\" key. The \"eigenvector\" key provides the CI coefficients with corresponding bitstring notation of electron configuration stored with \"states\" of the results." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "28cd677c", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "|Exact Energy - HI-VQE Energy|: 0.06246299427914437 mHa\n", + "Sampled Number of States: 1936\n" + ] + } + ], + "source": [ + "fci_energy = -55.521148034704126 # the exact energy using FCI method\n", + "hivqe_energy = result[\"energy\"]\n", + "print(\n", + " f\"|Exact Energy - HI-VQE Energy|: \"\n", + " f\"{abs(fci_energy - hivqe_energy) * 1000} mHa\"\n", + ")\n", + "print(f\"Sampled Number of States: {len(result['states'])}\")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/functions/application-functions/qunova-chemistry.ipynb b/docs/functions/qunova-chemistry/index.ipynb similarity index 57% rename from docs/functions/application-functions/qunova-chemistry.ipynb rename to docs/functions/qunova-chemistry/index.ipynb index 66f285ad8919..6bb38f3ba7bc 100644 --- a/docs/functions/application-functions/qunova-chemistry.ipynb +++ b/docs/functions/qunova-chemistry/index.ipynb @@ -83,7 +83,7 @@ "source": [ "## Overview\n", "\n", - "In quantum chemistry, the electronic structure problem focuses on finding the solutions to the electronic Schrödinger equation - the quantum wave functions describing the behavior of the system's electrons. These wave functions are vectors of complex amplitudes, with each amplitude corresponding to the contribution of a possible electron configuration.\n", + "In quantum chemistry, the electronic structure problem focuses on finding the solutions to the electronic Schr\u00f6dinger equation - the quantum wave functions describing the behavior of the system's electrons. These wave functions are vectors of complex amplitudes, with each amplitude corresponding to the contribution of a possible electron configuration.\n", "\n", "The ground state is the lowest energy wave function of the system and has a special importance in the study of molecular systems. The most accurate approach for computing the ground state considers all possible electron configurations, but this becomes intractable for larger systems since the number of configurations grows exponentially with system size.\n", "\n", @@ -105,7 +105,7 @@ "source": [ "## Description\n", "\n", - "The number of electron configurations for a molecular system grows exponentially with system size. However, for certain electronic states, such as the ground state, it is common that only a small fraction of configurations significantly contribute to the state’s energy. Selected configuration interaction (SCI) methods exploit this sparsity to reduce computational costs by identifying and focusing on the most relevant configurations. This subset of configurations is referred to as a subspace.\n", + "The number of electron configurations for a molecular system grows exponentially with system size. However, for certain electronic states, such as the ground state, it is common that only a small fraction of configurations significantly contribute to the state\u2019s energy. Selected configuration interaction (SCI) methods exploit this sparsity to reduce computational costs by identifying and focusing on the most relevant configurations. This subset of configurations is referred to as a subspace.\n", "\n", "HI-VQE leverages the inherent efficiency of quantum computers for representing molecular systems to aid the subspace search. It integrates classical and quantum subroutines to solve the electronic structure problem with high accuracy. Unlike existing quantum SCI methods, HI-VQE combines variational training, iterative subspace construction, and pre-diagonalization configuration screening to enhance efficiency by reducing quantum measurements, iterations, and classical diagonalization costs. HI-VQE can therefore be applied to larger molecular systems which require more qubits, and reduces the cost to solve a problem of a given size to the same degree of accuracy.\n", "\n", @@ -113,7 +113,7 @@ "\n", "To compute a system's ground state, HI-VQE first uses the classical chemistry package PySCF to generate a molecular representation from user-provided inputs, such as the molecular geometry and other molecular information. It then enters a hybrid quantum-classical optimization loop, iteratively refining a subspace to optimally represent the ground state while minimizing the number of configurations included. The loop continues until convergence criteria, such as subspace size or energy stability, are met, after which the computed ground state wave function and energy are output. These results can be used to construct accurate potential energy surfaces and perform further analysis of the system.\n", "\n", - "The optimization loop focuses on adjusting a quantum circuit’s parameters to generate a high-quality subspace. HI-VQE offers three quantum circuit options: [`excitation_preserving`](/docs/api/qiskit/qiskit.circuit.library.excitation_preserving), [efficient_su2](/docs/api/qiskit/qiskit.circuit.library.efficient_su2), and [LUCJ](https://qiskit-community.github.io/ffsim/explanations/lucj.html). The optimization is initialized close to the Hartree-Fock reference state due to its general suitability. The circuit is then executed on a quantum device and configurations are sampled from the resulting quantum state before being returned as binary strings. Due to quantum device noise, some sampled configurations may be physically invalid, failing to conserve electron number or spin. HI-VQE addresses this using the configuration recovery process from the [qiskit-addon-sqd](/docs/guides/qiskit-addons-sqd#sample-based-quantum-diagonalization-sqd-overview) package, so that users can either correct invalid configurations or discard them.\n", + "The optimization loop focuses on adjusting a quantum circuit\u2019s parameters to generate a high-quality subspace. HI-VQE offers three quantum circuit options: [`excitation_preserving`](/docs/api/qiskit/qiskit.circuit.library.excitation_preserving), [efficient_su2](/docs/api/qiskit/qiskit.circuit.library.efficient_su2), and [LUCJ](https://qiskit-community.github.io/ffsim/explanations/lucj.html). The optimization is initialized close to the Hartree-Fock reference state due to its general suitability. The circuit is then executed on a quantum device and configurations are sampled from the resulting quantum state before being returned as binary strings. Due to quantum device noise, some sampled configurations may be physically invalid, failing to conserve electron number or spin. HI-VQE addresses this using the configuration recovery process from the [qiskit-addon-sqd](/docs/guides/qiskit-addons-sqd#sample-based-quantum-diagonalization-sqd-overview) package, so that users can either correct invalid configurations or discard them.\n", "\n", "The valid configurations then undergo an optional screening step to remove those predicted to contribute minimally. This reduces the dimension of the subspace, thereby lowering the cost of the diagonalization step. If the screening is enabled, then a preliminary subspace Hamiltonian is constructed from the valid configurations and a diagonalization is performed with very loose termination critieria. Though the accuracy of the resulting amplitudes for each configuration is low, it is effective for predicting which configurations to leave out of the subspace this iteration, and it is fast to compute.\n", "\n", @@ -140,347 +140,6 @@ "Please email [qiskit.support@qunovacomputing.com](mailto:qiskit.support@qunovacomputing.com) if you would like to inquire about obtaining a license." ] }, - { - "cell_type": "markdown", - "id": "73390a19", - "metadata": {}, - "source": [ - "## Get started\n", - "\n", - "First, [request access to the function](https://forms.office.com/r/zN3hvMTqJ1).\n", - "Then, authenticate using your [IBM Quantum® API key](http://quantum.cloud.ibm.com/) and, assuming you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment, select the Qiskit Function as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "95a715d2", - "metadata": {}, - "outputs": [], - "source": [ - "import reprlib\n", - "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", - "\n", - "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n", - "\n", - "function = catalog.load(\"qunova/hivqe-chemistry\")" - ] - }, - { - "cell_type": "markdown", - "id": "c3e0cc98", - "metadata": {}, - "source": [ - "## Example\n", - "\n", - "The first example shows how to compute the ground state energy for an NH3 molecule using the HI-VQE algorithm." - ] - }, - { - "cell_type": "markdown", - "id": "b03aa968", - "metadata": {}, - "source": [ - "#### Define the molecular geometry and options\n", - "\n", - "The molecular geometry of NH3 is provided with Cartesian coordinates separated with \";\" for each atom." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "970dadd1", - "metadata": {}, - "outputs": [], - "source": [ - "# Define the molecule geometry\n", - "geometry = \"\"\"\n", - "N -0.85188 -0.02741 0.03141;\n", - "H 0.16545 0.00593 -0.01648;\n", - "H -1.16348 -0.39357 -0.86702;\n", - "H -1.16348 0.94228 0.06281;\n", - "\"\"\"" - ] - }, - { - "cell_type": "markdown", - "id": "64429e13", - "metadata": {}, - "source": [ - "Additional options can be defined and provided for molecular system in the following dictionary format." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "0f9e9a3c", - "metadata": {}, - "outputs": [], - "source": [ - "# Configure some options for the job.\n", - "molecule_options = {\"basis\": \"sto3g\"}\n", - "hivqe_options = {\"shots\": 100, \"max_iter\": 20}" - ] - }, - { - "cell_type": "markdown", - "id": "bf180336", - "metadata": {}, - "source": [ - "Execute the function with geometry and option inputs." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "fdebf7f0", - "metadata": {}, - "outputs": [], - "source": [ - "# Run HI-VQE\n", - "job = function.run(\n", - " geometry=geometry,\n", - " # `backend_name` is the name of a backend with at least 16 qubits,\n", - " # for example, \"ibm_marrakesh\".\n", - " backend_name=backend_name,\n", - " max_states=2000,\n", - " max_expansion_states=10,\n", - " molecule_options=molecule_options,\n", - " hivqe_options=hivqe_options,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "75e46808-1638-4f14-bfe4-ea3eba2f738b", - "metadata": {}, - "source": [ - "It is a good idea to print the Function job ID so that it can be provided in support requests if something goes wrong." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "87585ede-2ec4-467a-a269-514f59026602", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Job ID: e5ced6f2-fd1d-4244-a6aa-bd27cfb0cdee\n" - ] - } - ], - "source": [ - "print(\"Job ID:\", job.job_id)" - ] - }, - { - "cell_type": "markdown", - "id": "608cf736", - "metadata": {}, - "source": [ - "This example then utilizes 16 qubits with 8 orbitals of sto3g basis for an NH3 molecule." - ] - }, - { - "cell_type": "markdown", - "id": "ad1c9bcb", - "metadata": {}, - "source": [ - "Check your Qiskit Function workload's [status](/docs/guides/functions#check-job-status) or return [results](/docs/guides/functions#retrieve-results) as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "b442c581", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "QUEUED\n" - ] - } - ], - "source": [ - "print(job.status())" - ] - }, - { - "cell_type": "markdown", - "id": "aef704b8", - "metadata": {}, - "source": [ - "After the job is completed, the results can be obtained with `result()` instance." - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "f447e506", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "{'eigenvector': [0.9824448589364075, 0.009527106392132133, 6.854074372058527e-08, 3.591500190038039e-07, 0.0012975231577544268, 2.310159709002111e-05, ...], 'energy': -55.52108557170985, 'energy_history': [-55.51901898989887, -55.52056881448526, -55.52065046778772, -55.520690696813716, -55.520691108428, -55.520708448092634, ...], 'energy_variance': 3.066239097617371e-10, ...}\n" - ] - } - ], - "source": [ - "result = job.result()\n", - "\n", - "# Output can be long, so we display a shortened representation\n", - "shortened_result = reprlib.repr(result)\n", - "print(shortened_result)" - ] - }, - { - "cell_type": "markdown", - "id": "2b6fb05c", - "metadata": {}, - "source": [ - "To access the ground state energy, use the \"energy\" key. The \"eigenvector\" key provides the CI coefficients with corresponding bitstring notation of electron configuration stored with \"states\" of the results." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "28cd677c", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "|Exact Energy - HI-VQE Energy|: 0.06246299427914437 mHa\n", - "Sampled Number of States: 1936\n" - ] - } - ], - "source": [ - "fci_energy = -55.521148034704126 # the exact energy using FCI method\n", - "hivqe_energy = result[\"energy\"]\n", - "print(\n", - " f\"|Exact Energy - HI-VQE Energy|: \"\n", - " f\"{abs(fci_energy - hivqe_energy) * 1000} mHa\"\n", - ")\n", - "print(f\"Sampled Number of States: {len(result['states'])}\")" - ] - }, - { - "cell_type": "markdown", - "id": "4af252f6", - "metadata": {}, - "source": [ - "## Performance\n", - "\n", - "This section shows the demonstrated benchmark calculations of HI-VQE with a 24-qubit case for Li2S, a 40-qubit case for an N2 molecule, and a 44-qubit case for an FeP-NO system." - ] - }, - { - "cell_type": "markdown", - "id": "54d8f446", - "metadata": {}, - "source": [ - "#### Dissociation potential energy surface curve for an Li2S molecule with 24 qubits\n", - "\n", - "The PES curve is shown with the FCI reference and initial guess from RHF, together with the energy error from the FCI reference.\n", - "\n", - "![Image showing that HI-VQE produces solutions within chemical accuracy of a classical reference PES curve for the Li2S system](/docs/images/guides/qunova-chemistry/Li2S_PES.avif).\n", - "\n", - "The calculations have been conducted with the following geometries and options." - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "id": "294a02cfa0c3", - "metadata": { - "tags": [ - "remove-cell" - ] - }, - "outputs": [], - "source": [ - "# This cell is hidden from users\n", - "backend_name = service.least_busy(operational=True, min_num_qubits=38).name" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "id": "8c998f54", - "metadata": {}, - "outputs": [], - "source": [ - "# Define Li2S geometries\n", - "Li2S_geoms = {\n", - " \"Li2S_1.51\": \"S -1.239044 0.671232 -0.030374;Li -1.506327 0.432403 -1.498949;Li -0.899996 0.973348 1.826768;\",\n", - " \"Li2S_2.40\": \"S -1.741432 0.680397 0.346702;Li -0.529307 0.488006 -1.729343;Li -1.284307 0.989409 2.177209;\",\n", - " \"Li2S_3.80\": \"S -2.707255 0.674298 0.909161;Li 0.079218 0.552012 -1.671656;Li -0.927010 0.931502 1.557063;\",\n", - "}\n", - "\n", - "# Configure some options for the job.\n", - "molecule_options = {\n", - " \"basis\": \"sto3g\",\n", - "}\n", - "hivqe_options = {\n", - " \"shots\": 100,\n", - " \"max_iter\": 20,\n", - "}\n", - "\n", - "results = []\n", - "for geom in [\"Li2S_1.51\", \"Li2S_2.40\", \"Li2S_3.80\"]:\n", - " # Run HI-VQE\n", - " job = function.run(\n", - " geometry=Li2S_geoms[geom],\n", - " backend_name=backend_name, # can use any device with at least 38 qubits\n", - " max_states=2000,\n", - " max_expansion_states=10,\n", - " molecule_options=molecule_options,\n", - " hivqe_options=hivqe_options,\n", - " )\n", - " results.append(job.result())" - ] - }, - { - "cell_type": "markdown", - "id": "81129f0f", - "metadata": {}, - "source": [ - "The red dots represent the HI-VQE calculation results for six different geometries, and three geometries corresponding to 1.51, 2.40, and 3.80 Angstrom are provided as input in the above cell." - ] - }, - { - "cell_type": "markdown", - "id": "4d8d6cad", - "metadata": {}, - "source": [ - "#### Dissociation PES curve for an N2 molecule with 40 qubits\n", - "\n", - "The nitrogen molecule has been identified as a multireference system with large correlation energy contributions beyond the Hartree-Fock state. We conducted a benchmark calculation for the N2 molecule with cc-pvdz basis, (20o,14e) using the homo-lumo active orbital selection. The complete active space (CAS) number to represent this problem is 6,009,350,400. It is not possible to obtain the eigenvalue problem solution (for energy and electronic structure) with this number of states using a powerful desktop (16cpu/64GB). With HI-VQE, users can efficiently search the subspace of CAS states to find chemically accurate results while saving computation resources significantly. The following plots show the PES curve of 40 qubits HI-VQE calculation of the N2 molecule dissociation.\n", - "\n", - "![Image showing that HI-VQE produces solutions within chemical accuracy of a classical reference PES curve for the N2 system](/docs/images/guides/qunova-chemistry/N2_PES_40qubits.avif)" - ] - }, - { - "cell_type": "markdown", - "id": "e84bc625", - "metadata": {}, - "source": [ - "#### Dissociation PES curve for five-coordinated iron(II)-porphyrin with an NO system with 44 qubits\n", - "\n", - "Another interesting chemical system is an iron(II)-porphyrin (FeP) complex with a coordinated nitric oxide (NO) ligand, which represents a biologically relevant metalloporphyrin system that plays crucial roles in various physiological processes. In this example, HI-VQE has been utilized to estimate the accurate potential energy surface curve of the intermolecular interaction between FeP and NO (ground state energy for differently separated geometries). The combined system has 450 orbitals and 202 electrons (450o,202e) with 6-31g(d) basis in total. The homo-lumo active orbital selection was utilized to calculate the smaller case from the real case with (22o,22e). From the following benchmark results, we were able to achieve the chemical accuracy (> 1.6 mHa) with a state-of-the-art classical computer chemistry calculation of CASCI(DMRG) (22o,22e) reference.\n", - "\n", - "![Image showing that HI-VQE produces solutions within chemical accuracy of a classical reference PES curve for the FeP-NO system](/docs/images/guides/qunova-chemistry/fepno_44qubits.avif)" - ] - }, { "cell_type": "markdown", "id": "b34fe075", diff --git a/docs/functions/qunova-chemistry/performance-tuning.ipynb b/docs/functions/qunova-chemistry/performance-tuning.ipynb new file mode 100644 index 000000000000..473161c38421 --- /dev/null +++ b/docs/functions/qunova-chemistry/performance-tuning.ipynb @@ -0,0 +1,141 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "page-frontmatter", + "metadata": {}, + "source": [ + "---\ntitle: Advanced techniques with HI-VQE Chemistry\ndescription: Dissociation PES curves and performance benchmarks across molecular systems.\n---" + ] + }, + { + "cell_type": "markdown", + "id": "4af252f6", + "metadata": {}, + "source": [ + "## Performance\n", + "\n", + "This section shows the demonstrated benchmark calculations of HI-VQE with a 24-qubit case for Li2S, a 40-qubit case for an N2 molecule, and a 44-qubit case for an FeP-NO system." + ] + }, + { + "cell_type": "markdown", + "id": "54d8f446", + "metadata": {}, + "source": [ + "#### Dissociation potential energy surface curve for an Li2S molecule with 24 qubits\n", + "\n", + "The PES curve is shown with the FCI reference and initial guess from RHF, together with the energy error from the FCI reference.\n", + "\n", + "![Image showing that HI-VQE produces solutions within chemical accuracy of a classical reference PES curve for the Li2S system](/docs/images/guides/qunova-chemistry/Li2S_PES.avif).\n", + "\n", + "The calculations have been conducted with the following geometries and options." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "294a02cfa0c3", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# This cell is hidden from users\n", + "backend_name = service.least_busy(operational=True, min_num_qubits=38).name" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "8c998f54", + "metadata": {}, + "outputs": [], + "source": [ + "# Define Li2S geometries\n", + "Li2S_geoms = {\n", + " \"Li2S_1.51\": \"S -1.239044 0.671232 -0.030374;Li -1.506327 0.432403 -1.498949;Li -0.899996 0.973348 1.826768;\",\n", + " \"Li2S_2.40\": \"S -1.741432 0.680397 0.346702;Li -0.529307 0.488006 -1.729343;Li -1.284307 0.989409 2.177209;\",\n", + " \"Li2S_3.80\": \"S -2.707255 0.674298 0.909161;Li 0.079218 0.552012 -1.671656;Li -0.927010 0.931502 1.557063;\",\n", + "}\n", + "\n", + "# Configure some options for the job.\n", + "molecule_options = {\n", + " \"basis\": \"sto3g\",\n", + "}\n", + "hivqe_options = {\n", + " \"shots\": 100,\n", + " \"max_iter\": 20,\n", + "}\n", + "\n", + "results = []\n", + "for geom in [\"Li2S_1.51\", \"Li2S_2.40\", \"Li2S_3.80\"]:\n", + " # Run HI-VQE\n", + " job = function.run(\n", + " geometry=Li2S_geoms[geom],\n", + " backend_name=backend_name, # can use any device with at least 38 qubits\n", + " max_states=2000,\n", + " max_expansion_states=10,\n", + " molecule_options=molecule_options,\n", + " hivqe_options=hivqe_options,\n", + " )\n", + " results.append(job.result())" + ] + }, + { + "cell_type": "markdown", + "id": "81129f0f", + "metadata": {}, + "source": [ + "The red dots represent the HI-VQE calculation results for six different geometries, and three geometries corresponding to 1.51, 2.40, and 3.80 Angstrom are provided as input in the above cell." + ] + }, + { + "cell_type": "markdown", + "id": "4d8d6cad", + "metadata": {}, + "source": [ + "#### Dissociation PES curve for an N2 molecule with 40 qubits\n", + "\n", + "The nitrogen molecule has been identified as a multireference system with large correlation energy contributions beyond the Hartree-Fock state. We conducted a benchmark calculation for the N2 molecule with cc-pvdz basis, (20o,14e) using the homo-lumo active orbital selection. The complete active space (CAS) number to represent this problem is 6,009,350,400. It is not possible to obtain the eigenvalue problem solution (for energy and electronic structure) with this number of states using a powerful desktop (16cpu/64GB). With HI-VQE, users can efficiently search the subspace of CAS states to find chemically accurate results while saving computation resources significantly. The following plots show the PES curve of 40 qubits HI-VQE calculation of the N2 molecule dissociation.\n", + "\n", + "![Image showing that HI-VQE produces solutions within chemical accuracy of a classical reference PES curve for the N2 system](/docs/images/guides/qunova-chemistry/N2_PES_40qubits.avif)" + ] + }, + { + "cell_type": "markdown", + "id": "e84bc625", + "metadata": {}, + "source": [ + "#### Dissociation PES curve for five-coordinated iron(II)-porphyrin with an NO system with 44 qubits\n", + "\n", + "Another interesting chemical system is an iron(II)-porphyrin (FeP) complex with a coordinated nitric oxide (NO) ligand, which represents a biologically relevant metalloporphyrin system that plays crucial roles in various physiological processes. In this example, HI-VQE has been utilized to estimate the accurate potential energy surface curve of the intermolecular interaction between FeP and NO (ground state energy for differently separated geometries). The combined system has 450 orbitals and 202 electrons (450o,202e) with 6-31g(d) basis in total. The homo-lumo active orbital selection was utilized to calculate the smaller case from the real case with (22o,22e). From the following benchmark results, we were able to achieve the chemical accuracy (> 1.6 mHa) with a state-of-the-art classical computer chemistry calculation of CASCI(DMRG) (22o,22e) reference.\n", + "\n", + "![Image showing that HI-VQE produces solutions within chemical accuracy of a classical reference PES curve for the FeP-NO system](/docs/images/guides/qunova-chemistry/fepno_44qubits.avif)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index b79d5da156be..6261591fb906 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -719,31 +719,6 @@ "url": "/docs/guides/execution-modes-faq" } ] - }, - { - "title": "Qiskit Serverless", - "children": [ - { - "title": "Introduction to Qiskit Serverless", - "url": "/docs/guides/serverless" - }, - { - "title": "Write your first Qiskit Serverless program", - "url": "/docs/guides/serverless-first-program" - }, - { - "title": "Run your first Qiskit Serverless workload remotely", - "url": "/docs/guides/serverless-run-first-workload" - }, - { - "title": "Manage Qiskit Serverless compute and data resources", - "url": "/docs/guides/serverless-manage-resources" - }, - { - "title": "Port code to Qiskit Serverless", - "url": "/docs/guides/serverless-port-code" - } - ] } ], "collapsible": false @@ -756,48 +731,31 @@ "url": "/docs/guides/functions" }, { - "title": "Circuit functions", - "children": [ - { - "title": "Algorithmiq Tensor-network error mitigation", - "url": "/docs/guides/algorithmiq-tem" - }, - { - "title": "Q-CTRL Performance Management", - "url": "/docs/guides/q-ctrl-performance-management" - }, - { - "title": "Qedma QESEM", - "url": "/docs/guides/qedma-qesem" - } - ] + "title": "Getting Started with Qiskit Functions", + "url": "/docs/guides/functions/get-started" }, { - "title": "Application functions", + "title": "Custom Functions", "children": [ { - "title": "Kipu Quantum Iskay Quantum Optimizer", - "url": "/docs/guides/kipu-optimization" - }, - { - "title": "Multiverse Computing Singularity", - "url": "/docs/guides/multiverse-computing-singularity" + "title": "Introduction to custom functions", + "url": "/docs/guides/serverless" }, { - "title": "Q-CTRL Optimization Solver", - "url": "/docs/guides/q-ctrl-optimization-solver" + "title": "Write your first custom function", + "url": "/docs/guides/serverless-first-program" }, { - "title": "Quantum Portfolio Optimizer: A Qiskit Function by Global Data Quantum", - "url": "/docs/guides/global-data-quantum-optimizer" + "title": "Run your first custom function remotely", + "url": "/docs/guides/serverless-run-first-workload" }, { - "title": "QUICK-PDE: A Qiskit Function by ColibriTD", - "url": "/docs/guides/colibritd-pde" + "title": "Manage custom function compute and data resources", + "url": "/docs/guides/serverless-manage-resources" }, { - "title": "Qunova Computing HI-VQE Chemistry", - "url": "/docs/guides/qunova-chemistry" + "title": "Port code to custom functions", + "url": "/docs/guides/serverless-port-code" } ] }, @@ -806,15 +764,15 @@ "children": [ { "title": "Introduction to Qiskit Function templates", - "url": "/docs/guides/qiskit-function-templates" + "url": "/docs/functions/function-templates/qiskit-function-templates" }, { "title": "Template for chemistry simulation", - "url": "/docs/guides/function-template-chemistry-workflow" + "url": "/docs/functions/function-templates/function-template-chemistry-workflow" }, { "title": "Template for Hamiltonian simulation", - "url": "/docs/guides/function-template-hamiltonian-simulation" + "url": "/docs/functions/function-templates/function-template-hamiltonian-simulation" } ] }, diff --git a/docs/functions/get-started.ipynb b/docs/guides/functions/get-started.ipynb similarity index 64% rename from docs/functions/get-started.ipynb rename to docs/guides/functions/get-started.ipynb index 26043c4c1f00..d4fbe38db6d8 100644 --- a/docs/functions/get-started.ipynb +++ b/docs/guides/functions/get-started.ipynb @@ -1,52 +1,27 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "functions-gs-frontmatter", + "metadata": {}, + "source": [ + "---\ntitle: Getting Started with Qiskit Functions\ndescription: Install the Qiskit Functions Catalog client, authenticate, and learn the common workflow patterns across all vendor functions — loading, running, status checks, result retrieval, and error handling.\n---" + ] + }, + { + "cell_type": "markdown", + "id": "using-functions-intro", + "metadata": {}, + "source": [ + "# Getting Started with Qiskit Functions\n\nThe Qiskit Functions Catalog client provides a unified interface for running all functions in the catalog. This page covers installing the client, authenticating, and the core workflow patterns common to all circuit and application functions: loading a function, submitting a job, checking its status, retrieving results, and handling errors." + ] + }, { "cell_type": "markdown", "id": "88919905", "metadata": {}, "source": [ - "\n", - "## Get started with Qiskit Functions\n", - "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.\n", - "\n", - "### Request a free trial for third-party Qiskit Functions\n", - "\n", - "To request a new free trial, navigate to the [Qiskit Functions Catalog](https://quantum.cloud.ibm.com/functions), and explore the details panel. Click on `Request a free trial` and fill out information required by the Functions partner, including the IBM Cloud `AccessGroupId`:\n", - "\n", - "1. Navigate to [IBM Cloud IAM](http://cloud.ibm.com/iam/groups).\n", - "2. Verify eligibility.\n", - " - Switch your account in the top bar to one with the following format: `XXXXXXX - [Organization Name]`\n", - " - Ensure the organization is the same as the one associated with your Premium account.\n", - " - If you see \"[Your Name]'s Account\", you are using your _personal_ account, which is not eligible for premium access.\n", - "3. Find your access group ID.\n", - " - Click a group name.\n", - " - Click **Details**.\n", - " - Copy the access group ID. It should start with `AccessGroup-`.\n", - "\n", - "### Install Qiskit Functions Catalog client\n", - "\n", - "1. To start using Qiskit Functions, install the IBM Qiskit Functions Catalog client:\n", - "\n", - " ```\n", - " pip install qiskit-ibm-catalog\n", - " ```\n", - "1. Retrieve your API key from the [IBM Quantum Platform dashboard](https://quantum.cloud.ibm.com/), and activate your Python virtual environment. See the [installation instructions](/docs/guides/install-qiskit#local) if you do not already have a virtual environment set up.\n", - "\n", - " **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](#functions-untrusted) if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Quantum Platform.)\n", - "\n", - " To use `save_account()`, run `python` in your shell, then enter the following:\n", - "\n", - " ```python\n", - " from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", - "\n", - " QiskitFunctionsCatalog.save_account(channel=\"ibm_quantum_platform\", token=\"\", instance=\"\")\n", - " ```\n", - "\n", - " Type `exit()`. From now on, whenever you need to authenticate to the service, you can load your credentials with\n", - " ```python\n", - " from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", - " catalog = QiskitFunctionsCatalog()\n", - " ```" + "## Install Qiskit Functions Catalog client\n\n1. To start using Qiskit Functions, install the IBM Qiskit Functions Catalog client:\n\n ```\n pip install qiskit-ibm-catalog\n ```\n1. Retrieve your API key from the [IBM Quantum Platform dashboard](https://quantum.cloud.ibm.com/), and activate your Python virtual environment. See the [installation instructions](/docs/guides/install-qiskit#local) if you do not already have a virtual environment set up.\n\n **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](#functions-untrusted) if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Quantum Platform.)\n\n To use `save_account()`, run `python` in your shell, then enter the following:\n\n ```python\n from qiskit_ibm_catalog import QiskitFunctionsCatalog\n\n QiskitFunctionsCatalog.save_account(channel=\"ibm_quantum_platform\", token=\"\", instance=\"\")\n ```\n\n Type `exit()`. From now on, whenever you need to authenticate to the service, you can load your credentials with\n ```python\n from qiskit_ibm_catalog import QiskitFunctionsCatalog\n catalog = QiskitFunctionsCatalog()\n ```" ] }, { @@ -136,9 +111,7 @@ "id": "885ae29d", "metadata": {}, "source": [ - "### Run enabled functions\n", - "\n", - "After a catalog object has been instantiated, you can select a function using `catalog.load(provider/function-name)`:" + "## Run a function\n\nAfter a catalog object has been instantiated, you can select a function using `catalog.load(provider/function-name)`:" ] }, { @@ -210,25 +183,7 @@ "id": "f238416c", "metadata": {}, "source": [ - "### Check job status\n", - "\n", - "\n", - "Currently, the IBM Quantum workloads table only reflects Qiskit Runtime workloads. Use `job.status()` to see your Qiskit Function workload's current status.\n", - "\n", - "\n", - "With your Qiskit Function `job_id`, you can check the status of running jobs. This includes the following statuses:\n", - "\n", - "- **`QUEUED`**: The remote program is in the Qiskit Function queue. The queue priority is based on how much you've used Qiskit Functions.\n", - "- **`INITIALIZING`**: The remote program is starting; this includes setting up the remote environment and installing dependencies.\n", - "- **`RUNNING`**: The program is running. This also includes several more detailed statuses if supported by specific functions\n", - " - **`RUNNING: MAPPING`**\": The function is currently mapping your classical inputs to quantum inputs\n", - " - **`RUNNING: OPTIMIZING_FOR_HARDWARE`**\": The function is optimizing for the selected QPU. This could include circuit transpilation, QPU characterization, observable backpropagation, and so forth\n", - " - **`RUNNING: WAITING_FOR_QPU`**: The function has submitted a job to Qiskit Runtime, and is waiting in the queue\n", - " - **`RUNNING: EXECUTING_QPU`**: The function has an active Qiskit Runtime job\n", - " - **`RUNNING: POST_PROCESSING`**: The function is post-processing results. This could include error mitigation, mapping quantum results to classical, and so forth\n", - "- **`DONE`**: The program is complete, and you can retrieve result data with `job.results()`.\n", - "- **`ERROR`**: The program stopped running because of a problem. Use `job.result()` to get the error message.\n", - "- **`CANCELED`**: The program was canceled; either by a user, the service, or the server." + "## Check job status\n\n\nCurrently, the IBM Quantum workloads table only reflects Qiskit Runtime workloads. Use `job.status()` to see your Qiskit Function workload's current status.\n\n\nWith your Qiskit Function `job_id`, you can check the status of running jobs. This includes the following statuses:\n\n- **`QUEUED`**: The remote program is in the Qiskit Function queue. The queue priority is based on how much you've used Qiskit Functions.\n- **`INITIALIZING`**: The remote program is starting; this includes setting up the remote environment and installing dependencies.\n- **`RUNNING`**: The program is running. This also includes several more detailed statuses if supported by specific functions\n - **`RUNNING: MAPPING`**\": The function is currently mapping your classical inputs to quantum inputs\n - **`RUNNING: OPTIMIZING_FOR_HARDWARE`**\": The function is optimizing for the selected QPU. This could include circuit transpilation, QPU characterization, observable backpropagation, and so forth\n - **`RUNNING: WAITING_FOR_QPU`**: The function has submitted a job to Qiskit Runtime, and is waiting in the queue\n - **`RUNNING: EXECUTING_QPU`**: The function has an active Qiskit Runtime job\n - **`RUNNING: POST_PROCESSING`**: The function is post-processing results. This could include error mitigation, mapping quantum results to classical, and so forth\n- **`DONE`**: The program is complete, and you can retrieve result data with `job.results()`.\n- **`ERROR`**: The program stopped running because of a problem. Use `job.result()` to get the error message.\n- **`CANCELED`**: The program was canceled; either by a user, the service, or the server." ] }, { @@ -256,9 +211,7 @@ "id": "0c246c35", "metadata": {}, "source": [ - "### Retrieve results\n", - "\n", - "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:" + "## Retrieve results\n\nAfter 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:" ] }, { @@ -313,9 +266,7 @@ "id": "2fab74e8", "metadata": {}, "source": [ - "### List previously run jobs run with Qiskit Functions\n", - "\n", - "You can use `jobs()` to list all jobs submitted to Qiskit Functions:" + "## List previous jobs\n\nYou can use `jobs()` to list all jobs submitted to Qiskit Functions:" ] }, { @@ -389,9 +340,7 @@ "id": "b7d666a2", "metadata": {}, "source": [ - "### Fetch error messages\n", - "\n", - "If a program status is `ERROR`, use `job.error_message()` to fetch the error message as follows:" + "## Fetch error messages\n\nIf a program status is `ERROR`, use `job.error_message()` to fetch the error message as follows:" ] }, { @@ -420,4 +369,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file diff --git a/docs/guides/functions/index.mdx b/docs/guides/functions/index.mdx new file mode 100644 index 000000000000..e836ca277152 --- /dev/null +++ b/docs/guides/functions/index.mdx @@ -0,0 +1,131 @@ +--- +title: Introduction to Qiskit Functions +description: Explore IBM Qiskit Functions Catalog, abstracted circuit function and application function services designed to accelerate research and application prototyping. +--- + +{/* cspell:ignore Jarman, HIVQE, Cadavid, Chandarana, Leclerc, Sachdeva, HUBO, Filippov, Downfolding, Aharonov, Mundada, Yamauchi, supersymmetric, Paterakis, Gharibyan, Jaffali, Pellow */} + +# Introduction to Qiskit Functions + +* Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change. + + +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. + +| Type | What it does | Inputs → Outputs | Who it's for | +|---|---|---|---| +| **Circuit function** | Simplified interface for running circuits. Abstracts transpilation, error suppression, and error mitigation. | PUB objects → mitigated expectation values | Researchers discovering algorithms without focusing on hardware optimization | +| **Application function** | Higher-level abstraction for domain-specific tasks. Abstracts the full quantum workflow. | Molecules, graphs, optimization problems → classical results | Domain researchers integrating quantum into large-scale classical workflows | +| **Custom function** | Create and deploy your own quantum-classical workloads as a managed service on IBM Quantum. | Custom code and data → custom outputs | Researchers running high-scale experiments with intensive classical compute alongside quantum workloads | + +![Overview of Qiskit Functions](/docs/images/guides/functions/functions-overview.svg) + +## Circuit functions + + + + + + + + + +## Application functions + + + + + + + + + + + + + + + +## Custom functions + + + + + +## Access Qiskit Functions + +Premium, Flex, and On-Prem (through the IBM Quantum Platform API) Plan users can create Custom Functions, 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 new free trial, navigate to the [Qiskit Functions Catalog](https://quantum.cloud.ibm.com/functions), and explore the details panel. Click on `Request a free trial` and fill out information required by the Functions partner, including the IBM Cloud `AccessGroupId`: + +1. Navigate to [IBM Cloud IAM](http://cloud.ibm.com/iam/groups). +2. Verify eligibility. + - Switch your account in the top bar 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-`. diff --git a/docs/guides/serverless-first-program.ipynb b/docs/guides/serverless-first-program.ipynb index ec1e9ed51960..6b20638b1d72 100644 --- a/docs/guides/serverless-first-program.ipynb +++ b/docs/guides/serverless-first-program.ipynb @@ -6,13 +6,13 @@ "metadata": {}, "source": [ "---\n", - "title: Write your first Qiskit Serverless program\n", + "title: Write your first Custom Functions program\n", "description: How to create a parallel transpilation program and deploy it to IBM Quantum Platform to use as a reusable remote service.\n", "---\n", "\n", "{/* cspell:ignore mypath */}\n", "\n", - "# Write your first Qiskit Serverless program" + "# Write your first Custom Functions program" ] }, { @@ -54,7 +54,7 @@ "metadata": {}, "source": [ "\n", - " **Qiskit Serverless is getting an upgrade, and its features are changing fast.** During this development phase, find release notes and the most recent documentation at the [Qiskit Serverless GitHub](https://qiskit.github.io/qiskit-serverless/index.html) page.\n", + " **Custom Functions is getting an upgrade, and its features are changing fast.** During this development phase, find release notes and the most recent documentation at the [Custom Functions GitHub](https://qiskit.github.io/qiskit-serverless/index.html) page.\n", "\n", "\n", "This example demonstrates how to use `qiskit-serverless` tools to create a parallel transpilation program, and then implement `qiskit-ibm-catalog` to upload your program to IBM Quantum Platform to use as a reusable remote service.\n", @@ -62,11 +62,11 @@ "## Workflow overview\n", "\n", "1. Create a local directory and empty program file (`./source_files/transpile_remote.py`)\n", - "1. Add code to your program that, when uploaded to Qiskit Serverless, will transpile a circuit\n", - "1. Use `qiskit-ibm-catalog` to authenticate to Qiskit Serverless\n", - "1. Upload the program to Qiskit Serverless\n", + "1. Add code to your program that, when uploaded to Custom Functions, will transpile a circuit\n", + "1. Use `qiskit-ibm-catalog` to authenticate to Custom Functions\n", + "1. Upload the program to Custom Functions\n", "\n", - "After uploading your program , you can run it to transpile the circuit by following the [Run your first Qiskit Serverless workload remotely](/docs/guides/serverless-run-first-workload) guide." + "After uploading your program , you can run it to transpile the circuit by following the [Run your first Custom Functions workload remotely](/docs/guides/serverless-run-first-workload) guide." ] }, { @@ -74,12 +74,12 @@ "id": "cad16f43-8548-4849-a4b8-09059a8b747c", "metadata": {}, "source": [ - "## Example: Remote transpilation with Qiskit Serverless\n", + "## Example: Remote transpilation with Custom Functions\n", "\n", - "This example walks you through creating and adding to a program file that, when you upload it to Qiskit Serverless, will transpile a `circuit` against a given `backend` and target `optimization_level`.\n", + "This example walks you through creating and adding to a program file that, when you upload it to Custom Functions, will transpile a `circuit` against a given `backend` and target `optimization_level`.\n", "\n", "\n", - "Qiskit Serverless requires setting up your workload’s `.py` files into a dedicated directory. The following structure is an example of good practice:\n", + "Custom Functions requires setting up your workload’s `.py` files into a dedicated directory. The following structure is an example of good practice:\n", "\n", "```text\n", "serverless_program\n", @@ -94,7 +94,7 @@ "\n", "### Create the directory and an empty program file\n", "\n", - "First, create a directory named `source_files`, then create a program file in the directory, so that its path is `./source_files/transpile_remote.py`. This is the file you will upload to Qiskit Serverless." + "First, create a directory named `source_files`, then create a program file in the directory, so that its path is `./source_files/transpile_remote.py`. This is the file you will upload to Custom Functions." ] }, { @@ -252,7 +252,7 @@ "metadata": {}, "source": [ "\n", - "### Authenticate to Qiskit Serverless\n", + "### Authenticate to Custom Functions\n", "\n", "Use `qiskit-ibm-catalog` to authenticate to `QiskitServerless` with your API key (you can use your `QiskitRuntimeService` API key, or create a new API key on the [IBM Quantum Platform dashboard](https://quantum.cloud.ibm.com))." ] @@ -277,7 +277,7 @@ "source": [ "### Run code to upload\n", "\n", - "Run the following code to upload the program. Qiskit Serverless compresses the contents of `working_dir` (in this case, `source_files`) into a `tar`, which is uploaded and then cleaned up. The `entrypoint` identifies the main program executable for Qiskit Serverless to run." + "Run the following code to upload the program. Custom Functions compresses the contents of `working_dir` (in this case, `source_files`) into a `tar`, which is uploaded and then cleaned up. The `entrypoint` identifies the main program executable for Custom Functions to run." ] }, { @@ -410,7 +410,7 @@ "\n", "\n", "\n", - "- Learn how to pass inputs and run your program remotely in the [Run your first Qiskit Serverless workload remotely](/docs/guides/serverless-run-first-workload) topic.\n", + "- Learn how to pass inputs and run your program remotely in the [Run your first Custom Functions workload remotely](/docs/guides/serverless-run-first-workload) topic.\n", "\n", "" ] diff --git a/docs/guides/serverless-manage-resources.ipynb b/docs/guides/serverless-manage-resources.ipynb index 7d2db9ecd240..214c5917fc83 100644 --- a/docs/guides/serverless-manage-resources.ipynb +++ b/docs/guides/serverless-manage-resources.ipynb @@ -6,12 +6,12 @@ "metadata": {}, "source": [ "---\n", - "title: Manage Qiskit Serverless compute and data resources\n", - "description: Manage compute and data across your Qiskit pattern with Qiskit Serverless.\n", + "title: Manage Custom Functions compute and data resources\n", + "description: Manage compute and data across your Qiskit pattern with Custom Functions.\n", "---\n", "\n", "\n", - "# Manage Qiskit Serverless compute and data resources" + "# Manage Custom Functions compute and data resources" ] }, { @@ -44,10 +44,10 @@ "metadata": {}, "source": [ "\n", - " **Qiskit Serverless is getting an upgrade, and its features are changing fast.** During this development phase, find release notes and the most recent documentation at the [Qiskit Serverless GitHub](https://qiskit.github.io/qiskit-serverless/index.html) page.\n", + " **Custom Functions is getting an upgrade, and its features are changing fast.** During this development phase, find release notes and the most recent documentation at the [Custom Functions GitHub](https://qiskit.github.io/qiskit-serverless/index.html) page.\n", "\n", "\n", - "With Qiskit Serverless, you can manage compute and data across your [Qiskit pattern](/docs/guides/intro-to-patterns), including CPUs, QPUs, and other compute accelerators." + "With Custom Functions, you can manage compute and data across your [Qiskit pattern](/docs/guides/intro-to-patterns), including CPUs, QPUs, and other compute accelerators." ] }, { @@ -146,7 +146,7 @@ "source": [ "## Parallel workflows\n", "\n", - "For classical tasks that can be parallelized, use the `@distribute_task` decorator to define compute requirements needed to perform a task. Start by recalling the `transpile_remote.py` example from the [Write your first Qiskit Serverless program](/docs/guides/serverless-first-program) topic with the following code.\n", + "For classical tasks that can be parallelized, use the `@distribute_task` decorator to define compute requirements needed to perform a task. Start by recalling the `transpile_remote.py` example from the [Write your first Custom Functions program](/docs/guides/serverless-first-program) topic with the following code.\n", "\n", "The following code requires that you have already [saved your credentials](/docs/guides/cloud-setup)." ] @@ -419,7 +419,7 @@ "source": [ "### Explore different task configurations\n", "\n", - "You can flexibly allocate CPU, GPU, and memory for your tasks via `@distribute_task()`. For Qiskit Serverless on IBM Quantum® Platform, each program is equipped with 16 CPU cores and 32 GB RAM, which can be allocated dynamically as needed.\n", + "You can flexibly allocate CPU, GPU, and memory for your tasks via `@distribute_task()`. For Custom Functions on IBM Quantum® Platform, each program is equipped with 16 CPU cores and 32 GB RAM, which can be allocated dynamically as needed.\n", "\n", "CPU cores can be allocated as full CPU cores, or even fractional allocations, as shown in the following.\n", "\n", @@ -557,12 +557,12 @@ "source": [ "## Manage data across your program\n", "\n", - "Qiskit Serverless allows you to manage files in the `/data` directory across all your programs. This includes several limitations:\n", + "Custom Functions allows you to manage files in the `/data` directory across all your programs. This includes several limitations:\n", "\n", "- Only `tar` and `h5` files are supported today\n", "- This is only a flat `/data` storage, and cannot have `/data/folder/` subdirectories\n", "\n", - "The following shows how to upload files. Be sure you have authenticated to Qiskit Serverless with your IBM Quantum account (see [Upload to Qiskit Serverless](/docs/guides/serverless-first-program#upload-to-qiskit-serverless) for instructions)." + "The following shows how to upload files. Be sure you have authenticated to Custom Functions with your IBM Quantum account (see [Upload to Custom Functions](/docs/guides/serverless-first-program#upload-to-qiskit-serverless) for instructions)." ] }, { @@ -685,8 +685,8 @@ "\n", "\n", "\n", - "- See a full example that [ports existing code to Qiskit Serverless](/docs/guides/serverless-port-code).\n", - "- Read a paper in which researchers used Qiskit Serverless and quantum-centric supercomputing to [explore quantum chemistry](https://arxiv.org/abs/2405.05068v1).\n", + "- See a full example that [ports existing code to Custom Functions](/docs/guides/serverless-port-code).\n", + "- Read a paper in which researchers used Custom Functions and quantum-centric supercomputing to [explore quantum chemistry](https://arxiv.org/abs/2405.05068v1).\n", "\n", "" ] diff --git a/docs/guides/serverless-port-code.ipynb b/docs/guides/serverless-port-code.ipynb index 38ee69890b53..fff24b41dd20 100644 --- a/docs/guides/serverless-port-code.ipynb +++ b/docs/guides/serverless-port-code.ipynb @@ -6,12 +6,12 @@ "metadata": {}, "source": [ "---\n", - "title: Port code to Qiskit Serverless\n", - "description: How to port existing code to leverage Qiskit Serverless\n", + "title: Port code to Custom Functions\n", + "description: How to port existing code to leverage Custom Functions\n", "---\n", "\n", "\n", - "# Port code to Qiskit Serverless" + "# Port code to Custom Functions" ] }, { @@ -30,10 +30,10 @@ "metadata": {}, "source": [ "\n", - " **Qiskit Serverless is getting an upgrade, and its features are changing fast.** During this development phase, find release notes and the most recent documentation at the [Qiskit Serverless GitHub](https://qiskit.github.io/qiskit-serverless/index.html) page.\n", + " **Custom Functions is getting an upgrade, and its features are changing fast.** During this development phase, find release notes and the most recent documentation at the [Custom Functions GitHub](https://qiskit.github.io/qiskit-serverless/index.html) page.\n", "\n", "\n", - "The following example demonstrates how to port existing code to leverage Qiskit Serverless.\n", + "The following example demonstrates how to port existing code to leverage Custom Functions.\n", "\n", "The following code assumes that you have saved your credentials. If you have not, follow the instructions in [Set up your IBM Cloud account](/docs/guides/cloud-setup-untrusted) to authenticate with your API key.\n", "\n", @@ -129,7 +129,7 @@ " \n", "\n", "\n", - "## Upload to Qiskit Serverless\n", + "## Upload to Custom Functions\n", "\n", "Follow the instructions on the [Introduction to Qiskit Functions](/docs/guides/functions) page to authenticate with your API key.\n", "\n", @@ -153,7 +153,7 @@ "'transpile_remote_serverless'\n", "```\n", "\n", - "## Remotely run in Qiskit Serverless\n", + "## Remotely run in Custom Functions\n", "\n", "```python\n", "from qiskit.circuit.random import random_circuit\n", @@ -183,7 +183,7 @@ "\n", "\n", "\n", - "- Read a paper in which researchers used Qiskit Serverless and quantum-centric supercomputing to [explore quantum chemistry](https://arxiv.org/abs/2405.05068v1).\n", + "- Read a paper in which researchers used Custom Functions and quantum-centric supercomputing to [explore quantum chemistry](https://arxiv.org/abs/2405.05068v1).\n", "\n", "" ] diff --git a/docs/guides/serverless-run-first-workload.ipynb b/docs/guides/serverless-run-first-workload.ipynb index b800839a0eee..2315229ddaab 100644 --- a/docs/guides/serverless-run-first-workload.ipynb +++ b/docs/guides/serverless-run-first-workload.ipynb @@ -6,12 +6,12 @@ "metadata": {}, "source": [ "---\n", - "title: Run your first Qiskit Serverless workload remotely\n", + "title: Run your first Custom Functions workload remotely\n", "description: How to list programs available in Serverless, pass inputs into these programs, run them remotely, check status, and retrieve results and logs.\n", "---\n", "\n", "\n", - "# Run your first Qiskit Serverless workload remotely" + "# Run your first Custom Functions workload remotely" ] }, { @@ -44,12 +44,12 @@ "metadata": {}, "source": [ "\n", - " **Qiskit Serverless is getting an upgrade, and its features are changing fast.** During this development phase, find release notes and the most recent documentation at the [Qiskit Serverless GitHub](https://qiskit.github.io/qiskit-serverless/index.html) page.\n", + " **Custom Functions is getting an upgrade, and its features are changing fast.** During this development phase, find release notes and the most recent documentation at the [Custom Functions GitHub](https://qiskit.github.io/qiskit-serverless/index.html) page.\n", "\n", "\n", - "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.\n", + "This section explores how to use `qiskit-ibm-catalog` to list programs available in Custom Functions, pass inputs into these programs, run them remotely, check their status, and retrieve results and logs.\n", "\n", - "Be sure you have followed the workflow in [Write your first Qiskit Serverless program](/docs/guides/serverless-first-program) before you begin." + "Be sure you have followed the workflow in [Write your first Custom Functions program](/docs/guides/serverless-first-program) before you begin." ] }, { @@ -59,7 +59,7 @@ "source": [ "## List programs available\n", "\n", - "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`](/docs/guides/serverless-first-program)." + "You can use `QiskitServerless.list()` to fetch a list of the available programs to run with Custom Functions. This includes the previously uploaded [`transpile_remote_serverless`](/docs/guides/serverless-first-program)." ] }, { @@ -233,14 +233,14 @@ "\n", "## Check job status\n", "\n", - "With your Qiskit Serverless `job_id`, you can check the status of running jobs. This includes the following statuses:\n", + "With your Custom Functions `job_id`, you can check the status of running jobs. This includes the following statuses:\n", "\n", - "- **`QUEUED`**: The remote program is in the Qiskit Serverless queue. The queue priority is currently based on how much you've used Qiskit Serverless\n", + "- **`QUEUED`**: The remote program is in the Custom Functions queue. The queue priority is currently based on how much you've used Custom Functions\n", "- **`INITIALIZING`**: The remote program is starting; this includes setting up the remote environment and installing dependencies\n", "- **`RUNNING`**: The program is running. At this stage, if you have `print()` outputs in your program, you can retrieve logs using `job.logs()`\n", "- **`DONE`**: The program is complete, and you can retrieve data stored in `save_result()` with `job.results()`\n", "\n", - "You can also set more detailed job statuses in [Manage Qiskit Serverless compute and data resources](/docs/guides/serverless-manage-resources)." + "You can also set more detailed job statuses in [Manage Custom Functions compute and data resources](/docs/guides/serverless-manage-resources)." ] }, { @@ -285,10 +285,10 @@ "metadata": {}, "source": [ "\n", - "Currently, the IBM Quantum workloads table only reflects Qiskit Runtime workloads. Use `job.status()` to see your Qiskit Serverless workload's current status.\n", + "Currently, the IBM Quantum workloads table only reflects Qiskit Runtime workloads. Use `job.status()` to see your Custom Functions workload's current status.\n", "\n", "\n", - "You've successfully run your first Qiskit Serverless program!" + "You've successfully run your first Custom Functions program!" ] }, { @@ -396,9 +396,9 @@ "id": "ca9791df-60c2-49d8-8541-741078ea63c6", "metadata": {}, "source": [ - "## List jobs previously run with Qiskit Serverless\n", + "## List jobs previously run with Custom Functions\n", "\n", - "You can use `jobs()` to list all jobs submitted to Qiskit Serverless:" + "You can use `jobs()` to list all jobs submitted to Custom Functions:" ] }, { diff --git a/docs/guides/serverless.mdx b/docs/guides/serverless.mdx index f674afd47ae3..10240e230ac3 100644 --- a/docs/guides/serverless.mdx +++ b/docs/guides/serverless.mdx @@ -1,25 +1,25 @@ --- -title: Introduction to Qiskit Serverless -description: Use Qiskit Serverless to run quantum-classical workloads across the cloud and on quantum-centric supercomputers. +title: Introduction to Custom Functions +description: Use Custom Functions to run quantum-classical workloads across the cloud and on quantum-centric supercomputers. --- -# Introduction to Qiskit Serverless +# Introduction to Custom Functions -Qiskit Serverless provides a simple interface to run workloads across quantum-classical resources. This includes deploying programs to the IBM Quantum® Platform and running workloads remotely, as well as easy resource management for multi-cloud and quantum-centric supercomputing use cases. +Custom Functions provides a simple interface to run workloads across quantum-classical resources. This includes deploying programs to the IBM Quantum® Platform and running workloads remotely, as well as easy resource management for multi-cloud and quantum-centric supercomputing use cases. Premium users can build, deploy, and run their workloads remotely on classical compute made available through IBM Quantum Platform. - **Qiskit Serverless is getting an upgrade, and its features are changing fast.** During this development phase, find release notes and the most recent documentation at the [Qiskit Serverless GitHub](https://qiskit.github.io/qiskit-serverless/index.html) page. + **Custom Functions is getting an upgrade, and its features are changing fast.** During this development phase, find release notes and the most recent documentation at the [Custom Functions GitHub](https://qiskit.github.io/qiskit-serverless/index.html) page. This is an experimental feature available only for IBM Quantum Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. -## When should I use Qiskit Serverless? +## When should I use Custom Functions? -Qiskit Serverless helps manage classical and quantum resources across the entire [Qiskit patterns](/docs/guides/intro-to-patterns) workflow. This includes some of the following examples: +Custom Functions helps manage classical and quantum resources across the entire [Qiskit patterns](/docs/guides/intro-to-patterns) workflow. This includes some of the following examples: - Parallelizing classical tasks, such as pre-processing and post-processing - Persisting long-running workloads in the cloud, even if your laptop is turned off @@ -27,31 +27,31 @@ Qiskit Serverless helps manage classical and quantum resources across the entire ## What is included? -The following compute resources are included by default in the Qiskit Serverless environment. Users can contact [support](/docs/guides/support) to increase any of these. +The following compute resources are included by default in the Custom Functions environment. Users can contact [support](/docs/guides/support) to increase any of these. - 16 vCPU cores - 64GB RAM - Maximum of two active jobs per user at any one time -## Install Qiskit Serverless +## Install Custom Functions -To use Qiskit Serverless on IBM Quantum Platform, install the following packages: +To use Custom Functions on IBM Quantum Platform, install the following packages: ```bash pip install qiskit-ibm-catalog qiskit_serverless ``` -`qiskit_ibm_catalog` provides the client-side tools to upload and run remote programs, while `qiskit_serverless` provides server-side tools to distribute compute and manage data. These packages require `python` 3.11+. For users and organizations who want to run Qiskit Serverless on custom infrastructure, follow the [Cloud infrastructure setup](https://qiskit.github.io/qiskit-serverless/) guide. +`qiskit_ibm_catalog` provides the client-side tools to upload and run remote programs, while `qiskit_serverless` provides server-side tools to distribute compute and manage data. These packages require `python` 3.11+. For users and organizations who want to run Custom Functions on custom infrastructure, follow the [Cloud infrastructure setup](https://qiskit.github.io/qiskit-serverless/) guide. -Currently, the IBM Quantum workloads table only reflects Qiskit Runtime workloads. Use `job.status()` to see your Qiskit Serverless workload's current status. Find an example in the [Run your first Qiskit Serverless workload remotely](/docs/guides/serverless-run-first-workload#serverless-job-status) guide. +Currently, the IBM Quantum workloads table only reflects Qiskit Runtime workloads. Use `job.status()` to see your Custom Functions workload's current status. Find an example in the [Run your first Custom Functions workload remotely](/docs/guides/serverless-run-first-workload#serverless-job-status) guide. ## Next steps -- Explore how to [write your first Qiskit Serverless program](/docs/guides/serverless-first-program). +- Explore how to [write your first Custom Functions program](/docs/guides/serverless-first-program). - Try out some [tutorials](/docs/tutorials). \ No newline at end of file