{ "cells": [ { "cell_type": "markdown", "id": "92e0efa3-cda3-491c-99fc-650b2ce4cfa8", "metadata": {}, "source": [ "---\n", "title: Install and use transpiler plugins\n", "description: How to install and use transpiler plugins in Qiskit.\n", "---\n", "\n", "# Install and use transpiler plugins\n", "\n" ] }, { "cell_type": "markdown", "id": "5a4052f5-554d-4633-a588-eb0583f66871", "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.3.1\n", " qiskit-ibm-runtime~=0.45.1\n", " ```\n", " \n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "12018a80-a1ce-4508-9d04-23c4176028e6", "metadata": {}, "source": [ "To facilitate the development and reuse of custom transpilation code by the wider community of Qiskit users, the Qiskit SDK supports a plugin interface that enables third-party Python packages to declare that they provide extended transpilation functionality accessible via Qiskit.\n", "\n", "Currently, third-party plugins can provide extended transpilation functionality in three ways:\n", "\n", "* A [transpiler stage plugin](/docs/api/qiskit/transpiler_plugins) provides a pass manager that can be used in place of one of the [6 stages](transpiler-stages) of a preset staged pass manager: `init`, `layout`, `routing`, `translation`, `optimization`, and `scheduling`.\n", "* A [unitary synthesis plugin](/docs/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin) provides extended functionality for unitary gate synthesis.\n", "* A [high-level synthesis plugin](/docs/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin) provides extended functionality for synthesizing \"high-level objects\" such as linear functions or Clifford operators. High-level objects are represented by subclasses of the [Operation](/docs/api/qiskit/qiskit.circuit.Operation) class.\n", "\n", "The rest of the page describes how to list available plugins, install new ones, and use them.\n", "\n" ] }, { "cell_type": "markdown", "id": "934388b3-8efd-43b6-82f8-ace84d3bb0d4", "metadata": {}, "source": [ "## List available plugins and install new ones\n", "\n", "Qiskit already includes some built-in plugins for transpilation. To install more, you can use your Python package manager. For example, you might run `pip install qiskit-toqm` to install the [Qiskit TOQM](https://github.com/qiskit-toqm/qiskit-toqm) routing stage plugin. A number of third-party plugins are part of the [Qiskit ecosystem](https://qiskit.github.io/ecosystem/#transpiler_plugin).\n", "\n", "### List available transpiler stage plugins\n", "\n", "Use the [list\\_stage\\_plugins](/docs/api/qiskit/transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins) function, passing the name of the stage whose plugins you want to list.\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "817254a8-77d7-4eb4-8630-623e67bb2186", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['default', 'dense', 'sabre', 'trivial']" ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from qiskit.transpiler.preset_passmanagers.plugin import list_stage_plugins\n", "\n", "list_stage_plugins(\"layout\")" ] }, { "cell_type": "code", "execution_count": 2, "id": "354f9be8-3567-4449-ba60-4d1c3258bb50", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['basic', 'default', 'lookahead', 'none', 'sabre']" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "list_stage_plugins(\"routing\")" ] }, { "cell_type": "markdown", "id": "ac57d3ce-afb3-4aba-8601-93513d4dd491", "metadata": {}, "source": [ "If `qiskit-toqm` were installed, then `toqm` would appear in the list of `routing` plugins.\n", "\n" ] }, { "cell_type": "markdown", "id": "1397de7f-c447-463e-8aba-ed1f569be86c", "metadata": {}, "source": [ "### List available unitary synthesis plugins\n", "\n", "Use the [unitary\\_synthesis\\_plugin\\_names](/docs/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names) function.\n", "\n" ] }, { "cell_type": "code", "execution_count": 3, "id": "596cbb3d-2ece-4193-929c-79149f7e23bd", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['aqc', 'clifford', 'default', 'gridsynth', 'sk']" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from qiskit.transpiler.passes.synthesis import unitary_synthesis_plugin_names\n", "\n", "unitary_synthesis_plugin_names()" ] }, { "cell_type": "markdown", "id": "e33885d4-788f-4759-bd63-e26d7a45ff9e", "metadata": {}, "source": [ "### List available high-level synthesis plugins\n", "\n", "Use the [high\\_level\\_synthesis\\_plugin\\_names](/docs/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.high_level_synthesis_plugin_names) function, passing the name of the type of \"high-level object\" to be synthesized. The name corresponds to the [`name`](/docs/api/qiskit/qiskit.circuit.Operation#name) attribute of the [Operation](/docs/api/qiskit/qiskit.circuit.Operation) class representing the type of object being synthesized.\n", "\n" ] }, { "cell_type": "code", "execution_count": 4, "id": "3b2d72bb-d661-4432-acfe-970f0a2dcd53", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['ag', 'bm', 'default', 'greedy', 'layers', 'lnn', 'rb_default']" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from qiskit.transpiler.passes.synthesis import (\n", " high_level_synthesis_plugin_names,\n", ")\n", "\n", "high_level_synthesis_plugin_names(\"clifford\")" ] }, { "cell_type": "markdown", "id": "583d7529-ab3e-449d-b7d0-e732801d7ae0", "metadata": {}, "source": [ "You can use the [HighLevelSynthesisPluginManager](/docs/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager) class to list the names of all high-level synthesis plugins:\n", "\n" ] }, { "cell_type": "code", "execution_count": 5, "id": "b17192e5-ddac-4cf6-b2e2-597e8c505568", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['FullAdder.default',\n", " 'FullAdder.ripple_c04',\n", " 'FullAdder.ripple_v95',\n", " 'HalfAdder.default',\n", " 'HalfAdder.qft_d00',\n", " 'HalfAdder.ripple_c04',\n", " 'HalfAdder.ripple_r25',\n", " 'HalfAdder.ripple_v95',\n", " 'IntComp.default',\n", " 'IntComp.noaux',\n", " 'IntComp.twos',\n", " 'ModularAdder.default',\n", " 'ModularAdder.modular_v17',\n", " 'ModularAdder.qft_d00',\n", " 'ModularAdder.ripple_c04',\n", " 'ModularAdder.ripple_v95',\n", " 'Multiplier.cumulative_h18',\n", " 'Multiplier.default',\n", " 'Multiplier.qft_r17',\n", " 'PauliEvolution.default',\n", " 'PauliEvolution.rustiq',\n", " 'WeightedSum.default',\n", " 'annotated.default',\n", " 'clifford.ag',\n", " 'clifford.bm',\n", " 'clifford.default',\n", " 'clifford.greedy',\n", " 'clifford.layers',\n", " 'clifford.lnn',\n", " 'linear_function.default',\n", " 'linear_function.kms',\n", " 'linear_function.pmh',\n", " 'mcmt.default',\n", " 'mcmt.noaux',\n", " 'mcmt.vchain',\n", " 'mcmt.xgate',\n", " 'mcx.1_clean_b95',\n", " 'mcx.1_clean_kg24',\n", " 'mcx.1_dirty_kg24',\n", " 'mcx.2_clean_kg24',\n", " 'mcx.2_dirty_kg24',\n", " 'mcx.default',\n", " 'mcx.gray_code',\n", " 'mcx.n_clean_m15',\n", " 'mcx.n_dirty_i15',\n", " 'mcx.noaux_hp24',\n", " 'mcx.noaux_v24',\n", " 'permutation.acg',\n", " 'permutation.basic',\n", " 'permutation.default',\n", " 'permutation.kms',\n", " 'permutation.token_swapper',\n", " 'qft.default',\n", " 'qft.full',\n", " 'qft.line',\n", " 'clifford.rb_default']" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from qiskit.transpiler.passes.synthesis.plugin import (\n", " HighLevelSynthesisPluginManager,\n", ")\n", "\n", "HighLevelSynthesisPluginManager().plugins.names()" ] }, { "cell_type": "markdown", "id": "4eed49d1-4723-4366-9edc-1f5aa73907ba", "metadata": {}, "source": [ "## Use a plugin\n", "\n", "In this section, we show how to use transpiler plugins. In the code examples, we use plugins that come with Qiskit, but plugins installed from third-party packages are used the same way.\n", "\n", "### Use a transpiler stage plugin\n", "\n", "To use a transpiler stage plugin, specify its name with the appropriate argument to [`generate_preset_pass_manager`](/docs/api/qiskit/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager) or [`transpile`](/docs/api/qiskit/compiler#qiskit.compiler.transpile). The argument is formed by appending `_method` to the name of the transpilation stage. For example, to use the `lookahead` routing plugin, we would specify `lookahead` for the `routing_method` argument.\n", "\n", "\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" ] }, { "cell_type": "code", "execution_count": 6, "id": "d5e598b3-9226-4fbc-ac76-8eca08ec4af3", "metadata": {}, "outputs": [], "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=3, backend=backend, routing_method=\"lookahead\"\n", ")" ] }, { "attachments": {}, "cell_type": "markdown", "id": "657db73c-7064-4569-a212-87642f16216e", "metadata": {}, "source": [ "### Use a unitary synthesis plugin\n", "\n", "To use a unitary synthesis plugin, specify its name as the `unitary_synthesis_method` argument to [`generate_preset_pass_manager`](/docs/api/qiskit/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager) or [`transpile`](/docs/api/qiskit/compiler#qiskit.compiler.transpile):\n", "\n" ] }, { "cell_type": "code", "execution_count": 7, "id": "28184c68-4b1e-46d2-a8a0-5480814bad9b", "metadata": {}, "outputs": [], "source": [ "pass_manager = generate_preset_pass_manager(\n", " optimization_level=3,\n", " backend=backend,\n", " unitary_synthesis_method=\"sk\",\n", " unitary_synthesis_plugin_config=dict(\n", " basis_gates=[\"cz\", \"id\", \"rz\", \"sx\", \"x\"]\n", " ),\n", ")" ] }, { "cell_type": "markdown", "id": "c019cb3d-5069-4257-bfb6-e15600caa342", "metadata": {}, "source": [ "Unitary synthesis is used in the `init`, `translation`, and `optimization` stages of the staged pass manager returned by [`generate_preset_pass_manager`](/docs/api/qiskit/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager) or used in [`transpile`](/docs/api/qiskit/compiler#qiskit.compiler.transpile). See [Transpiler stages](transpiler-stages) for a description of these stages.\n", "\n", "Use the `unitary_synthesis_plugin_config` argument, a free-form dictionary, to pass options for the unitary synthesis method. The documentation of the synthesis method should explain the options it supports. See [this list](/docs/api/qiskit/transpiler_synthesis_plugins#unitary-synthesis-plugins-2) for links to the documentation of the built-in unitary synthesis plugins.\n", "\n" ] }, { "attachments": {}, "cell_type": "markdown", "id": "d4ce7ad9-711f-4e43-9012-3f404b885ab1", "metadata": {}, "source": [ "### Use a high-level synthesis plugin\n", "\n", "First, create an [HLSConfig](/docs/api/qiskit/qiskit.transpiler.passes.HLSConfig) to\n", "store the names of the plugins to use for various high-level objects. For example:\n", "\n" ] }, { "cell_type": "code", "execution_count": 8, "id": "d4672004-aead-4827-9c10-5c70c3c2289b", "metadata": {}, "outputs": [], "source": [ "from qiskit.transpiler.passes import HLSConfig\n", "\n", "hls_config = HLSConfig(clifford=[\"layers\"], linear_function=[\"pmh\"])" ] }, { "cell_type": "markdown", "id": "4eab8d19-4b58-4f50-a205-039288e4a00d", "metadata": {}, "source": [ "This code cell creates a high-level synthesis configuration that uses the `layers` plugin\n", "for synthesizing [Clifford](/docs/api/qiskit/qiskit.quantum_info.Clifford#clifford) objects and the `pmh` plugin for synthesizing\n", "[LinearFunction](/docs/api/qiskit/qiskit.circuit.library.LinearFunction#linearfunction) objects. The names of the keyword arguments correspond to the\n", "[`name`](/docs/api/qiskit/qiskit.circuit.Operation#name) attribute of the [Operation](/docs/api/qiskit/qiskit.circuit.Operation) class representing the type of object being synthesized.\n", "For each high-level object, the list of given plugins are tried in sequence until one of them\n", "succeeds (in the example above, each list only contains a single plugin).\n", "\n", "In addition to specifying\n", "a plugin by its name, you can instead pass a `(name, options)` tuple, where the second element of the tuple is a dictionary containing options for the plugin. The documentation of the synthesis method should explain the options it supports. See [this list](/docs/api/qiskit/transpiler_synthesis_plugins#high-level-synthesis-plugins-2) for links to the documentation of the built-in high-level synthesis plugins.\n", "\n", "Once you have created the `HLSConfig` object, pass it as the\n", "`hls_config` argument to [`generate_preset_pass_manager`](/docs/api/qiskit/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager) or [`transpile`](/docs/api/qiskit/compiler#qiskit.compiler.transpile):\n", "\n" ] }, { "cell_type": "code", "execution_count": 9, "id": "8784b881-2f37-4f75-b5c7-c84cdb8b8a60", "metadata": {}, "outputs": [], "source": [ "pass_manager = generate_preset_pass_manager(\n", " optimization_level=3, backend=backend, hls_config=hls_config\n", ")" ] }, { "cell_type": "markdown", "id": "ea63c611-c213-4736-83f7-c46e918eb862", "metadata": {}, "source": [ "High-level synthesis is used in the `init`, `translation`, and `optimization` stages of the staged pass manager returned by [`generate_preset_pass_manager`](/docs/api/qiskit/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager) or used in [`transpile`](/docs/api/qiskit/compiler#qiskit.compiler.transpile). See [Transpiler stages](transpiler-stages) for a description of these stages.\n", "\n" ] }, { "cell_type": "markdown", "id": "aae87a98-f16d-4ac1-9b85-11a771e04224", "metadata": {}, "source": [ "## Next steps\n", "\n", "\n", " * [Create a transpiler plugin](./create-transpiler-plugin).\n", " * Check out the [tutorials](/docs/tutorials) for examples of transpiling and running quantum circuits.\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": 4 }