{ "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 */}\n", "\n" ] }, { "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", "\n", "\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", " 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", "\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).\n", "\n" ] }, { "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", "![Visualization of the Optimization Solver workflow](https://quantum.cloud.ibm.com/docs/images/guides/qctrl-optimization/solver_workflow.svg)\n", "\n", "To solve a generic problem with the Optimization Solver:\n", "\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.\n", "\n" ] }, { "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", "### Supported backends\n", "\n", "Run the following code to see the list of backends that are currently supported. If your device is not listed, [reach out to Q-CTRL](https://form.typeform.com/to/iuujEAEI?typeform-source=q-ctrl.com) to add support.\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "36d78eb4", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "[,\n", " ,\n", " ,\n", " ,\n", " ,\n", " ]" ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from qiskit_ibm_runtime import QiskitRuntimeService\n", "\n", "service = QiskitRuntimeService()\n", "\n", "service.backends()" ] }, { "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 |\n", "\n" ] }, { "cell_type": "markdown", "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.)\n", "\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "95a715d2", "metadata": {}, "outputs": [], "source": [ "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", "\n", "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n", "\n", "# Access Function\n", "solver = catalog.load(\"q-ctrl/optimization-solver\")" ] }, { "cell_type": "markdown", "id": "e8837f5f", "metadata": {}, "source": [ "## Example: Unconstrained optimization\n", "\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.\n", "\n" ] }, { "cell_type": "markdown", "id": "a699235b", "metadata": {}, "source": [ "In addition to `qiskit-ibm-catalog`, you will also use the following packages to run this example: `networkx` and `numpy`. You can install these packages by uncommenting the following cell if you are running this example in a notebook using the IPython kernel.\n", "\n" ] }, { "cell_type": "code", "execution_count": 3, "id": "a74fe6a9", "metadata": {}, "outputs": [], "source": [ "# %pip install networkx numpy" ] }, { "cell_type": "markdown", "id": "a41c4a0d", "metadata": {}, "source": [ "### 1. Define the problem\n", "\n", "You can run a max-cut problem by defining a graph problem and specifying `problem_type='maxcut'`.\n", "\n" ] }, { "cell_type": "code", "execution_count": 4, "id": "d56e1440", "metadata": {}, "outputs": [], "source": [ "import networkx as nx\n", "import numpy as np\n", "\n", "# Generate a random graph with 156 nodes\n", "maxcut_graph = nx.random_regular_graph(d=3, n=156, seed=8)" ] }, { "cell_type": "code", "execution_count": 5, "id": "0a7255e1", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Optionally, visualize the graph\n", "nx.draw_networkx(\n", " maxcut_graph, nx.kamada_kawai_layout(maxcut_graph), node_size=100\n", ")" ] }, { "cell_type": "markdown", "id": "e42a8d55", "metadata": {}, "source": [ "The Solver accepts a string as the problem definition input.\n", "\n" ] }, { "cell_type": "code", "execution_count": 6, "id": "2546e3e5", "metadata": {}, "outputs": [], "source": [ "# Convert graph to string\n", "problem_as_str = nx.readwrite.json_graph.adjacency_data(maxcut_graph)" ] }, { "cell_type": "markdown", "id": "0ab6f24f", "metadata": {}, "source": [ "### 2. Run the problem\n", "\n", "When using the graph-based input method, specify the problem type.\n", "\n" ] }, { "cell_type": "code", "execution_count": 8, "id": "16c66d64", "metadata": {}, "outputs": [], "source": [ "# Solve the problem\n", "maxcut_job = solver.run(\n", " problem=problem_as_str,\n", " problem_type=\"maxcut\",\n", " backend_name=backend_name, # E.g. \"ibm_fez\"\n", ")" ] }, { "cell_type": "markdown", "id": "48069093", "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:\n", "\n" ] }, { "cell_type": "code", "execution_count": 9, "id": "856fe992", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "QUEUED\n" ] } ], "source": [ "# Get job status\n", "print(maxcut_job.status())" ] }, { "cell_type": "markdown", "id": "74f48eab", "metadata": {}, "source": [ "### 3. Retrieve the result\n", "\n", "Retrieve the optimal cut value from the results dictionary.\n", "\n", "\n", " The mapping of the variables to the bitstring may have changed. The output dictionary contains a `variables_to_bitstring_index_map` sub-dictionary, which helps to verify the ordering.\n", "\n", "\n" ] }, { "cell_type": "code", "execution_count": 10, "id": "6b571411", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Optimal cut value: 210.0\n" ] } ], "source": [ "# Poll for results\n", "maxcut_result = maxcut_job.result()\n", "\n", "# Take the absolute value of the solution since the cost function is minimized\n", "qctrl_maxcut = abs(maxcut_result[\"solution_bitstring_cost\"])\n", "\n", "# Print the optimal cut value found by the Optimization Solver\n", "print(f\"Optimal cut value: {qctrl_maxcut}\")" ] }, { "cell_type": "markdown", "id": "508e29b0", "metadata": {}, "source": [ "You can verify the accuracy of the result by solving the problem classically with open-source solvers like [PuLP](https://coin-or.github.io/pulp/) if the graph is not densely connected. High density problems may require advanced classical solvers to validate the solution.\n", "\n" ] }, { "cell_type": "markdown", "id": "e2817b13", "metadata": {}, "source": [ "## Example: Constrained optimization\n", "\n", "The prior max-cut example is a common quadratic unconstrained binary optimization problem. Q-CTRL's Optimization Solver can be used for various problem types, including constrained optimization. You can solve arbitrary problem types by inputting the problem definition represented as a polynomial where constraints are modeled as penalty terms.\n", "\n", "The following example demonstrates how to construct a cost function for a constrained optimization problem, [minimum vertex cover](https://en.wikipedia.org/wiki/Vertex_cover) (MVC).\n", "\n" ] }, { "cell_type": "markdown", "id": "a9fbc0e9", "metadata": {}, "source": [ "In addition to the `qiskit-ibm-catalog` and `qiskit` packages, you will also use the following packages to run this example: `numpy`, `networkx`, and `sympy`. You can install these packages by uncommenting the following cell if you are running this example in a notebook using the IPython kernel.\n", "\n" ] }, { "cell_type": "code", "execution_count": 11, "id": "c6428fd0", "metadata": {}, "outputs": [], "source": [ "# %pip install numpy networkx sympy" ] }, { "cell_type": "markdown", "id": "98d3bfd3", "metadata": {}, "source": [ "### 1. Define the problem\n", "\n", "Define a random MVC problem by generating a graph with randomly weighted nodes.\n", "\n" ] }, { "cell_type": "code", "execution_count": 12, "id": "c2ce65e3", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "import networkx as nx\n", "from sympy import symbols, Poly, srepr\n", "\n", "# To change the weights, change the seed to any integer.\n", "rng_seed = 18\n", "_rng = np.random.default_rng(rng_seed)\n", "node_count = 50\n", "edge_probability = 0.08\n", "mvc_graph = nx.erdos_renyi_graph(\n", " node_count, edge_probability, seed=rng_seed, directed=False\n", ")\n", "\n", "# add node weights\n", "for i in mvc_graph.nodes:\n", " mvc_graph.add_node(i, weight=_rng.random())\n", "\n", "# Optionally, visualize the graph\n", "nx.draw_networkx(mvc_graph, nx.kamada_kawai_layout(mvc_graph), node_size=200)" ] }, { "cell_type": "markdown", "id": "89c91472", "metadata": {}, "source": [ "A standard optimization model for weighted MVC can be formulated as follows. First, a penalty must be added for any case where an edge is not connected to a vertex in the subset. Therefore, let $n_i = 1$ if vertex $i$ is in the cover (i.e., in the subset) and $n_i = 0$ otherwise. Second, the goal is to minimize the total number of vertices in the subset, which can be represented by the following function:\n", "\n", "$\\textbf{Minimize}\\qquad y = \\sum_{i\\in V} \\omega_i n_i$\n", "\n" ] }, { "cell_type": "code", "execution_count": 13, "id": "91586ee9", "metadata": {}, "outputs": [], "source": [ "# Construct the cost function.\n", "variables = symbols([f\"n[{i}]\" for i in range(node_count)])\n", "cost_function = Poly(0, variables)\n", "\n", "for i in mvc_graph.nodes():\n", " weight = mvc_graph.nodes[i].get(\"weight\", 0)\n", " cost_function += variables[i] * weight" ] }, { "cell_type": "markdown", "id": "9d01684b", "metadata": {}, "source": [ "Now every edge in the graph should include at least one end point from the cover, which can be expressed as the inequality:\n", "\n", "$n_i + n_j \\ge 1 \\texttt{ for all } (i,j)\\in E$\n", "\n", "Any case where an edge is not connected to the vertex of cover must be penalized. This can be represented in the cost function by adding a penalty of the form $P(1-n_i-n_j+n_i n_j)$ where $P$ is a positive penalty constant. Thus, an unconstrained alternative to the constrained inequality for weighted MVC is:\n", "\n", "$\\textbf{Minimize}\\qquad y = \\sum_{i\\in V}\\omega_i n_i + P(\\sum_{(i,j)\\in E}(1 - n_i - n_j + n_i n_j))$\n", "\n" ] }, { "cell_type": "code", "execution_count": 14, "id": "1ff1ffcc", "metadata": {}, "outputs": [], "source": [ "# Add penalty term.\n", "penalty_constant = 2\n", "for i, j in mvc_graph.edges():\n", " cost_function += penalty_constant * (\n", " 1 - variables[i] - variables[j] + variables[i] * variables[j]\n", " )" ] }, { "cell_type": "markdown", "id": "9fd0ba9e", "metadata": {}, "source": [ "### 2. Run the problem\n", "\n" ] }, { "cell_type": "code", "execution_count": 15, "id": "f380b56d", "metadata": {}, "outputs": [], "source": [ "# Solve the problem\n", "mvc_job = solver.run(\n", " problem=srepr(cost_function),\n", " backend_name=backend_name, # E.g. \"ibm_fez\"\n", ")" ] }, { "cell_type": "markdown", "id": "d154c226", "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:\n", "\n" ] }, { "cell_type": "code", "execution_count": 16, "id": "6de77b14", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "QUEUED\n" ] } ], "source": [ "print(mvc_job.status())" ] }, { "cell_type": "markdown", "id": "8a95618e", "metadata": {}, "source": [ "### 3. Get the result\n", "\n", "Retrieve the solution and analyze the results. Because this problem has weighted nodes, the solution is not simply the minimum number of nodes covered. Instead, the solution cost represents the sum of the weights of the vertices that are included in the vertex cover. It represents the total \"cost\" or \"weight\" of covering all the edges in the graph using the selected vertices.\n", "\n" ] }, { "cell_type": "code", "execution_count": 17, "id": "a924bf93", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Solution cost: 10.248198273708624\n" ] } ], "source": [ "mvc_result = mvc_job.result()\n", "qctrl_cost = mvc_result[\"solution_bitstring_cost\"]\n", "\n", "# 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).\n", "\n" ] }, { "cell_type": "markdown", "id": "993aa226c6ec9f5e", "metadata": {}, "source": [ "## Changelog\n", "\n", "* 2026-02-11: We now have support for `ibm_miami`\n", "\n" ] }, { "cell_type": "markdown", "id": "5a6a25c8", "metadata": {}, "source": [ "## Next steps\n", "\n", "\n", " * Request access to [Q-CTRL Optimization Solver](/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", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "id": "a1b8767d", "source": "© IBM Corp., 2017-2026" } ], "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 }