{ "cells": [ { "cell_type": "markdown", "id": "d53161ce", "metadata": {}, "source": [ "---\n", "title: Set transpiler optimization level\n", "description: How to set the optimization level for transpiling quantum circuits in Qiskit.\n", "---\n", "\n", "{/* cspell:ignore Cartan's */}\n", "\n" ] }, { "cell_type": "markdown", "id": "6f5a4641-5b7f-4841-8bec-60fa44429030", "metadata": {}, "source": [ "# Set transpiler optimization level\n", "\n" ] }, { "cell_type": "markdown", "id": "8a1db79c-9bee-4737-b8b5-13155062ca04", "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[all]~=2.6.1\n", " qiskit-ibm-runtime~=0.50.0\n", " ```\n", " \n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "bd9eb973-430c-4450-8de2-c061aa0ff742", "metadata": {}, "source": [ "Real quantum devices are subject to noise and gate errors, so optimizing the circuits to reduce their depth and gate count can significantly improve the results obtained from executing those circuits.\n", "The [`generate_preset_pass_manager`](/docs/api/qiskit/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager) function has one required positional argument, `optimization_level`, that controls how much effort the transpiler spends on optimizing circuits. This argument can be an integer taking one of the values 0, 1, 2, or 3.\n", "Higher optimization levels generate more optimized circuits at the expense of longer compile times.\n", "The following table explains the optimizations performed with each setting.\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", " \n", " \n", " \n", "\n", " \n", " \n", "\n", " \n", " \n", "\n", " \n", " \n", "\n", " \n", " \n", "\n", " \n", " \n", "\n", " \n", " \n", "\n", " \n", " \n", " \n", "
Optimization LevelDescription
0\n", " No optimization: typically used for hardware characterization\n", "\n", " * Basic translation\n", " * Layout/Routing: `TrivialLayout`, where it selects the same physical qubit numbers as virtual and inserts SWAPs to make it work (using `SabreSwap`)\n", "
1\n", " Light optimization:\n", "\n", " * Layout/Routing: Layout is first attempted with `TrivialLayout`. If additional SWAPs are required, a layout with a minimum number of SWAPs is found by using `SabreSwap`, then it uses `VF2LayoutPostLayout` to try to select the best qubits in the graph.\n", " * `InverseCancellation`\n", " * 1Q gate optimization\n", "
2\n", " Medium optimization:\n", "\n", " * Layout/Routing: Optimization level 1 (without trivial) + heuristic optimized with greater\n", " search depth and trials of optimization function. Because `TrivialLayout` is not used, there is no attempt to use the same physical and virtual qubit numbers.\n", " * `CommutativeCancellation`\n", "
3\n", " High Optimization:\n", "\n", " * Optimization level 2 + heuristic optimized on layout/routing further with greater effort/trials\n", " * Resynthesis of two-qubit blocks using [Cartan's KAK Decomposition](https://arxiv.org/abs/quant-ph/0507171).\n", " * Unitarity-breaking passes:\n", " * `OptimizeSwapBeforeMeasure`: Moves the measurements around to avoid SWAPs\n", " * `RemoveDiagonalGatesBeforeMeasure`: Removes gates before measurements that would not effect the measurements\n", "
\n", "\n", "## Optimization level in action\n", "\n", "Since two-qubit gates are typically the most significant source of errors, we can approximately quantify the transpilation's \"hardware efficiency\" by counting the number of two-qubit gates in the resulting circuit.\n", "Here, we'll try the different optimization levels on an input circuit consisting of a random unitary followed by a SWAP gate.\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "81173ebc-8359-48a6-b585-0477907b3b93", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from qiskit import QuantumCircuit\n", "from qiskit.circuit.library import UnitaryGate\n", "from qiskit.quantum_info import Operator, random_unitary\n", "\n", "UU = random_unitary(4, seed=12345)\n", "rand_U = UnitaryGate(UU)\n", "\n", "qc = QuantumCircuit(2)\n", "qc.append(rand_U, range(2))\n", "qc.swap(0, 1)\n", "qc.draw(\"mpl\", style=\"iqp\")" ] }, { "cell_type": "markdown", "id": "34509d07-7804-46cb-b508-130436d9b01d", "metadata": {}, "source": [ "\n", " The `FakeSherbrooke` mock backend from `qiskit_ibm_runtime` is used in these examples, but you can try it on any Qiskit-compatible real or fake backend. Your results might be different.\n", "\n", "\n", "First, let's transpile using optimization level 0.\n", "\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "40cdd173-b437-48b1-8928-741e8411342e", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from qiskit.transpiler import generate_preset_pass_manager\n", "from qiskit_ibm_runtime.fake_provider import FakeSherbrooke\n", "\n", "backend = FakeSherbrooke()\n", "\n", "pass_manager = generate_preset_pass_manager(\n", " optimization_level=0, backend=backend, seed_transpiler=12345\n", ")\n", "qc_t1_exact = pass_manager.run(qc)\n", "qc_t1_exact.draw(\"mpl\", idle_wires=False)" ] }, { "cell_type": "markdown", "id": "a5169cb2-cd2a-40c0-93e5-c526580f84aa", "metadata": {}, "source": [ "The transpiled circuit has six of the two-qubit ECR gates.\n", "\n", "Repeat for optimization level 1:\n", "\n" ] }, { "cell_type": "code", "execution_count": 3, "id": "2dab5def-a017-42e9-92d6-e043ac4065b2", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from qiskit.transpiler import generate_preset_pass_manager\n", "from qiskit_ibm_runtime.fake_provider import FakeSherbrooke\n", "\n", "backend = FakeSherbrooke()\n", "\n", "pass_manager = generate_preset_pass_manager(\n", " optimization_level=1, backend=backend, seed_transpiler=12345\n", ")\n", "qc_t1_exact = pass_manager.run(qc)\n", "qc_t1_exact.draw(\"mpl\", idle_wires=False)" ] }, { "cell_type": "markdown", "id": "69d5d04b-746f-41c4-92e8-62a7eaffb5b2", "metadata": {}, "source": [ "The transpiled circuit still has six ECR gates, but the number of single-qubit gates has reduced.\n", "\n", "Repeat for optimization level 2:\n", "\n" ] }, { "cell_type": "code", "execution_count": 4, "id": "77d76048-b1e8-4225-b35f-80dc9d458e8d", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "pass_manager = generate_preset_pass_manager(\n", " optimization_level=2, backend=backend, seed_transpiler=12345\n", ")\n", "qc_t2_exact = pass_manager.run(qc)\n", "qc_t2_exact.draw(\"mpl\", idle_wires=False)" ] }, { "cell_type": "markdown", "id": "4818fb06-88bd-43cb-b23c-eba5a3537e67", "metadata": {}, "source": [ "This yields the same results as optimization level 1. Note that increasing the level of optimization does not always make a difference.\n", "\n", "Repeat again, with optimization level 3:\n", "\n" ] }, { "cell_type": "code", "execution_count": 5, "id": "4109d0e2-df37-4850-8409-6b860c48595c", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "pass_manager = generate_preset_pass_manager(\n", " optimization_level=3, backend=backend, seed_transpiler=12345\n", ")\n", "qc_t3_exact = pass_manager.run(qc)\n", "qc_t3_exact.draw(\"mpl\", idle_wires=False)" ] }, { "cell_type": "markdown", "id": "c9cf6dcf-733f-494f-a571-43d47d3908ce", "metadata": {}, "source": [ "Now, there are only three ECR gates. We obtain this result because at optimization level 3, Qiskit tries to re-synthesize two-qubit blocks of gates, and any two-qubit gate can be implemented using at most three ECR gates. We can get even fewer ECR gates if we set `approximation_degree` to a value less than 1, allowing the transpiler to make approximations that may introduce some error in the gate decomposition (see [Commonly used parameters for transpilation](common-parameters#approximation-degree)):\n", "\n" ] }, { "cell_type": "code", "execution_count": 6, "id": "bf239116-b8bb-42aa-a27a-89206d9e108a", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "pass_manager = generate_preset_pass_manager(\n", " optimization_level=3,\n", " approximation_degree=0.99,\n", " backend=backend,\n", " seed_transpiler=12345,\n", ")\n", "qc_t3_approx = pass_manager.run(qc)\n", "qc_t3_approx.draw(\"mpl\", idle_wires=False)" ] }, { "cell_type": "markdown", "id": "247f60a9-b0ad-4e83-85ea-008dc808267f", "metadata": {}, "source": [ "This circuit has only two ECR gates, but it's an approximate circuit. To understand how its effect differs from the exact circuit, we can calculate the fidelity between the unitary operator this circuit implements, and the exact unitary. Before performing the computation, we first reduce the transpiled circuit, which contains 127 qubits, down to a circuit that only contains the active qubits, of which there are two.\n", "\n" ] }, { "cell_type": "code", "execution_count": 7, "id": "56988ecd-8a78-42ca-90eb-fc956674c64d", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Synthesis fidelity\n", "Exact: 1.000+0.000j\n", "Approximate: 0.992+0.000j\n" ] } ], "source": [ "import numpy as np\n", "\n", "\n", "def trace_to_fidelity_2q(trace: float) -> float:\n", " return (4.0 + trace * trace.conjugate()) / 20.0\n", "\n", "\n", "# Reduce circuits down to 2 qubits so they are easy to simulate\n", "qc_t3_exact_small = QuantumCircuit.from_instructions(qc_t3_exact)\n", "qc_t3_approx_small = QuantumCircuit.from_instructions(qc_t3_approx)\n", "\n", "# Compute the fidelity\n", "exact_fid = trace_to_fidelity_2q(\n", " np.trace(np.dot(Operator(qc_t3_exact_small).adjoint().data, UU))\n", ")\n", "approx_fid = trace_to_fidelity_2q(\n", " np.trace(np.dot(Operator(qc_t3_approx_small).adjoint().data, UU))\n", ")\n", "print(\n", " f\"Synthesis fidelity\\nExact: {exact_fid:.3f}\\nApproximate: {approx_fid:.3f}\"\n", ")" ] }, { "cell_type": "markdown", "id": "382f6ffc-1d17-4c4b-8ea1-2f828c705793", "metadata": { "jp-MarkdownHeadingCollapsed": true }, "source": [ "Adjusting the optimization level can change other aspects of the circuit too, not just the number of ECR gates. For examples of how setting optimization level changes the layout, see [Representing quantum computers](/docs/qiskit/represent-quantum-computers).\n", "\n", "## Next steps\n", "\n", "\n", " * To learn more about the `generate_preset_passmanager` function, start with the [Transpilation default settings and configuration options](defaults-and-configuration-options) topic.\n", " * Continue learning about transpilation with the [Transpiler stages](transpiler-stages) topic.\n", " * Try the [Compare transpiler settings](/docs/qiskit/circuit-transpilation-settings) guide.\n", " * Try the [Build repetition codes](/docs/tutorials/repetition-codes) tutorial.\n", " * See the [Transpile API documentation](/docs/api/qiskit/transpiler).\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 }