From 7085d969f4cf956f1d776316c72709165bca1b87 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Tue, 6 Feb 2024 14:16:46 -0500 Subject: [PATCH 01/25] add transpiler plugin docs --- .../create-a-transpiler-plugin.ipynb | 309 ++++++++++++++++++ docs/transpile/transpiler-plugins.ipynb | 299 +++++++++++++++++ 2 files changed, 608 insertions(+) create mode 100644 docs/transpile/create-a-transpiler-plugin.ipynb create mode 100644 docs/transpile/transpiler-plugins.ipynb diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb new file mode 100644 index 00000000000..2f31c07567e --- /dev/null +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -0,0 +1,309 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "58b1f0a7-d62e-4f71-ba01-b8f0beaeeb83", + "metadata": {}, + "source": [ + "# Create a transpiler plugin\n", + "\n", + "Creating a [transpiler plugin](transpiler-plugins) is a great way to share your transpilation code with the wider Qiskit community, allowing other users to benefit from the functionality you've developed. Thank you for your interest in contributing to the Qiskit community!\n", + "\n", + "Before you create a transpiler plugin, you need to decide what kind of plugin is appropriate for your situation. There are three kinds of transpiler plugins:\n", + "- [**Transpiler stage plugin**](/api/qiskit/transpiler_plugins). Choose this if you are defining a pass manager that can be substituted for one of the [6 stages](transpiler-stages) of a preset staged pass manager.\n", + "- [**Unitary synthesis plugin**](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin). Choose this if your transpilation code takes as input a unitary matrix and outputs a description of a quantum circuit implementing that unitary.\n", + "- [**High-level synthesis plugin**](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin). Choose this if your transpilation code takes as input a \"high-level object\" such as a Clifford operator or a linear function and outputs a description of a quantum circuit implementing that high-level object. High-level objects are represented by subclasses of the [Operation](/api/qiskit/qiskit.circuit.Operation) class.\n", + "\n", + "Once you've determined which kind of plugin to create, follow these steps to create the plugin:\n", + "\n", + "1. Create a subclass of the appropriate abstract plugin class:\n", + " - [PassManagerStagePlugin](/api/qiskit/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin) for a transpiler stage plugin,\n", + " - [UnitarySynthesisPlugin](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin) for a unitary synthesis plugin, and\n", + " - [HighLevelSynthesisPlugin](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin) for a high-level synthesis plugin.\n", + "2. Expose the class as a [setuptools entry point](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) in the package metadata, typically by adding an `entry-points` table in `pyproject.toml`.\n", + "\n", + "There is no limit to the number of plugins a single package can define, but each plugin must have a unique name. The name `default` is used by Qiskit itself and can't be used in a plugin.\n", + "\n", + "In the next sections, we show examples of these steps for the different types of plugins. In these examples, we assume that we are creating a Python package called `my_qiskit_plugin`. For information on creating Python packages, you can check out [this tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/) from the Python website." + ] + }, + { + "cell_type": "markdown", + "id": "4519c0dc-2bcd-48f4-8522-435b72efdb40", + "metadata": {}, + "source": [ + "## Example: Create a transpiler stage plugin\n", + "\n", + "In this example, we create a transpiler stage plugin for the `layout` stage (see [Transpiler stages](transpiler-stages) for a description of the 6 stages of Qiskit's built-in transpilation pipeline).\n", + "Our plugin simply runs [VF2Layout](/api/qiskit/qiskit.transpiler.passes.VF2Layout) for a number of trials that depends on the requested optimization level.\n", + "\n", + "First, we create a subclass of [PassManagerStagePlugin](/api/qiskit/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin). There is one method we need to implement, called [`pass_manager`](/api/qiskit/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin#pass_manager). This method takes as input a [PassManagerConfig](/api/qiskit/qiskit.transpiler.PassManagerConfig) and returns the pass manager that we are defining. The PassManagerConfig object stores information about the target backend, such as its coupling map and basis gates." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "f90299d9-5026-424c-b528-6d0defdddb54", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.transpiler import PassManager\n", + "from qiskit.transpiler.passes import VF2Layout\n", + "from qiskit.transpiler.passmanager_config import PassManagerConfig\n", + "from qiskit.transpiler.preset_passmanagers import common\n", + "from qiskit.transpiler.preset_passmanagers.plugin import PassManagerStagePlugin\n", + "\n", + "\n", + "class MyLayoutPlugin(PassManagerStagePlugin):\n", + " def pass_manager(\n", + " self,\n", + " pass_manager_config: PassManagerConfig,\n", + " optimization_level: int | None = None,\n", + " ) -> PassManager:\n", + " layout_pm = PassManager(\n", + " [\n", + " VF2Layout(\n", + " coupling_map=pass_manager_config.coupling_map,\n", + " properties=pass_manager_config.backend_properties,\n", + " max_trials=optimization_level * 10 + 1,\n", + " target=pass_manager_config.target,\n", + " )\n", + " ]\n", + " )\n", + " layout_pm += common.generate_embed_passmanager(pass_manager_config.coupling_map)\n", + " return layout_pm" + ] + }, + { + "cell_type": "markdown", + "id": "d7666879-14bc-479c-a91b-56a800897073", + "metadata": {}, + "source": [ + "Now, we expose the plugin by adding an `entry-points` table in `pyproject.toml` under the appropriate namespace. See the [table of transpiler plugin stages](/api/qiskit/transpiler_plugins#stage-table) for the entry points and expectations for each stage.\n", + "To expose this plugin in a package called `my_qiskit_plugin`, we would add the following in `pyproject.toml`:\n", + "\n", + "```toml\n", + "[project.entry-points.\"qiskit.transpiler.layout\"]\n", + "\"vf2\" = \"my_qiskit_plugin.module.plugin:MyLayoutPlugin\"\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "fe3a1a6c-5aa2-4f00-9bdd-45598717be1d", + "metadata": {}, + "source": [ + "## Example: Create a unitary synthesis plugin\n", + "\n", + "In this example, we'll create a unitary synthesis plugin that simply uses the built-in [UnitarySynthesis](/api/qiskit/qiskit.transpiler.passes.UnitarySynthesis#unitarysynthesis) transpilation pass to synthesize a gate. Of course, your own plugin will do something more interesting than that.\n", + "\n", + "The [UnitarySynthesisPlugin](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin) class defines the interface and contract for unitary synthesis\n", + "plugins. The primary method is\n", + "[`run`](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin#run),\n", + "which takes as input a Numpy array storing a unitary matrix\n", + "and returns a [DAGCircuit](/api/qiskit/qiskit.dagcircuit.DAGCircuit) representing the circuit synthesized from that unitary matrix.\n", + "In addition to the `run` method, there are a number of property methods that need to be defined.\n", + "See [UnitarySynthesisPlugin](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin) for documentation of all required properties.\n", + "\n", + "Let's create our UnitarySynthesisPlugin subclass:" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "6bc1011c-b15d-4210-973b-d9d530ece880", + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "from qiskit.circuit import QuantumCircuit, QuantumRegister\n", + "from qiskit.converters import circuit_to_dag\n", + "from qiskit.dagcircuit.dagcircuit import DAGCircuit\n", + "from qiskit.quantum_info import Operator\n", + "from qiskit.transpiler.passes import UnitarySynthesis\n", + "from qiskit.transpiler.passes.synthesis.plugin import UnitarySynthesisPlugin\n", + "\n", + "\n", + "class MyUnitarySynthesisPlugin(UnitarySynthesisPlugin):\n", + " @property\n", + " def supports_basis_gates(self):\n", + " return True\n", + "\n", + " @property\n", + " def supports_coupling_map(self):\n", + " return False\n", + "\n", + " @property\n", + " def supports_natural_direction(self):\n", + " return False\n", + "\n", + " @property\n", + " def supports_pulse_optimize(self):\n", + " return False\n", + "\n", + " @property\n", + " def supports_gate_lengths(self):\n", + " return False\n", + "\n", + " @property\n", + " def supports_gate_errors(self):\n", + " return False\n", + "\n", + " @property\n", + " def supports_gate_lengths_by_qubit(self):\n", + " return False\n", + "\n", + " @property\n", + " def supports_gate_errors_by_qubit(self):\n", + " return False\n", + "\n", + " @property\n", + " def min_qubits(self):\n", + " return None\n", + "\n", + " @property\n", + " def max_qubits(self):\n", + " return None\n", + "\n", + " @property\n", + " def supported_bases(self):\n", + " return None\n", + "\n", + " def run(self, unitary: np.ndarray, **options) -> DAGCircuit:\n", + " basis_gates = options[\"basis_gates\"]\n", + " synth_pass = UnitarySynthesis(basis_gates, min_qubits=3)\n", + " qubits = QuantumRegister(3)\n", + " circuit = QuantumCircuit(qubits)\n", + " circuit.append(Operator(unitary).to_instruction(), qubits)\n", + " dag_circuit = synth_pass.run(circuit_to_dag(circuit))\n", + " return dag_circuit" + ] + }, + { + "cell_type": "markdown", + "id": "6daebf1b-aa38-44a8-bf62-eea96838e95f", + "metadata": {}, + "source": [ + "If you find that the inputs available to the [`run`](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin#run)\n", + "method are insufficient for your purposes, please [open an issue](https://github.com/Qiskit/qiskit/issues/new/choose) explaining your requirements. Changes to the plugin interface, such as adding additional optional inputs, will be done in a backward compatible way so that they do not require changes from existing plugins.\n", + "\n", + "\n", + "All methods prefixed with `supports_` are reserved on a `UnitarySynthesisPlugin` derived class as part of the interface. You should not define any custom `supports_*` methods on a subclass that are not defined in the abstract class.\n", + "\n", + "\n", + "Now, we expose the plugin by adding an `entry-points` table in `pyproject.toml` under the `qiskit.unitary_synthesis` namespace.\n", + "To expose this plugin in a package called `my_qiskit_plugin`, we would add the following in `pyproject.toml`:\n", + "\n", + "```toml\n", + "[project.entry-points.\"qiskit.unitary_synthesis\"]\n", + "\"special\" = \"my_qiskit_plugin.module.plugin:MyUnitarySynthesisPlugin\"\n", + "```\n", + "\n", + "To accommodate unitary synthesis plugins that expose multiple options,\n", + "the plugin interface has an option for users to provide a free-form\n", + "configuration dictionary. This will be passed to the `run` method\n", + "via the `options` keyword argument. If your plugin has these configuration options, you should clearly document them." + ] + }, + { + "cell_type": "markdown", + "id": "651c863d-41d9-41f4-a133-b392dae2f363", + "metadata": {}, + "source": [ + "## Example: Create a high-level synthesis plugin\n", + "\n", + "In this example, we'll create a high-level synthesis plugin that simply uses the built-in [synth_clifford_bm](/api/qiskit/synthesis#synth_clifford_bm) function to synthesize a Clifford operator.\n", + "\n", + "The [HighLevelSynthesisPlugin](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin) class defines the interface and contract for high-level synthesis plugins. The primary method is [`run`](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin#run).\n", + "The positional argument `high_level_object` is an [Operation](/api/qiskit/qiskit.circuit.Operation) representing the \"high-level\" object to be synthesized. For example, it could be a\n", + "[LinearFunction](/api/qiskit/qiskit.circuit.library.LinearFunction) or a\n", + "[Clifford](/api/qiskit/qiskit.quantum_info.Clifford).\n", + "The following keyword arguments are present:\n", + "- `target` specifies the target backend, allowing the plugin\n", + "to access all target-specific information,\n", + "such as the coupling map, the supported gate set, and so on\n", + "- `coupling_map` only specifies the coupling map, and is only used when `target` is not specified.\n", + "- `qubits` specifies the list of qubits over which the\n", + "high-level object is defined, in case the synthesis is done on the physical circuit.\n", + "A value of ``None`` indicates that the layout has not yet been chosen and the physical qubits in the target or coupling map that this operation is operating on has not yet been determined.\n", + "- `options`, a free-form configuration dictionary for plugin-specific options. If your plugin has these configuration options you\n", + "should clearly document them.\n", + "\n", + "The `run` method returns a [QuantumCircuit](/api/qiskit/qiskit.circuit.QuantumCircuit)\n", + "representing the circuit synthesized from that high-level object.\n", + "It is also allowed to return `None`, indicating that the plugin is unable to synthesize the given high-level object.\n", + "The actual synthesis of high-level objects is performed by the\n", + "[HighLevelSynthesis](/api/qiskit/qiskit.transpiler.passes.HighLevelSynthesis)\n", + "transpiler pass.\n", + "\n", + "In addition to the `run` method, there are a number of property methods that need to be defined.\n", + "See [HighLevelSynthesisPlugin](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin) for documentation of all required properties.\n", + "\n", + "Let's define our HighLevelSynthesisPlugin subclass:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "3c0e59d4-85b0-4157-824b-b1f6220e83ad", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.synthesis import synth_clifford_bm\n", + "from qiskit.transpiler.passes.synthesis.plugin import HighLevelSynthesisPlugin\n", + "\n", + "\n", + "class MyCliffordSynthesisPlugin(HighLevelSynthesisPlugin):\n", + " def run(\n", + " self, high_level_object, coupling_map=None, target=None, qubits=None, **options\n", + " ) -> QuantumCircuit:\n", + " if high_level_object.num_qubits <= 3:\n", + " return synth_clifford_bm(high_level_object)\n", + " else:\n", + " return None" + ] + }, + { + "cell_type": "markdown", + "id": "1285dbfd-04ce-494b-8a01-a58040035dbd", + "metadata": {}, + "source": [ + "This plugin synthesizes objects of type [Clifford](/api/qiskit/qiskit.quantum_info.Clifford) that have\n", + "at most 3 qubits, using the `synth_clifford_bm` method.\n", + "\n", + "Now, we expose the plugin by adding an `entry-points` table in `pyproject.toml` under the `qiskit.synthesis` namespace.\n", + "To expose this plugin in a package called `my_qiskit_plugin`, we would add the following in `pyproject.toml`:\n", + "\n", + "```toml\n", + "[project.entry-points.\"qiskit.synthesis\"]\n", + "\"clifford.special\" = \"my_qiskit_plugin.module.plugin:MyCliffordSynthesisPlugin\"\n", + "```\n", + "\n", + "The `name` consists of two parts separated by a dot (`.`):\n", + "- The name of the type of [Operation](/api/qiskit/qiskit.circuit.Operation) that the plugin synthesizes (in this case, `clifford`). Note that this string corresponds to the [`name`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the Operation class, and not the name of the class itself.\n", + "- The name of the plugin (in this case, `special`)." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "documentation", + "language": "python", + "name": "documentation" + }, + "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.10.12" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb new file mode 100644 index 00000000000..20822660a9b --- /dev/null +++ b/docs/transpile/transpiler-plugins.ipynb @@ -0,0 +1,299 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Transpiler plugins\n", + "\n", + "To facilitate the development and reuse of custom transpilation code by the wider community of Qiskit users, Qiskit 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](/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](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin) provides extended functionality for unitary gate synthesis.\n", + "- A [high-level synthesis plugin](/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](/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." + ] + }, + { + "cell_type": "markdown", + "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.\n", + "\n", + "### List available transpiler stage plugins\n", + "\n", + "Use the [list_stage_plugins](/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." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['default', 'dense', 'noise_adaptive', '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, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['basic', 'lookahead', 'none', 'sabre', 'stochastic']" + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "list_stage_plugins(\"routing\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + " If `qiskit-toqm` were installed, then `toqm` would appear in the list of `routing` plugins." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### List available unitary synthesis plugins\n", + "\n", + "Use the [unitary_synthesis_plugin_names](api/qiskit/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names) function." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['aqc', 'default', '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", + "metadata": {}, + "source": [ + "### List available high-level sythesis plugins\n", + "\n", + "Use the [high_level_synthesis_plugin_names](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`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the [Operation](/api/qiskit/qiskit.circuit.Operation) class representing the type of object being synthesized." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [ + { + "ename": "ImportError", + "evalue": "cannot import name 'high_level_synthesis_plugin_names' from 'qiskit.transpiler.passes.synthesis' (/home/kjs/.local/share/virtualenvs/documentation--fuetTj0/lib/python3.10/site-packages/qiskit/transpiler/passes/synthesis/__init__.py)", + "output_type": "error", + "traceback": [ + "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", + "\u001b[0;31mImportError\u001b[0m Traceback (most recent call last)", + "Cell \u001b[0;32mIn[4], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[38;5;28;01mfrom\u001b[39;00m \u001b[38;5;21;01mqiskit\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mtranspiler\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mpasses\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01msynthesis\u001b[39;00m \u001b[38;5;28;01mimport\u001b[39;00m high_level_synthesis_plugin_names\n\u001b[1;32m 3\u001b[0m high_level_synthesis_plugin_names(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mclifford\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n", + "\u001b[0;31mImportError\u001b[0m: cannot import name 'high_level_synthesis_plugin_names' from 'qiskit.transpiler.passes.synthesis' (/home/kjs/.local/share/virtualenvs/documentation--fuetTj0/lib/python3.10/site-packages/qiskit/transpiler/passes/synthesis/__init__.py)" + ] + } + ], + "source": [ + "from qiskit.transpiler.passes.synthesis import high_level_synthesis_plugin_names\n", + "\n", + "high_level_synthesis_plugin_names(\"clifford\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Use a plugin\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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or [`transpile`](/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 `sabre` routing plugin, we would specify `sabre` for the `routing_method` argument:" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager\n", + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.backend(\"ibm_brisbane\")\n", + "\n", + "pass_manager = generate_preset_pass_manager(\n", + " optimization_level=3, backend=backend, routing_method=\"sabre\"\n", + ")" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile):" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "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(basis_gates=[\"cz\", \"id\", \"rz\", \"sx\", \"x\"]),\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "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. For example, see [SolovayKitaevSynthesis](/api/qiskit/qiskit.transpiler.passes.SolovayKitaevSynthesis) for documentation of the options available for the `sk` unitary synthesis method." + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Use a high-level synthesis plugin\n", + "\n", + "First, create an [HLSConfig](/api/qiskit/qiskit.transpiler.passes.HLSConfig) to\n", + "store the names of the plugins to use for various high-level objects. For example:" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [ + { + "ename": "ImportError", + "evalue": "cannot import name 'HLSConfig' from 'qiskit.transpiler.passes' (/home/kjs/.local/share/virtualenvs/documentation--fuetTj0/lib/python3.10/site-packages/qiskit/transpiler/passes/__init__.py)", + "output_type": "error", + "traceback": [ + "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", + "\u001b[0;31mImportError\u001b[0m Traceback (most recent call last)", + "Cell \u001b[0;32mIn[7], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[38;5;28;01mfrom\u001b[39;00m \u001b[38;5;21;01mqiskit\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mtranspiler\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mpasses\u001b[39;00m \u001b[38;5;28;01mimport\u001b[39;00m HLSConfig\n\u001b[1;32m 3\u001b[0m hls_config \u001b[38;5;241m=\u001b[39m HLSConfig(clifford\u001b[38;5;241m=\u001b[39m[\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mlayers\u001b[39m\u001b[38;5;124m\"\u001b[39m], linear_function\u001b[38;5;241m=\u001b[39m[\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mpmh\u001b[39m\u001b[38;5;124m\"\u001b[39m])\n", + "\u001b[0;31mImportError\u001b[0m: cannot import name 'HLSConfig' from 'qiskit.transpiler.passes' (/home/kjs/.local/share/virtualenvs/documentation--fuetTj0/lib/python3.10/site-packages/qiskit/transpiler/passes/__init__.py)" + ] + } + ], + "source": [ + "from qiskit.transpiler.passes import HLSConfig\n", + "\n", + "hls_config = HLSConfig(clifford=[\"layers\"], linear_function=[\"pmh\"])" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This code cell creates a high-level synthesis configuration that uses the `layers` plugin\n", + "for synthesizing [Clifford](/api/qiskit/qiskit.quantum_info.Clifford#clifford) objects and the `pmh` plugin for synthesizing\n", + "[LinearFunction](/api/qiskit/qiskit.circuit.library.LinearFunction#linearfunction) objects. The names of the keyword arguments correspond to the \n", + "[`name`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the [Operation](/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). 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.\n", + "\n", + "Once you have created the `HLSConfig` object, pass it as the\n", + "`hls_config` argument to [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile):" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [ + { + "ename": "NameError", + "evalue": "name 'hls_config' is not defined", + "output_type": "error", + "traceback": [ + "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", + "\u001b[0;31mNameError\u001b[0m Traceback (most recent call last)", + "Cell \u001b[0;32mIn[8], line 2\u001b[0m\n\u001b[1;32m 1\u001b[0m pass_manager \u001b[38;5;241m=\u001b[39m generate_preset_pass_manager(\n\u001b[0;32m----> 2\u001b[0m optimization_level\u001b[38;5;241m=\u001b[39m\u001b[38;5;241m3\u001b[39m, backend\u001b[38;5;241m=\u001b[39mbackend, hls_config\u001b[38;5;241m=\u001b[39m\u001b[43mhls_config\u001b[49m\n\u001b[1;32m 3\u001b[0m )\n", + "\u001b[0;31mNameError\u001b[0m: name 'hls_config' is not defined" + ] + } + ], + "source": [ + "pass_manager = generate_preset_pass_manager(\n", + " optimization_level=3, backend=backend, hls_config=hls_config\n", + ")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "documentation", + "language": "python", + "name": "documentation" + }, + "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.10.12" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} From 43122599cc92532534c6b5db28f89db645d3ab07 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Wed, 7 Feb 2024 17:00:03 -0500 Subject: [PATCH 02/25] add notebook metadata --- docs/transpile/create-a-transpiler-plugin.ipynb | 2 ++ docs/transpile/transpiler-plugins.ipynb | 6 ++++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index 2f31c07567e..413d83c85f4 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -286,6 +286,8 @@ } ], "metadata": { + "title": "Create a transpiler plugin", + "description": "How to create a Qiskit transpiler plugin.", "kernelspec": { "display_name": "documentation", "language": "python", diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index 20822660a9b..3830a5c0ae3 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -276,10 +276,12 @@ } ], "metadata": { + "title": "Transpiler plugins", + "description": "How to use transpiler plugins in Qiskit.", "kernelspec": { - "display_name": "documentation", + "display_name": "documentation--fuetTj0", "language": "python", - "name": "documentation" + "name": "python3" }, "language_info": { "codemirror_mode": { From 376d90f4eff7362507f98ef79bb3a8e0ac8acf94 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Thu, 8 Feb 2024 14:50:20 -0500 Subject: [PATCH 03/25] address comments --- docs/transpile/transpiler-plugins.ipynb | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index 3830a5c0ae3..8467991aa4e 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -23,7 +23,7 @@ "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.\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/), and you can find them on [this page](https://qiskit.github.io/ecosystem/#transpiler_plugin).\n", "\n", "### List available transpiler stage plugins\n", "\n", @@ -150,7 +150,7 @@ "\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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or [`transpile`](/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 `sabre` routing plugin, we would specify `sabre` for the `routing_method` argument:" + "To use a transpiler stage plugin, specify its name with the appropriate argument to [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or [`transpile`](/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 `dense` routing plugin, we would specify `dense` for the `routing_method` argument:" ] }, { @@ -166,7 +166,7 @@ "backend = service.backend(\"ibm_brisbane\")\n", "\n", "pass_manager = generate_preset_pass_manager(\n", - " optimization_level=3, backend=backend, routing_method=\"sabre\"\n", + " optimization_level=3, backend=backend, routing_method=\"stochastic\"\n", ")" ] }, @@ -245,7 +245,7 @@ "[`name`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the [Operation](/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). 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.\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.\n", "\n", "Once you have created the `HLSConfig` object, pass it as the\n", "`hls_config` argument to [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile):" @@ -276,7 +276,6 @@ } ], "metadata": { - "title": "Transpiler plugins", "description": "How to use transpiler plugins in Qiskit.", "kernelspec": { "display_name": "documentation--fuetTj0", @@ -294,7 +293,8 @@ "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.12" - } + }, + "title": "Transpiler plugins" }, "nbformat": 4, "nbformat_minor": 4 From fcde5106f852cec54cb6ab37962dc82dc1b84223 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 12 Feb 2024 16:45:58 -0500 Subject: [PATCH 04/25] run notebooks using qiskit 1.0.0rc1 --- .../create-a-transpiler-plugin.ipynb | 8 ++-- docs/transpile/transpiler-plugins.ipynb | 47 +++++-------------- 2 files changed, 15 insertions(+), 40 deletions(-) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index 413d83c85f4..e62a9b544b7 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -286,12 +286,11 @@ } ], "metadata": { - "title": "Create a transpiler plugin", "description": "How to create a Qiskit transpiler plugin.", "kernelspec": { - "display_name": "documentation", + "display_name": "documentation--fuetTj0", "language": "python", - "name": "documentation" + "name": "python3" }, "language_info": { "codemirror_mode": { @@ -304,7 +303,8 @@ "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.12" - } + }, + "title": "Create a transpiler plugin" }, "nbformat": 4, "nbformat_minor": 5 diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index 8467991aa4e..c3a481b1ebd 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -38,7 +38,7 @@ { "data": { "text/plain": [ - "['default', 'dense', 'noise_adaptive', 'sabre', 'trivial']" + "['default', 'dense', 'sabre', 'trivial']" ] }, "execution_count": 1, @@ -125,15 +125,14 @@ "metadata": {}, "outputs": [ { - "ename": "ImportError", - "evalue": "cannot import name 'high_level_synthesis_plugin_names' from 'qiskit.transpiler.passes.synthesis' (/home/kjs/.local/share/virtualenvs/documentation--fuetTj0/lib/python3.10/site-packages/qiskit/transpiler/passes/synthesis/__init__.py)", - "output_type": "error", - "traceback": [ - "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", - "\u001b[0;31mImportError\u001b[0m Traceback (most recent call last)", - "Cell \u001b[0;32mIn[4], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[38;5;28;01mfrom\u001b[39;00m \u001b[38;5;21;01mqiskit\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mtranspiler\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mpasses\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01msynthesis\u001b[39;00m \u001b[38;5;28;01mimport\u001b[39;00m high_level_synthesis_plugin_names\n\u001b[1;32m 3\u001b[0m high_level_synthesis_plugin_names(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mclifford\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n", - "\u001b[0;31mImportError\u001b[0m: cannot import name 'high_level_synthesis_plugin_names' from 'qiskit.transpiler.passes.synthesis' (/home/kjs/.local/share/virtualenvs/documentation--fuetTj0/lib/python3.10/site-packages/qiskit/transpiler/passes/synthesis/__init__.py)" - ] + "data": { + "text/plain": [ + "['ag', 'bm', 'default', 'greedy', 'layers', 'lnn']" + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" } ], "source": [ @@ -216,19 +215,7 @@ "cell_type": "code", "execution_count": 7, "metadata": {}, - "outputs": [ - { - "ename": "ImportError", - "evalue": "cannot import name 'HLSConfig' from 'qiskit.transpiler.passes' (/home/kjs/.local/share/virtualenvs/documentation--fuetTj0/lib/python3.10/site-packages/qiskit/transpiler/passes/__init__.py)", - "output_type": "error", - "traceback": [ - "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", - "\u001b[0;31mImportError\u001b[0m Traceback (most recent call last)", - "Cell \u001b[0;32mIn[7], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[38;5;28;01mfrom\u001b[39;00m \u001b[38;5;21;01mqiskit\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mtranspiler\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mpasses\u001b[39;00m \u001b[38;5;28;01mimport\u001b[39;00m HLSConfig\n\u001b[1;32m 3\u001b[0m hls_config \u001b[38;5;241m=\u001b[39m HLSConfig(clifford\u001b[38;5;241m=\u001b[39m[\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mlayers\u001b[39m\u001b[38;5;124m\"\u001b[39m], linear_function\u001b[38;5;241m=\u001b[39m[\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mpmh\u001b[39m\u001b[38;5;124m\"\u001b[39m])\n", - "\u001b[0;31mImportError\u001b[0m: cannot import name 'HLSConfig' from 'qiskit.transpiler.passes' (/home/kjs/.local/share/virtualenvs/documentation--fuetTj0/lib/python3.10/site-packages/qiskit/transpiler/passes/__init__.py)" - ] - } - ], + "outputs": [], "source": [ "from qiskit.transpiler.passes import HLSConfig\n", "\n", @@ -255,19 +242,7 @@ "cell_type": "code", "execution_count": 8, "metadata": {}, - "outputs": [ - { - "ename": "NameError", - "evalue": "name 'hls_config' is not defined", - "output_type": "error", - "traceback": [ - "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", - "\u001b[0;31mNameError\u001b[0m Traceback (most recent call last)", - "Cell \u001b[0;32mIn[8], line 2\u001b[0m\n\u001b[1;32m 1\u001b[0m pass_manager \u001b[38;5;241m=\u001b[39m generate_preset_pass_manager(\n\u001b[0;32m----> 2\u001b[0m optimization_level\u001b[38;5;241m=\u001b[39m\u001b[38;5;241m3\u001b[39m, backend\u001b[38;5;241m=\u001b[39mbackend, hls_config\u001b[38;5;241m=\u001b[39m\u001b[43mhls_config\u001b[49m\n\u001b[1;32m 3\u001b[0m )\n", - "\u001b[0;31mNameError\u001b[0m: name 'hls_config' is not defined" - ] - } - ], + "outputs": [], "source": [ "pass_manager = generate_preset_pass_manager(\n", " optimization_level=3, backend=backend, hls_config=hls_config\n", From 073e7a19cb9a880e1c3f1c68d13eee0f4ad24770 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 12 Feb 2024 16:52:23 -0500 Subject: [PATCH 05/25] link to docs on setup.cfg and setup.py --- docs/transpile/create-a-transpiler-plugin.ipynb | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index e62a9b544b7..74e5cdaeb9a 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -24,7 +24,7 @@ "\n", "There is no limit to the number of plugins a single package can define, but each plugin must have a unique name. The name `default` is used by Qiskit itself and can't be used in a plugin.\n", "\n", - "In the next sections, we show examples of these steps for the different types of plugins. In these examples, we assume that we are creating a Python package called `my_qiskit_plugin`. For information on creating Python packages, you can check out [this tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/) from the Python website." + "In the next sections, we show examples of these steps for the different types of plugins. In these examples, we assume that we are creating a Python package called `my_qiskit_plugin`, and that we are using a `pyproject.toml` file to store our project metadata. For information on creating Python packages, you can check out [this tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/) from the Python website." ] }, { @@ -88,6 +88,14 @@ "```" ] }, + { + "cell_type": "markdown", + "id": "5c5edd30", + "metadata": {}, + "source": [ + "If your project uses `setup.cfg` or `setup.py` instead of `pyproject.toml`, see the [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) for how to adapt these lines for your situation." + ] + }, { "cell_type": "markdown", "id": "fe3a1a6c-5aa2-4f00-9bdd-45598717be1d", @@ -199,6 +207,8 @@ "\"special\" = \"my_qiskit_plugin.module.plugin:MyUnitarySynthesisPlugin\"\n", "```\n", "\n", + "As before, if your project uses `setup.cfg` or `setup.py` instead of `pyproject.toml`, see the [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) for how to adapt these lines for your situation.\n", + "\n", "To accommodate unitary synthesis plugins that expose multiple options,\n", "the plugin interface has an option for users to provide a free-form\n", "configuration dictionary. This will be passed to the `run` method\n", @@ -281,7 +291,9 @@ "\n", "The `name` consists of two parts separated by a dot (`.`):\n", "- The name of the type of [Operation](/api/qiskit/qiskit.circuit.Operation) that the plugin synthesizes (in this case, `clifford`). Note that this string corresponds to the [`name`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the Operation class, and not the name of the class itself.\n", - "- The name of the plugin (in this case, `special`)." + "- The name of the plugin (in this case, `special`).\n", + "\n", + "As before, if your project uses `setup.cfg` or `setup.py` instead of `pyproject.toml`, see the [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) for how to adapt these lines for your situation." ] } ], From e23417d72b0dfedb753b4c6b4b1a01e0675d32c2 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 12 Feb 2024 20:39:14 -0500 Subject: [PATCH 06/25] add to toc --- docs/transpile/_toc.json | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/transpile/_toc.json b/docs/transpile/_toc.json index d2f354d5736..2d5f60f35b4 100644 --- a/docs/transpile/_toc.json +++ b/docs/transpile/_toc.json @@ -22,6 +22,14 @@ "title": "Write a custom transpiler pass", "url": "/transpile/custom-transpiler-pass" }, + { + "title": "Transpiler plugins", + "url": "/transpile/transpiler-plugins" + }, + { + "title": "Create a transpiler plugin", + "url": "/transpile/create-a-transpiler-plugin" + }, { "title": "Use the transpile function", "children": [ From b0655cc316b90b97270474a04c12eb04162ded02 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 12 Feb 2024 20:50:48 -0500 Subject: [PATCH 07/25] add instructions for checking plugin detected by qiskit --- .../create-a-transpiler-plugin.ipynb | 113 ++++++++++++++++-- 1 file changed, 106 insertions(+), 7 deletions(-) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index 74e5cdaeb9a..2d8d27be3c3 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -84,7 +84,7 @@ "\n", "```toml\n", "[project.entry-points.\"qiskit.transpiler.layout\"]\n", - "\"vf2\" = \"my_qiskit_plugin.module.plugin:MyLayoutPlugin\"\n", + "\"my_layout\" = \"my_qiskit_plugin.module.plugin:MyLayoutPlugin\"\n", "```" ] }, @@ -93,7 +93,40 @@ "id": "5c5edd30", "metadata": {}, "source": [ - "If your project uses `setup.cfg` or `setup.py` instead of `pyproject.toml`, see the [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) for how to adapt these lines for your situation." + "If your project uses `setup.cfg` or `setup.py` instead of `pyproject.toml`, see the [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) for how to adapt these lines for your situation.\n", + "\n", + "To check that your plugin is successfully detected by Qiskit, install your plugin package and follow the instructions at [Transpiler plugins](transpiler-plugins#list-available-transpiler-stage-plugins) for listing installed plugins, and ensure that your plugin appears in the list:" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "04b07ec3", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['default', 'dense', 'sabre', 'trivial']" + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qiskit.transpiler.preset_passmanagers.plugin import list_stage_plugins\n", + " \n", + "list_stage_plugins(\"layout\")" + ] + }, + { + "cell_type": "markdown", + "id": "d62c4edb", + "metadata": {}, + "source": [ + "If our example plugin were installed, then the name `my_layout` would appear in this list." ] }, { @@ -118,7 +151,7 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 3, "id": "6bc1011c-b15d-4210-973b-d9d530ece880", "metadata": {}, "outputs": [], @@ -204,11 +237,44 @@ "\n", "```toml\n", "[project.entry-points.\"qiskit.unitary_synthesis\"]\n", - "\"special\" = \"my_qiskit_plugin.module.plugin:MyUnitarySynthesisPlugin\"\n", + "\"my_unitary_synthesis\" = \"my_qiskit_plugin.module.plugin:MyUnitarySynthesisPlugin\"\n", "```\n", "\n", "As before, if your project uses `setup.cfg` or `setup.py` instead of `pyproject.toml`, see the [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) for how to adapt these lines for your situation.\n", "\n", + "To check that your plugin is successfully detected by Qiskit, install your plugin package and follow the instructions at [Transpiler plugins](transpiler-plugins#list-available-unitary-synthesis-plugins) for listing installed plugins, and ensure that your plugin appears in the list:" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "31bfaf30", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['aqc', 'default', 'sk']" + ] + }, + "execution_count": 4, + "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": "4faf2d51", + "metadata": {}, + "source": [ + "If our example plugin were installed, then the name `my_unitary_synthesis` would appear in this list.\n", + "\n", "To accommodate unitary synthesis plugins that expose multiple options,\n", "the plugin interface has an option for users to provide a free-form\n", "configuration dictionary. This will be passed to the `run` method\n", @@ -254,7 +320,7 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": 5, "id": "3c0e59d4-85b0-4157-824b-b1f6220e83ad", "metadata": {}, "outputs": [], @@ -286,14 +352,47 @@ "\n", "```toml\n", "[project.entry-points.\"qiskit.synthesis\"]\n", - "\"clifford.special\" = \"my_qiskit_plugin.module.plugin:MyCliffordSynthesisPlugin\"\n", + "\"clifford.my_clifford_synthesis\" = \"my_qiskit_plugin.module.plugin:MyCliffordSynthesisPlugin\"\n", "```\n", "\n", "The `name` consists of two parts separated by a dot (`.`):\n", "- The name of the type of [Operation](/api/qiskit/qiskit.circuit.Operation) that the plugin synthesizes (in this case, `clifford`). Note that this string corresponds to the [`name`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the Operation class, and not the name of the class itself.\n", "- The name of the plugin (in this case, `special`).\n", "\n", - "As before, if your project uses `setup.cfg` or `setup.py` instead of `pyproject.toml`, see the [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) for how to adapt these lines for your situation." + "As before, if your project uses `setup.cfg` or `setup.py` instead of `pyproject.toml`, see the [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) for how to adapt these lines for your situation.\n", + "\n", + "To check that your plugin is successfully detected by Qiskit, install your plugin package and follow the instructions at [Transpiler plugins](transpiler-plugins#list-available-high-level-sythesis-plugins) for listing installed plugins, and ensure that your plugin appears in the list:" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "fbe1f265", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['ag', 'bm', 'default', 'greedy', 'layers', 'lnn']" + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qiskit.transpiler.passes.synthesis import high_level_synthesis_plugin_names\n", + " \n", + "high_level_synthesis_plugin_names(\"clifford\")" + ] + }, + { + "cell_type": "markdown", + "id": "f1e86f49", + "metadata": {}, + "source": [ + "If our example plugin were installed, then the name `my_clifford_synthesis` would appear in this list." ] } ], From bc667cf63bd76c02d09095c0ba399166787d2105 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Tue, 13 Feb 2024 14:32:01 -0500 Subject: [PATCH 08/25] add table of reserved names --- docs/transpile/create-a-transpiler-plugin.ipynb | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index 2d8d27be3c3..cb32bca6e84 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -22,7 +22,18 @@ " - [HighLevelSynthesisPlugin](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin) for a high-level synthesis plugin.\n", "2. Expose the class as a [setuptools entry point](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) in the package metadata, typically by adding an `entry-points` table in `pyproject.toml`.\n", "\n", - "There is no limit to the number of plugins a single package can define, but each plugin must have a unique name. The name `default` is used by Qiskit itself and can't be used in a plugin.\n", + "There is no limit to the number of plugins a single package can define, but each plugin must have a unique name. Qiskit itself includes a number of plugins, whose names are also reserved. The reserved names are:\n", + "\n", + "- Transpiler stage plugins: See [this table](/api/qiskit/transpiler_plugins#plugin-stages).\n", + "- Unitary synthesis plugins: `default`, `aqc`, `sk`\n", + "- High-level synthesis plugins:\n", + "\n", + "| Operation class | Operation name | Reserved names |\n", + "| --- | --- | --- |\n", + "| [Clifford](/api/qiskit/qiskit.quantum_info.Clifford#clifford) | `clifford` | `default`, `ag`, `bm`, `greedy`, `layers`, `lnn` |\n", + "| [LinearFunction](/api/qiskit/qiskit.circuit.library.LinearFunction#linearfunction) | `linear_function` | `default`, `kms`, `pmh` |\n", + "| [PermutationGate](/api/qiskit/qiskit.circuit.library.PermutationGate#permutationgate) | `permutation` | `default`, `kms`, `basic`, `acg`, `token_swapper` |\n", + "\n", "\n", "In the next sections, we show examples of these steps for the different types of plugins. In these examples, we assume that we are creating a Python package called `my_qiskit_plugin`, and that we are using a `pyproject.toml` file to store our project metadata. For information on creating Python packages, you can check out [this tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/) from the Python website." ] @@ -399,9 +410,9 @@ "metadata": { "description": "How to create a Qiskit transpiler plugin.", "kernelspec": { - "display_name": "documentation--fuetTj0", + "display_name": "documentation", "language": "python", - "name": "python3" + "name": "documentation" }, "language_info": { "codemirror_mode": { From 2537de013b677829ea8a36db9338ac3d9cc2ea38 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Thu, 15 Feb 2024 15:23:42 -0500 Subject: [PATCH 09/25] fix typo --- docs/transpile/transpiler-plugins.ipynb | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index c3a481b1ebd..60ea198be38 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -149,7 +149,7 @@ "\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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or [`transpile`](/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 `dense` routing plugin, we would specify `dense` for the `routing_method` argument:" + "To use a transpiler stage plugin, specify its name with the appropriate argument to [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or [`transpile`](/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 `stochastic` routing plugin, we would specify `stochastic` for the `routing_method` argument:" ] }, { @@ -253,9 +253,9 @@ "metadata": { "description": "How to use transpiler plugins in Qiskit.", "kernelspec": { - "display_name": "documentation--fuetTj0", + "display_name": "documentation", "language": "python", - "name": "python3" + "name": "documentation" }, "language_info": { "codemirror_mode": { From d8d2b5d3831c39a29f0be378ff5f1119d20d5b41 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Thu, 15 Feb 2024 15:39:01 -0500 Subject: [PATCH 10/25] unitary matrix is numpy array --- docs/transpile/create-a-transpiler-plugin.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index cb32bca6e84..5c62d62758a 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -11,7 +11,7 @@ "\n", "Before you create a transpiler plugin, you need to decide what kind of plugin is appropriate for your situation. There are three kinds of transpiler plugins:\n", "- [**Transpiler stage plugin**](/api/qiskit/transpiler_plugins). Choose this if you are defining a pass manager that can be substituted for one of the [6 stages](transpiler-stages) of a preset staged pass manager.\n", - "- [**Unitary synthesis plugin**](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin). Choose this if your transpilation code takes as input a unitary matrix and outputs a description of a quantum circuit implementing that unitary.\n", + "- [**Unitary synthesis plugin**](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin). Choose this if your transpilation code takes as input a unitary matrix (represented as a Numpy array) and outputs a description of a quantum circuit implementing that unitary.\n", "- [**High-level synthesis plugin**](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin). Choose this if your transpilation code takes as input a \"high-level object\" such as a Clifford operator or a linear function and outputs a description of a quantum circuit implementing that high-level object. High-level objects are represented by subclasses of the [Operation](/api/qiskit/qiskit.circuit.Operation) class.\n", "\n", "Once you've determined which kind of plugin to create, follow these steps to create the plugin:\n", From 636662e05036cfb764568ff9d16d90a4cad557d4 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 19 Feb 2024 11:41:22 -0500 Subject: [PATCH 11/25] add tabs --- .../create-a-transpiler-plugin.ipynb | 126 ++++++++++++++---- 1 file changed, 102 insertions(+), 24 deletions(-) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index 5c62d62758a..66abbb4aea7 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -20,7 +20,7 @@ " - [PassManagerStagePlugin](/api/qiskit/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin) for a transpiler stage plugin,\n", " - [UnitarySynthesisPlugin](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin) for a unitary synthesis plugin, and\n", " - [HighLevelSynthesisPlugin](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin) for a high-level synthesis plugin.\n", - "2. Expose the class as a [setuptools entry point](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) in the package metadata, typically by adding an `entry-points` table in `pyproject.toml`.\n", + "2. Expose the class as a [setuptools entry point](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) in the package metadata, typically by editing the `pyproject.toml`, `setup.cfg`, or `setup.py` file for your Python package.\n", "\n", "There is no limit to the number of plugins a single package can define, but each plugin must have a unique name. Qiskit itself includes a number of plugins, whose names are also reserved. The reserved names are:\n", "\n", @@ -35,7 +35,7 @@ "| [PermutationGate](/api/qiskit/qiskit.circuit.library.PermutationGate#permutationgate) | `permutation` | `default`, `kms`, `basic`, `acg`, `token_swapper` |\n", "\n", "\n", - "In the next sections, we show examples of these steps for the different types of plugins. In these examples, we assume that we are creating a Python package called `my_qiskit_plugin`, and that we are using a `pyproject.toml` file to store our project metadata. For information on creating Python packages, you can check out [this tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/) from the Python website." + "In the next sections, we show examples of these steps for the different types of plugins. In these examples, we assume that we are creating a Python package called `my_qiskit_plugin`. For information on creating Python packages, you can check out [this tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/) from the Python website." ] }, { @@ -90,13 +90,39 @@ "id": "d7666879-14bc-479c-a91b-56a800897073", "metadata": {}, "source": [ - "Now, we expose the plugin by adding an `entry-points` table in `pyproject.toml` under the appropriate namespace. See the [table of transpiler plugin stages](/api/qiskit/transpiler_plugins#stage-table) for the entry points and expectations for each stage.\n", - "To expose this plugin in a package called `my_qiskit_plugin`, we would add the following in `pyproject.toml`:\n", - "\n", - "```toml\n", - "[project.entry-points.\"qiskit.transpiler.layout\"]\n", - "\"my_layout\" = \"my_qiskit_plugin.module.plugin:MyLayoutPlugin\"\n", - "```" + "Now, we expose the plugin by adding an entry point in our Python package metadata.\n", + "Here, we assume that the class we defined is exposed in a module called `my_qiskit_plugin`, for example by being imported in the `__init__.py` file of the `my_qiskit_plugin` module.\n", + "We edit the `pyproject.toml`, `setup.cfg`, or `setup.py` file of our package:\n", + "\n", + "\n", + " \n", + " ```toml\n", + " [project.entry-points.\"qiskit.transpiler.layout\"]\n", + " \"my_layout\" = \"my_qiskit_plugin:MyLayoutPlugin\"\n", + " ```\n", + " \n", + " \n", + " ```ini\n", + " [options.entry_points]\n", + " qiskit.transpiler.layout =\n", + " my_layout = my_qiskit_plugin:MyLayoutPlugin\n", + " ```\n", + " \n", + " \n", + " ```python\n", + " from setuptools import setup\n", + "\n", + " setup(\n", + " # ...,\n", + " entry_points={\n", + " 'qiskit.transpiler.layout': [\n", + " 'my_layout = my_qiskit_plugin:MyLayoutPlugin',\n", + " ]\n", + " }\n", + " )\n", + " ```\n", + " \n", + "" ] }, { @@ -104,7 +130,7 @@ "id": "5c5edd30", "metadata": {}, "source": [ - "If your project uses `setup.cfg` or `setup.py` instead of `pyproject.toml`, see the [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) for how to adapt these lines for your situation.\n", + "See the [table of transpiler plugin stages](/api/qiskit/transpiler_plugins#stage-table) for the entry points and expectations for each transpiler stage.\n", "\n", "To check that your plugin is successfully detected by Qiskit, install your plugin package and follow the instructions at [Transpiler plugins](transpiler-plugins#list-available-transpiler-stage-plugins) for listing installed plugins, and ensure that your plugin appears in the list:" ] @@ -243,13 +269,39 @@ "All methods prefixed with `supports_` are reserved on a `UnitarySynthesisPlugin` derived class as part of the interface. You should not define any custom `supports_*` methods on a subclass that are not defined in the abstract class.\n", "\n", "\n", - "Now, we expose the plugin by adding an `entry-points` table in `pyproject.toml` under the `qiskit.unitary_synthesis` namespace.\n", - "To expose this plugin in a package called `my_qiskit_plugin`, we would add the following in `pyproject.toml`:\n", - "\n", - "```toml\n", - "[project.entry-points.\"qiskit.unitary_synthesis\"]\n", - "\"my_unitary_synthesis\" = \"my_qiskit_plugin.module.plugin:MyUnitarySynthesisPlugin\"\n", - "```\n", + "Now, we expose the plugin by adding an entry point in our Python package metadata.\n", + "Here, we assume that the class we defined is exposed in a module called `my_qiskit_plugin`, for example by being imported in the `__init__.py` file of the `my_qiskit_plugin` module.\n", + "We edit the `pyproject.toml`, `setup.cfg`, or `setup.py` file of our package:\n", + "\n", + "\n", + " \n", + " ```toml\n", + " [project.entry-points.\"qiskit.unitary_synthesis\"]\n", + " \"my_unitary_synthesis\" = \"my_qiskit_plugin:MyUnitarySynthesisPlugin\"\n", + " ```\n", + " \n", + " \n", + " ```ini\n", + " [options.entry_points]\n", + " qiskit.unitary_synthesis =\n", + " my_unitary_synthesis = my_qiskit_plugin:MyUnitarySynthesisPlugin\n", + " ```\n", + " \n", + " \n", + " ```python\n", + " from setuptools import setup\n", + "\n", + " setup(\n", + " # ...,\n", + " entry_points={\n", + " 'qiskit.unitary_synthesis': [\n", + " 'my_unitary_synthesis = my_qiskit_plugin:MyUnitarySynthesisPlugin',\n", + " ]\n", + " }\n", + " )\n", + " ```\n", + " \n", + "\n", "\n", "As before, if your project uses `setup.cfg` or `setup.py` instead of `pyproject.toml`, see the [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) for how to adapt these lines for your situation.\n", "\n", @@ -358,13 +410,39 @@ "This plugin synthesizes objects of type [Clifford](/api/qiskit/qiskit.quantum_info.Clifford) that have\n", "at most 3 qubits, using the `synth_clifford_bm` method.\n", "\n", - "Now, we expose the plugin by adding an `entry-points` table in `pyproject.toml` under the `qiskit.synthesis` namespace.\n", - "To expose this plugin in a package called `my_qiskit_plugin`, we would add the following in `pyproject.toml`:\n", - "\n", - "```toml\n", - "[project.entry-points.\"qiskit.synthesis\"]\n", - "\"clifford.my_clifford_synthesis\" = \"my_qiskit_plugin.module.plugin:MyCliffordSynthesisPlugin\"\n", - "```\n", + "Now, we expose the plugin by adding an entry point in our Python package metadata.\n", + "Here, we assume that the class we defined is exposed in a module called `my_qiskit_plugin`, for example by being imported in the `__init__.py` file of the `my_qiskit_plugin` module.\n", + "We edit the `pyproject.toml`, `setup.cfg`, or `setup.py` file of our package:\n", + "\n", + "\n", + " \n", + " ```toml\n", + " [project.entry-points.\"qiskit.synthesis\"]\n", + " \"clifford.my_clifford_synthesis\" = \"my_qiskit_plugin:MyCliffordSynthesisPlugin\"\n", + " ```\n", + " \n", + " \n", + " ```ini\n", + " [options.entry_points]\n", + " qiskit.synthesis =\n", + " clifford.my_clifford_synthesis = my_qiskit_plugin:MyCliffordSynthesisPlugin\n", + " ```\n", + " \n", + " \n", + " ```python\n", + " from setuptools import setup\n", + "\n", + " setup(\n", + " # ...,\n", + " entry_points={\n", + " 'qiskit.synthesis': [\n", + " 'clifford.my_clifford_synthesis = my_qiskit_plugin:MyCliffordSynthesisPlugin',\n", + " ]\n", + " }\n", + " )\n", + " ```\n", + " \n", + "\n", "\n", "The `name` consists of two parts separated by a dot (`.`):\n", "- The name of the type of [Operation](/api/qiskit/qiskit.circuit.Operation) that the plugin synthesizes (in this case, `clifford`). Note that this string corresponds to the [`name`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the Operation class, and not the name of the class itself.\n", From d8b48c86b3f53cf7dd519155be71e8269336dd1e Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 19 Feb 2024 11:47:39 -0500 Subject: [PATCH 12/25] add links --- docs/transpile/transpiler-plugins.ipynb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index 60ea198be38..a86e46e1817 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -197,7 +197,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "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. For example, see [SolovayKitaevSynthesis](/api/qiskit/qiskit.transpiler.passes.SolovayKitaevSynthesis) for documentation of the options available for the `sk` unitary synthesis method." + "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](/api/qiskit/transpiler_synthesis_plugins#unitary-synthesis-plugins-2) for links to the documentation of the built-in unitary synthesis plugins." ] }, { @@ -232,7 +232,7 @@ "[`name`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the [Operation](/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). 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.\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](/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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile):" From ee7ae0cf2762d45757d5e11f44a29e43ef7b0adc Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 19 Feb 2024 15:26:50 -0500 Subject: [PATCH 13/25] document which stages use synthesis methods --- docs/transpile/transpiler-plugins.ipynb | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index a86e46e1817..c80bf605248 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -197,6 +197,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ + "Unitary synthesis is used in the `init`, `translation`, and `optimization` stages of the staged pass manager returned by [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile).\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](/api/qiskit/transpiler_synthesis_plugins#unitary-synthesis-plugins-2) for links to the documentation of the built-in unitary synthesis plugins." ] }, @@ -231,7 +233,9 @@ "[LinearFunction](/api/qiskit/qiskit.circuit.library.LinearFunction#linearfunction) objects. The names of the keyword arguments correspond to the \n", "[`name`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the [Operation](/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). In addition to specifying\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](/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", @@ -248,6 +252,13 @@ " optimization_level=3, backend=backend, hls_config=hls_config\n", ")" ] + }, + { + "cell_type": "markdown", + "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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile)." + ] } ], "metadata": { From 1ecb164ca936ad54b3ebf4e58a65fe775d10cd64 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 19 Feb 2024 15:33:35 -0500 Subject: [PATCH 14/25] fix links --- docs/transpile/transpiler-plugins.ipynb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index c80bf605248..e9295d84b49 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -85,7 +85,7 @@ "source": [ "### List available unitary synthesis plugins\n", "\n", - "Use the [unitary_synthesis_plugin_names](api/qiskit/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names) function." + "Use the [unitary_synthesis_plugin_names](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names) function." ] }, { @@ -116,7 +116,7 @@ "source": [ "### List available high-level sythesis plugins\n", "\n", - "Use the [high_level_synthesis_plugin_names](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`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the [Operation](/api/qiskit/qiskit.circuit.Operation) class representing the type of object being synthesized." + "Use the [high_level_synthesis_plugin_names](/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`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the [Operation](/api/qiskit/qiskit.circuit.Operation) class representing the type of object being synthesized." ] }, { From f32a64f069ba39c04a690cfb839e70c897231e57 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 19 Feb 2024 15:50:00 -0500 Subject: [PATCH 15/25] run squeaky --- .../create-a-transpiler-plugin.ipynb | 12 ++++----- docs/transpile/transpiler-plugins.ipynb | 27 ++++++++++++++++--- 2 files changed, 29 insertions(+), 10 deletions(-) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index 66abbb4aea7..e9f3a3b87a2 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -154,7 +154,7 @@ ], "source": [ "from qiskit.transpiler.preset_passmanagers.plugin import list_stage_plugins\n", - " \n", + "\n", "list_stage_plugins(\"layout\")" ] }, @@ -327,7 +327,7 @@ ], "source": [ "from qiskit.transpiler.passes.synthesis import unitary_synthesis_plugin_names\n", - " \n", + "\n", "unitary_synthesis_plugin_names()" ] }, @@ -472,7 +472,7 @@ ], "source": [ "from qiskit.transpiler.passes.synthesis import high_level_synthesis_plugin_names\n", - " \n", + "\n", "high_level_synthesis_plugin_names(\"clifford\")" ] }, @@ -488,9 +488,9 @@ "metadata": { "description": "How to create a Qiskit transpiler plugin.", "kernelspec": { - "display_name": "documentation", + "display_name": "Python 3", "language": "python", - "name": "documentation" + "name": "python3" }, "language_info": { "codemirror_mode": { @@ -502,7 +502,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3" }, "title": "Create a transpiler plugin" }, diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index e9295d84b49..08a99d6dbd2 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "f9ba5f6b-49d3-4f23-b955-c263a5f96d0e", "metadata": {}, "source": [ "# Transpiler plugins\n", @@ -19,6 +20,7 @@ }, { "cell_type": "markdown", + "id": "a7cc4e17-fd60-4714-bc24-e97c9a6297c1", "metadata": {}, "source": [ "## List available plugins and install new ones\n", @@ -33,6 +35,7 @@ { "cell_type": "code", "execution_count": 1, + "id": "0f661ec6-bec1-4550-be33-c00c0f518021", "metadata": {}, "outputs": [ { @@ -55,6 +58,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "01cfd288-5fb5-45dd-a949-b4b1f33bcdeb", "metadata": {}, "outputs": [ { @@ -74,6 +78,7 @@ }, { "cell_type": "markdown", + "id": "482f2f1e-15dc-4106-883e-802e85ab556d", "metadata": {}, "source": [ " If `qiskit-toqm` were installed, then `toqm` would appear in the list of `routing` plugins." @@ -81,6 +86,7 @@ }, { "cell_type": "markdown", + "id": "845e0bbc-8a7a-4f50-8420-dccebf38169d", "metadata": {}, "source": [ "### List available unitary synthesis plugins\n", @@ -91,6 +97,7 @@ { "cell_type": "code", "execution_count": 3, + "id": "12810039-64e3-4389-be24-3f4ff1fc9642", "metadata": {}, "outputs": [ { @@ -112,6 +119,7 @@ }, { "cell_type": "markdown", + "id": "4fe8731d-f0ec-427e-9b4a-db2b71a2827f", "metadata": {}, "source": [ "### List available high-level sythesis plugins\n", @@ -122,6 +130,7 @@ { "cell_type": "code", "execution_count": 4, + "id": "f103fdd1-a9c3-4c0e-b0b7-d9d02561cba3", "metadata": {}, "outputs": [ { @@ -143,6 +152,7 @@ }, { "cell_type": "markdown", + "id": "6dd1c68f-af34-4887-b297-054b57f20f53", "metadata": {}, "source": [ "## Use a plugin\n", @@ -155,6 +165,7 @@ { "cell_type": "code", "execution_count": 5, + "id": "049378d6-20ad-4ef4-9f3c-58311a5944be", "metadata": {}, "outputs": [], "source": [ @@ -172,6 +183,7 @@ { "attachments": {}, "cell_type": "markdown", + "id": "b7dee496-07db-4423-8b5d-265c4100c1c1", "metadata": {}, "source": [ "### Use a unitary synthesis plugin\n", @@ -182,6 +194,7 @@ { "cell_type": "code", "execution_count": 6, + "id": "c6f563f0-173d-4937-8969-e08d250a1ddb", "metadata": {}, "outputs": [], "source": [ @@ -195,6 +208,7 @@ }, { "cell_type": "markdown", + "id": "3d8b84f4-3001-4857-a493-cbd6381a6507", "metadata": {}, "source": [ "Unitary synthesis is used in the `init`, `translation`, and `optimization` stages of the staged pass manager returned by [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile).\n", @@ -205,6 +219,7 @@ { "attachments": {}, "cell_type": "markdown", + "id": "b213f0d2-d969-4dca-9743-e14475f0e0c2", "metadata": {}, "source": [ "### Use a high-level synthesis plugin\n", @@ -216,6 +231,7 @@ { "cell_type": "code", "execution_count": 7, + "id": "a0a45258-d391-4ad2-9e3b-978ce266779f", "metadata": {}, "outputs": [], "source": [ @@ -226,11 +242,12 @@ }, { "cell_type": "markdown", + "id": "e9c39d39-9d42-4a0d-a044-fe0df9445b36", "metadata": {}, "source": [ "This code cell creates a high-level synthesis configuration that uses the `layers` plugin\n", "for synthesizing [Clifford](/api/qiskit/qiskit.quantum_info.Clifford#clifford) objects and the `pmh` plugin for synthesizing\n", - "[LinearFunction](/api/qiskit/qiskit.circuit.library.LinearFunction#linearfunction) objects. The names of the keyword arguments correspond to the \n", + "[LinearFunction](/api/qiskit/qiskit.circuit.library.LinearFunction#linearfunction) objects. The names of the keyword arguments correspond to the\n", "[`name`](/api/qiskit/qiskit.circuit.Operation#name) attribute of the [Operation](/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", @@ -245,6 +262,7 @@ { "cell_type": "code", "execution_count": 8, + "id": "c0eb2d77-d144-4946-960f-49ed08ba517d", "metadata": {}, "outputs": [], "source": [ @@ -255,6 +273,7 @@ }, { "cell_type": "markdown", + "id": "9ef44cf9-fc5b-4beb-af4c-db368c90e312", "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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile)." @@ -264,9 +283,9 @@ "metadata": { "description": "How to use transpiler plugins in Qiskit.", "kernelspec": { - "display_name": "documentation", + "display_name": "Python 3", "language": "python", - "name": "documentation" + "name": "python3" }, "language_info": { "codemirror_mode": { @@ -278,7 +297,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3" }, "title": "Transpiler plugins" }, From c3f9221dbe337abef9c2262ce2435f0c8667af44 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Tue, 20 Feb 2024 10:53:54 -0500 Subject: [PATCH 16/25] add HighLevelSynthesisPluginManager().plugins.names() --- docs/transpile/transpiler-plugins.ipynb | 82 +++++++++++++++++++------ 1 file changed, 63 insertions(+), 19 deletions(-) diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index 08a99d6dbd2..e0145bc22d3 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "f9ba5f6b-49d3-4f23-b955-c263a5f96d0e", + "id": "5aec3ebc-57f6-4472-9dfe-fc8aac585dd9", "metadata": {}, "source": [ "# Transpiler plugins\n", @@ -20,7 +20,7 @@ }, { "cell_type": "markdown", - "id": "a7cc4e17-fd60-4714-bc24-e97c9a6297c1", + "id": "f9c4440b-5e9b-44e3-9228-529ea3b34f48", "metadata": {}, "source": [ "## List available plugins and install new ones\n", @@ -35,7 +35,7 @@ { "cell_type": "code", "execution_count": 1, - "id": "0f661ec6-bec1-4550-be33-c00c0f518021", + "id": "1a3c398e-b48d-4679-bfde-a3773b379b3e", "metadata": {}, "outputs": [ { @@ -58,7 +58,7 @@ { "cell_type": "code", "execution_count": 2, - "id": "01cfd288-5fb5-45dd-a949-b4b1f33bcdeb", + "id": "fa2396d9-5c2f-46d7-98e2-5f5295e99853", "metadata": {}, "outputs": [ { @@ -78,7 +78,7 @@ }, { "cell_type": "markdown", - "id": "482f2f1e-15dc-4106-883e-802e85ab556d", + "id": "daca8f8f-ea7a-4da5-a9ea-23f7805fe36d", "metadata": {}, "source": [ " If `qiskit-toqm` were installed, then `toqm` would appear in the list of `routing` plugins." @@ -86,7 +86,7 @@ }, { "cell_type": "markdown", - "id": "845e0bbc-8a7a-4f50-8420-dccebf38169d", + "id": "b723ca18-1358-4cf3-90e4-ae79f1db85b9", "metadata": {}, "source": [ "### List available unitary synthesis plugins\n", @@ -97,7 +97,7 @@ { "cell_type": "code", "execution_count": 3, - "id": "12810039-64e3-4389-be24-3f4ff1fc9642", + "id": "8535f628-25a9-4651-81de-0ba7aac1e938", "metadata": {}, "outputs": [ { @@ -119,7 +119,7 @@ }, { "cell_type": "markdown", - "id": "4fe8731d-f0ec-427e-9b4a-db2b71a2827f", + "id": "5f31164d-a82d-4da3-98b9-39fba6fa3791", "metadata": {}, "source": [ "### List available high-level sythesis plugins\n", @@ -130,7 +130,7 @@ { "cell_type": "code", "execution_count": 4, - "id": "f103fdd1-a9c3-4c0e-b0b7-d9d02561cba3", + "id": "d8a3f89f-2157-4c4b-9812-8c5bab7172a8", "metadata": {}, "outputs": [ { @@ -152,7 +152,51 @@ }, { "cell_type": "markdown", - "id": "6dd1c68f-af34-4887-b297-054b57f20f53", + "id": "8db6f96e-a03f-4364-8bb7-fa195a9408ac", + "metadata": {}, + "source": [ + "You can use the [HighLevelSynthesisPluginManager](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager) class to list the names of all high-level synthesis plugins:" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "b5eaa297-fea8-4a48-9d4a-c247a9d38aa9", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['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", + " 'permutation.acg',\n", + " 'permutation.basic',\n", + " 'permutation.default',\n", + " 'permutation.kms',\n", + " 'permutation.token_swapper']" + ] + }, + "execution_count": 21, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qiskit.transpiler.passes.synthesis.plugin import HighLevelSynthesisPluginManager\n", + "\n", + "HighLevelSynthesisPluginManager().plugins.names()" + ] + }, + { + "cell_type": "markdown", + "id": "79f983c1-495a-4e9e-9fb8-80aa55ea1966", "metadata": {}, "source": [ "## Use a plugin\n", @@ -165,7 +209,7 @@ { "cell_type": "code", "execution_count": 5, - "id": "049378d6-20ad-4ef4-9f3c-58311a5944be", + "id": "bf81a38d-a9d4-4e98-936c-5edf8181c2ad", "metadata": {}, "outputs": [], "source": [ @@ -183,7 +227,7 @@ { "attachments": {}, "cell_type": "markdown", - "id": "b7dee496-07db-4423-8b5d-265c4100c1c1", + "id": "2e3dc574-618c-4386-a8af-fb3261e98dc9", "metadata": {}, "source": [ "### Use a unitary synthesis plugin\n", @@ -194,7 +238,7 @@ { "cell_type": "code", "execution_count": 6, - "id": "c6f563f0-173d-4937-8969-e08d250a1ddb", + "id": "49e7a6ca-3596-474a-a943-68f49149019a", "metadata": {}, "outputs": [], "source": [ @@ -208,7 +252,7 @@ }, { "cell_type": "markdown", - "id": "3d8b84f4-3001-4857-a493-cbd6381a6507", + "id": "dd23f4e2-6042-4fb6-a919-d376a0195ff5", "metadata": {}, "source": [ "Unitary synthesis is used in the `init`, `translation`, and `optimization` stages of the staged pass manager returned by [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile).\n", @@ -219,7 +263,7 @@ { "attachments": {}, "cell_type": "markdown", - "id": "b213f0d2-d969-4dca-9743-e14475f0e0c2", + "id": "1f664d6e-670c-40c2-994b-be980656605c", "metadata": {}, "source": [ "### Use a high-level synthesis plugin\n", @@ -231,7 +275,7 @@ { "cell_type": "code", "execution_count": 7, - "id": "a0a45258-d391-4ad2-9e3b-978ce266779f", + "id": "3a8e775b-749c-44e8-9767-5c0e5233a096", "metadata": {}, "outputs": [], "source": [ @@ -242,7 +286,7 @@ }, { "cell_type": "markdown", - "id": "e9c39d39-9d42-4a0d-a044-fe0df9445b36", + "id": "85bd015c-8697-40e2-b06f-3ef4762d8bc0", "metadata": {}, "source": [ "This code cell creates a high-level synthesis configuration that uses the `layers` plugin\n", @@ -262,7 +306,7 @@ { "cell_type": "code", "execution_count": 8, - "id": "c0eb2d77-d144-4946-960f-49ed08ba517d", + "id": "e3ceb56b-7910-4e99-bc38-ed81ba9fdb55", "metadata": {}, "outputs": [], "source": [ @@ -273,7 +317,7 @@ }, { "cell_type": "markdown", - "id": "9ef44cf9-fc5b-4beb-af4c-db368c90e312", + "id": "f72797af-c104-4938-bd1d-9e7e248fd6f6", "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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile)." From 55d051d7e7b25fda24206b1d914bb103aebadb09 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Wed, 21 Feb 2024 16:26:51 -0500 Subject: [PATCH 17/25] refer to transpiler stages docs --- docs/transpile/transpiler-plugins.ipynb | 46 ++++++++++++------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index e0145bc22d3..59bb330c10d 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "5aec3ebc-57f6-4472-9dfe-fc8aac585dd9", + "id": "795be283-a243-4adb-a106-5ef0bb743c07", "metadata": {}, "source": [ "# Transpiler plugins\n", @@ -20,7 +20,7 @@ }, { "cell_type": "markdown", - "id": "f9c4440b-5e9b-44e3-9228-529ea3b34f48", + "id": "bdf51a04-6dc3-475e-af4a-95a7a6587a3d", "metadata": {}, "source": [ "## List available plugins and install new ones\n", @@ -35,7 +35,7 @@ { "cell_type": "code", "execution_count": 1, - "id": "1a3c398e-b48d-4679-bfde-a3773b379b3e", + "id": "0869bac8-7c98-4be6-a1c0-653432ff1964", "metadata": {}, "outputs": [ { @@ -58,7 +58,7 @@ { "cell_type": "code", "execution_count": 2, - "id": "fa2396d9-5c2f-46d7-98e2-5f5295e99853", + "id": "5007f1ed-8468-45e5-a896-70e251e5539d", "metadata": {}, "outputs": [ { @@ -78,7 +78,7 @@ }, { "cell_type": "markdown", - "id": "daca8f8f-ea7a-4da5-a9ea-23f7805fe36d", + "id": "bc902820-8c51-429f-a53e-b10b079c09af", "metadata": {}, "source": [ " If `qiskit-toqm` were installed, then `toqm` would appear in the list of `routing` plugins." @@ -86,7 +86,7 @@ }, { "cell_type": "markdown", - "id": "b723ca18-1358-4cf3-90e4-ae79f1db85b9", + "id": "b233e6c7-9aec-48ba-9dad-27ce1360e013", "metadata": {}, "source": [ "### List available unitary synthesis plugins\n", @@ -97,7 +97,7 @@ { "cell_type": "code", "execution_count": 3, - "id": "8535f628-25a9-4651-81de-0ba7aac1e938", + "id": "161e2446-0d6b-4bac-86ee-7f2409246e7b", "metadata": {}, "outputs": [ { @@ -119,7 +119,7 @@ }, { "cell_type": "markdown", - "id": "5f31164d-a82d-4da3-98b9-39fba6fa3791", + "id": "f9f6f6be-ef00-4300-9877-1d9b81e82c33", "metadata": {}, "source": [ "### List available high-level sythesis plugins\n", @@ -130,7 +130,7 @@ { "cell_type": "code", "execution_count": 4, - "id": "d8a3f89f-2157-4c4b-9812-8c5bab7172a8", + "id": "3542155e-cfd6-4571-b62b-ee44df18e087", "metadata": {}, "outputs": [ { @@ -152,7 +152,7 @@ }, { "cell_type": "markdown", - "id": "8db6f96e-a03f-4364-8bb7-fa195a9408ac", + "id": "b8b96b12-9301-4a55-8f70-52b4136e6a05", "metadata": {}, "source": [ "You can use the [HighLevelSynthesisPluginManager](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager) class to list the names of all high-level synthesis plugins:" @@ -161,7 +161,7 @@ { "cell_type": "code", "execution_count": 21, - "id": "b5eaa297-fea8-4a48-9d4a-c247a9d38aa9", + "id": "c5f9defb-521c-4634-871f-3ac0ab7e6faf", "metadata": {}, "outputs": [ { @@ -196,7 +196,7 @@ }, { "cell_type": "markdown", - "id": "79f983c1-495a-4e9e-9fb8-80aa55ea1966", + "id": "242c557f-4e3c-4f7e-a417-a497fc6da3e6", "metadata": {}, "source": [ "## Use a plugin\n", @@ -209,7 +209,7 @@ { "cell_type": "code", "execution_count": 5, - "id": "bf81a38d-a9d4-4e98-936c-5edf8181c2ad", + "id": "76738594-1ded-4a68-8d1e-8f23f91f0c9e", "metadata": {}, "outputs": [], "source": [ @@ -227,7 +227,7 @@ { "attachments": {}, "cell_type": "markdown", - "id": "2e3dc574-618c-4386-a8af-fb3261e98dc9", + "id": "777f43c2-9802-4b61-8a8d-a5370fa25431", "metadata": {}, "source": [ "### Use a unitary synthesis plugin\n", @@ -238,7 +238,7 @@ { "cell_type": "code", "execution_count": 6, - "id": "49e7a6ca-3596-474a-a943-68f49149019a", + "id": "247807c2-ab7b-46df-aa96-53739c227e00", "metadata": {}, "outputs": [], "source": [ @@ -252,10 +252,10 @@ }, { "cell_type": "markdown", - "id": "dd23f4e2-6042-4fb6-a919-d376a0195ff5", + "id": "c32c5ff8-e072-490a-b835-3836022f9907", "metadata": {}, "source": [ - "Unitary synthesis is used in the `init`, `translation`, and `optimization` stages of the staged pass manager returned by [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile).\n", + "Unitary synthesis is used in the `init`, `translation`, and `optimization` stages of the staged pass manager returned by [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/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](/api/qiskit/transpiler_synthesis_plugins#unitary-synthesis-plugins-2) for links to the documentation of the built-in unitary synthesis plugins." ] @@ -263,7 +263,7 @@ { "attachments": {}, "cell_type": "markdown", - "id": "1f664d6e-670c-40c2-994b-be980656605c", + "id": "78436237-1bbf-43cb-91d5-bc2f67eb72e7", "metadata": {}, "source": [ "### Use a high-level synthesis plugin\n", @@ -275,7 +275,7 @@ { "cell_type": "code", "execution_count": 7, - "id": "3a8e775b-749c-44e8-9767-5c0e5233a096", + "id": "21de4399-2aa4-4432-b758-5e9c2d66d79b", "metadata": {}, "outputs": [], "source": [ @@ -286,7 +286,7 @@ }, { "cell_type": "markdown", - "id": "85bd015c-8697-40e2-b06f-3ef4762d8bc0", + "id": "cc2e87c5-80da-42ce-a1f1-700a749d9e3f", "metadata": {}, "source": [ "This code cell creates a high-level synthesis configuration that uses the `layers` plugin\n", @@ -306,7 +306,7 @@ { "cell_type": "code", "execution_count": 8, - "id": "e3ceb56b-7910-4e99-bc38-ed81ba9fdb55", + "id": "b1e6e330-c51e-40fe-85a1-d10c98f0450d", "metadata": {}, "outputs": [], "source": [ @@ -317,10 +317,10 @@ }, { "cell_type": "markdown", - "id": "f72797af-c104-4938-bd1d-9e7e248fd6f6", + "id": "41dbe866-95b1-4e6f-bd26-21e292afb87f", "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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile)." + "High-level synthesis is used in the `init`, `translation`, and `optimization` stages of the staged pass manager returned by [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile). See [Transpiler stages](transpiler-stages) for a description of these stages." ] } ], From 4aa0df939658f288ead3f2c79b7c8df1d97d6f9f Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Thu, 22 Feb 2024 13:54:31 -0500 Subject: [PATCH 18/25] remove redundant link --- docs/transpile/transpiler-plugins.ipynb | 44 ++++++++++++------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index 59bb330c10d..ded76b792ca 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "795be283-a243-4adb-a106-5ef0bb743c07", + "id": "b09b851c-1be2-437f-b065-c1c5d65bd502", "metadata": {}, "source": [ "# Transpiler plugins\n", @@ -20,12 +20,12 @@ }, { "cell_type": "markdown", - "id": "bdf51a04-6dc3-475e-af4a-95a7a6587a3d", + "id": "85bf37c2-9990-463c-9130-5b63a2919b1f", "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/), and you can find them on [this page](https://qiskit.github.io/ecosystem/#transpiler_plugin).\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", @@ -35,7 +35,7 @@ { "cell_type": "code", "execution_count": 1, - "id": "0869bac8-7c98-4be6-a1c0-653432ff1964", + "id": "3e5b167d-aded-46de-8380-398aa49d574d", "metadata": {}, "outputs": [ { @@ -58,7 +58,7 @@ { "cell_type": "code", "execution_count": 2, - "id": "5007f1ed-8468-45e5-a896-70e251e5539d", + "id": "4c0d77d7-3cb9-4ca5-8809-510fe5099699", "metadata": {}, "outputs": [ { @@ -78,7 +78,7 @@ }, { "cell_type": "markdown", - "id": "bc902820-8c51-429f-a53e-b10b079c09af", + "id": "61eb0f42-2823-4d3e-9dac-97cbb21cca26", "metadata": {}, "source": [ " If `qiskit-toqm` were installed, then `toqm` would appear in the list of `routing` plugins." @@ -86,7 +86,7 @@ }, { "cell_type": "markdown", - "id": "b233e6c7-9aec-48ba-9dad-27ce1360e013", + "id": "07d056c2-bc0e-4459-a822-3ee18fc3f69a", "metadata": {}, "source": [ "### List available unitary synthesis plugins\n", @@ -97,7 +97,7 @@ { "cell_type": "code", "execution_count": 3, - "id": "161e2446-0d6b-4bac-86ee-7f2409246e7b", + "id": "edcd61f8-bedc-4f09-b32e-8c1cb9bc5302", "metadata": {}, "outputs": [ { @@ -119,7 +119,7 @@ }, { "cell_type": "markdown", - "id": "f9f6f6be-ef00-4300-9877-1d9b81e82c33", + "id": "527725bb-6c5b-4b94-bbe4-6dd0a8c6da41", "metadata": {}, "source": [ "### List available high-level sythesis plugins\n", @@ -130,7 +130,7 @@ { "cell_type": "code", "execution_count": 4, - "id": "3542155e-cfd6-4571-b62b-ee44df18e087", + "id": "5d74f2a4-5349-4539-b276-9cce09b831e8", "metadata": {}, "outputs": [ { @@ -152,7 +152,7 @@ }, { "cell_type": "markdown", - "id": "b8b96b12-9301-4a55-8f70-52b4136e6a05", + "id": "b581176c-ddbb-457b-a4d3-7c7fc62f10b8", "metadata": {}, "source": [ "You can use the [HighLevelSynthesisPluginManager](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager) class to list the names of all high-level synthesis plugins:" @@ -161,7 +161,7 @@ { "cell_type": "code", "execution_count": 21, - "id": "c5f9defb-521c-4634-871f-3ac0ab7e6faf", + "id": "73f4b255-e3d6-4e66-9907-31f0bd4b686d", "metadata": {}, "outputs": [ { @@ -196,7 +196,7 @@ }, { "cell_type": "markdown", - "id": "242c557f-4e3c-4f7e-a417-a497fc6da3e6", + "id": "32f1ef50-08d8-4cff-8bb0-62b8fc92eb3b", "metadata": {}, "source": [ "## Use a plugin\n", @@ -209,7 +209,7 @@ { "cell_type": "code", "execution_count": 5, - "id": "76738594-1ded-4a68-8d1e-8f23f91f0c9e", + "id": "f4b94173-7f4b-4672-9278-2ad8e0824383", "metadata": {}, "outputs": [], "source": [ @@ -227,7 +227,7 @@ { "attachments": {}, "cell_type": "markdown", - "id": "777f43c2-9802-4b61-8a8d-a5370fa25431", + "id": "18777e17-e228-4824-9a6a-fdfce7b84a97", "metadata": {}, "source": [ "### Use a unitary synthesis plugin\n", @@ -238,7 +238,7 @@ { "cell_type": "code", "execution_count": 6, - "id": "247807c2-ab7b-46df-aa96-53739c227e00", + "id": "913d409f-b3d6-4808-ba0d-54f11c553f1b", "metadata": {}, "outputs": [], "source": [ @@ -252,7 +252,7 @@ }, { "cell_type": "markdown", - "id": "c32c5ff8-e072-490a-b835-3836022f9907", + "id": "05a80404-0427-4e6f-b2cc-5b75a7d40e85", "metadata": {}, "source": [ "Unitary synthesis is used in the `init`, `translation`, and `optimization` stages of the staged pass manager returned by [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile). See [Transpiler stages](transpiler-stages) for a description of these stages.\n", @@ -263,7 +263,7 @@ { "attachments": {}, "cell_type": "markdown", - "id": "78436237-1bbf-43cb-91d5-bc2f67eb72e7", + "id": "44dbefe5-c489-4764-a19e-0b536a6166ea", "metadata": {}, "source": [ "### Use a high-level synthesis plugin\n", @@ -275,7 +275,7 @@ { "cell_type": "code", "execution_count": 7, - "id": "21de4399-2aa4-4432-b758-5e9c2d66d79b", + "id": "934605a8-ebef-41b9-a84d-d8ac3013b750", "metadata": {}, "outputs": [], "source": [ @@ -286,7 +286,7 @@ }, { "cell_type": "markdown", - "id": "cc2e87c5-80da-42ce-a1f1-700a749d9e3f", + "id": "019e529b-99ae-4ea5-a34a-33901f25e112", "metadata": {}, "source": [ "This code cell creates a high-level synthesis configuration that uses the `layers` plugin\n", @@ -306,7 +306,7 @@ { "cell_type": "code", "execution_count": 8, - "id": "b1e6e330-c51e-40fe-85a1-d10c98f0450d", + "id": "4de39a1d-3435-4519-b053-b8a14ecf4fe3", "metadata": {}, "outputs": [], "source": [ @@ -317,7 +317,7 @@ }, { "cell_type": "markdown", - "id": "41dbe866-95b1-4e6f-bd26-21e292afb87f", + "id": "85d7c56f-1313-4a2d-8abe-37a548b514df", "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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile). See [Transpiler stages](transpiler-stages) for a description of these stages." From b788f73dfadeba90ea84f2cf798c9f2eae0e2d32 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Thu, 22 Feb 2024 14:05:49 -0500 Subject: [PATCH 19/25] say that examples use built-in plugins and add next steps --- docs/transpile/transpiler-plugins.ipynb | 40 ++++++++++--------------- 1 file changed, 16 insertions(+), 24 deletions(-) diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index ded76b792ca..d2ac5aac6ce 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -2,7 +2,6 @@ "cells": [ { "cell_type": "markdown", - "id": "b09b851c-1be2-437f-b065-c1c5d65bd502", "metadata": {}, "source": [ "# Transpiler plugins\n", @@ -20,7 +19,6 @@ }, { "cell_type": "markdown", - "id": "85bf37c2-9990-463c-9130-5b63a2919b1f", "metadata": {}, "source": [ "## List available plugins and install new ones\n", @@ -35,7 +33,6 @@ { "cell_type": "code", "execution_count": 1, - "id": "3e5b167d-aded-46de-8380-398aa49d574d", "metadata": {}, "outputs": [ { @@ -58,7 +55,6 @@ { "cell_type": "code", "execution_count": 2, - "id": "4c0d77d7-3cb9-4ca5-8809-510fe5099699", "metadata": {}, "outputs": [ { @@ -78,7 +74,6 @@ }, { "cell_type": "markdown", - "id": "61eb0f42-2823-4d3e-9dac-97cbb21cca26", "metadata": {}, "source": [ " If `qiskit-toqm` were installed, then `toqm` would appear in the list of `routing` plugins." @@ -86,7 +81,6 @@ }, { "cell_type": "markdown", - "id": "07d056c2-bc0e-4459-a822-3ee18fc3f69a", "metadata": {}, "source": [ "### List available unitary synthesis plugins\n", @@ -97,7 +91,6 @@ { "cell_type": "code", "execution_count": 3, - "id": "edcd61f8-bedc-4f09-b32e-8c1cb9bc5302", "metadata": {}, "outputs": [ { @@ -119,7 +112,6 @@ }, { "cell_type": "markdown", - "id": "527725bb-6c5b-4b94-bbe4-6dd0a8c6da41", "metadata": {}, "source": [ "### List available high-level sythesis plugins\n", @@ -130,7 +122,6 @@ { "cell_type": "code", "execution_count": 4, - "id": "5d74f2a4-5349-4539-b276-9cce09b831e8", "metadata": {}, "outputs": [ { @@ -152,7 +143,6 @@ }, { "cell_type": "markdown", - "id": "b581176c-ddbb-457b-a4d3-7c7fc62f10b8", "metadata": {}, "source": [ "You can use the [HighLevelSynthesisPluginManager](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager) class to list the names of all high-level synthesis plugins:" @@ -161,7 +151,6 @@ { "cell_type": "code", "execution_count": 21, - "id": "73f4b255-e3d6-4e66-9907-31f0bd4b686d", "metadata": {}, "outputs": [ { @@ -196,11 +185,12 @@ }, { "cell_type": "markdown", - "id": "32f1ef50-08d8-4cff-8bb0-62b8fc92eb3b", "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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or [`transpile`](/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 `stochastic` routing plugin, we would specify `stochastic` for the `routing_method` argument:" @@ -209,7 +199,6 @@ { "cell_type": "code", "execution_count": 5, - "id": "f4b94173-7f4b-4672-9278-2ad8e0824383", "metadata": {}, "outputs": [], "source": [ @@ -227,7 +216,6 @@ { "attachments": {}, "cell_type": "markdown", - "id": "18777e17-e228-4824-9a6a-fdfce7b84a97", "metadata": {}, "source": [ "### Use a unitary synthesis plugin\n", @@ -238,7 +226,6 @@ { "cell_type": "code", "execution_count": 6, - "id": "913d409f-b3d6-4808-ba0d-54f11c553f1b", "metadata": {}, "outputs": [], "source": [ @@ -252,7 +239,6 @@ }, { "cell_type": "markdown", - "id": "05a80404-0427-4e6f-b2cc-5b75a7d40e85", "metadata": {}, "source": [ "Unitary synthesis is used in the `init`, `translation`, and `optimization` stages of the staged pass manager returned by [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile). See [Transpiler stages](transpiler-stages) for a description of these stages.\n", @@ -263,7 +249,6 @@ { "attachments": {}, "cell_type": "markdown", - "id": "44dbefe5-c489-4764-a19e-0b536a6166ea", "metadata": {}, "source": [ "### Use a high-level synthesis plugin\n", @@ -275,7 +260,6 @@ { "cell_type": "code", "execution_count": 7, - "id": "934605a8-ebef-41b9-a84d-d8ac3013b750", "metadata": {}, "outputs": [], "source": [ @@ -286,7 +270,6 @@ }, { "cell_type": "markdown", - "id": "019e529b-99ae-4ea5-a34a-33901f25e112", "metadata": {}, "source": [ "This code cell creates a high-level synthesis configuration that uses the `layers` plugin\n", @@ -306,7 +289,6 @@ { "cell_type": "code", "execution_count": 8, - "id": "4de39a1d-3435-4519-b053-b8a14ecf4fe3", "metadata": {}, "outputs": [], "source": [ @@ -317,19 +299,29 @@ }, { "cell_type": "markdown", - "id": "85d7c56f-1313-4a2d-8abe-37a548b514df", "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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile). See [Transpiler stages](transpiler-stages) for a description of these stages." ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + " - [Create a transpiler plugin](create-a-transpiler-plugin).\n", + "" + ] } ], "metadata": { "description": "How to use transpiler plugins in Qiskit.", "kernelspec": { - "display_name": "Python 3", + "display_name": "documentation", "language": "python", - "name": "python3" + "name": "documentation" }, "language_info": { "codemirror_mode": { @@ -341,7 +333,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.10.12" }, "title": "Transpiler plugins" }, From edb7f73af5f557af28765e17a0f8726be5638ca8 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Thu, 22 Feb 2024 16:38:06 -0500 Subject: [PATCH 20/25] clarify metadata files and add comments --- .../create-a-transpiler-plugin.ipynb | 20 ++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index e9f3a3b87a2..d8c3e79f5f5 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -92,7 +92,7 @@ "source": [ "Now, we expose the plugin by adding an entry point in our Python package metadata.\n", "Here, we assume that the class we defined is exposed in a module called `my_qiskit_plugin`, for example by being imported in the `__init__.py` file of the `my_qiskit_plugin` module.\n", - "We edit the `pyproject.toml`, `setup.cfg`, or `setup.py` file of our package:\n", + "We edit the `pyproject.toml`, `setup.cfg`, or `setup.py` file of our package (depending on which kind of file you chose to store your Python project metadata):\n", "\n", "\n", " \n", @@ -205,46 +205,60 @@ "class MyUnitarySynthesisPlugin(UnitarySynthesisPlugin):\n", " @property\n", " def supports_basis_gates(self):\n", + " # Returns True if the plugin can target a list of basis gates\n", " return True\n", "\n", " @property\n", " def supports_coupling_map(self):\n", + " # Returns True if the plugin can synthesize for a given coupling map\n", " return False\n", "\n", " @property\n", " def supports_natural_direction(self):\n", + " # Returns True if the plugin supports a toggle for considering\n", + " # directionality of 2-qubit gates\n", " return False\n", "\n", " @property\n", " def supports_pulse_optimize(self):\n", + " # Returns True if the plugin can optimize pulses during synthesis\n", " return False\n", "\n", " @property\n", " def supports_gate_lengths(self):\n", + " # Returns True if the plugin can accept information about gate lengths\n", " return False\n", "\n", " @property\n", " def supports_gate_errors(self):\n", + " # Returns True if the plugin can accept information about gate errors\n", " return False\n", "\n", " @property\n", " def supports_gate_lengths_by_qubit(self):\n", + " # Returns True if the plugin can accept information about gate lengths\n", + " # (The format of the input differs from supports_gate_lengths)\n", " return False\n", "\n", " @property\n", " def supports_gate_errors_by_qubit(self):\n", + " # Returns True if the plugin can accept information about gate errors\n", + " # (The format of the input differs from supports_gate_errors)\n", " return False\n", "\n", " @property\n", " def min_qubits(self):\n", + " # Returns the minimum number of qubits the plugin supports\n", " return None\n", "\n", " @property\n", " def max_qubits(self):\n", + " # Returns the maximum number of qubits the plugin supports\n", " return None\n", "\n", " @property\n", " def supported_bases(self):\n", + " # Returns a dictionary of supported bases for synthesis\n", " return None\n", "\n", " def run(self, unitary: np.ndarray, **options) -> DAGCircuit:\n", @@ -488,7 +502,7 @@ "metadata": { "description": "How to create a Qiskit transpiler plugin.", "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -502,7 +516,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.11.7" }, "title": "Create a transpiler plugin" }, From b7d848709d5ff2eff22b21e99658fd66f2fe3442 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Thu, 22 Feb 2024 16:38:22 -0500 Subject: [PATCH 21/25] run squeaky --- docs/transpile/transpiler-plugins.ipynb | 28 ++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index d2ac5aac6ce..9223f9c6352 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "334fb4b3-9d8d-4ee2-ba20-b6008b13c6e5", "metadata": {}, "source": [ "# Transpiler plugins\n", @@ -19,6 +20,7 @@ }, { "cell_type": "markdown", + "id": "aa9e4775-d7fb-473f-8864-c6c2f42d309c", "metadata": {}, "source": [ "## List available plugins and install new ones\n", @@ -33,6 +35,7 @@ { "cell_type": "code", "execution_count": 1, + "id": "17cf6ef8-7edf-428c-a779-8c934e67720d", "metadata": {}, "outputs": [ { @@ -55,6 +58,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "6077307e-3214-453d-af1b-c19ee2f917f4", "metadata": {}, "outputs": [ { @@ -74,6 +78,7 @@ }, { "cell_type": "markdown", + "id": "fde508b8-ac1d-42d8-84cc-60e37d78092e", "metadata": {}, "source": [ " If `qiskit-toqm` were installed, then `toqm` would appear in the list of `routing` plugins." @@ -81,6 +86,7 @@ }, { "cell_type": "markdown", + "id": "c2214241-8bb7-47e4-91b2-d5225f9dd281", "metadata": {}, "source": [ "### List available unitary synthesis plugins\n", @@ -91,6 +97,7 @@ { "cell_type": "code", "execution_count": 3, + "id": "5b8e4b56-79bd-4079-a22f-cf74f2a86f4a", "metadata": {}, "outputs": [ { @@ -112,6 +119,7 @@ }, { "cell_type": "markdown", + "id": "5497ad2a-92aa-4461-8182-89472848e214", "metadata": {}, "source": [ "### List available high-level sythesis plugins\n", @@ -122,6 +130,7 @@ { "cell_type": "code", "execution_count": 4, + "id": "d88eee69-c021-41e1-9c69-6a461e77ab12", "metadata": {}, "outputs": [ { @@ -143,6 +152,7 @@ }, { "cell_type": "markdown", + "id": "be7d3c04-3c0f-4a84-9311-108f04f75196", "metadata": {}, "source": [ "You can use the [HighLevelSynthesisPluginManager](/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager) class to list the names of all high-level synthesis plugins:" @@ -151,6 +161,7 @@ { "cell_type": "code", "execution_count": 21, + "id": "7def6967-6125-43f4-b59f-617f0e2b298f", "metadata": {}, "outputs": [ { @@ -185,6 +196,7 @@ }, { "cell_type": "markdown", + "id": "bfdf815b-78f8-40b4-b24e-bab68506237a", "metadata": {}, "source": [ "## Use a plugin\n", @@ -199,6 +211,7 @@ { "cell_type": "code", "execution_count": 5, + "id": "98b3b08c-0945-47dd-918a-ccd62e8efa54", "metadata": {}, "outputs": [], "source": [ @@ -216,6 +229,7 @@ { "attachments": {}, "cell_type": "markdown", + "id": "955b3de1-0363-4c05-bca4-47dec38837fb", "metadata": {}, "source": [ "### Use a unitary synthesis plugin\n", @@ -226,6 +240,7 @@ { "cell_type": "code", "execution_count": 6, + "id": "134c7ce2-ae3b-496e-89a8-cfe554ed6e32", "metadata": {}, "outputs": [], "source": [ @@ -239,6 +254,7 @@ }, { "cell_type": "markdown", + "id": "a2b1c570-50f6-45ae-928d-274e827501fe", "metadata": {}, "source": [ "Unitary synthesis is used in the `init`, `translation`, and `optimization` stages of the staged pass manager returned by [`generate_preset_pass_manager`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile). See [Transpiler stages](transpiler-stages) for a description of these stages.\n", @@ -249,6 +265,7 @@ { "attachments": {}, "cell_type": "markdown", + "id": "241012ed-3f75-4ac9-a5bf-cf55b4db5b1f", "metadata": {}, "source": [ "### Use a high-level synthesis plugin\n", @@ -260,6 +277,7 @@ { "cell_type": "code", "execution_count": 7, + "id": "057d86eb-6d70-4772-8b9c-98fbe5566fac", "metadata": {}, "outputs": [], "source": [ @@ -270,6 +288,7 @@ }, { "cell_type": "markdown", + "id": "7b5e1b28-a8e9-4767-b0ae-9cc940f89ede", "metadata": {}, "source": [ "This code cell creates a high-level synthesis configuration that uses the `layers` plugin\n", @@ -289,6 +308,7 @@ { "cell_type": "code", "execution_count": 8, + "id": "a9245ac1-af79-48cf-85e3-16b27417f5b3", "metadata": {}, "outputs": [], "source": [ @@ -299,6 +319,7 @@ }, { "cell_type": "markdown", + "id": "b1c5f3a7-01f1-4424-a8f8-f174f1e14905", "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`](/api/qiskit/transpiler_preset#generate_preset_pass_manager) or used in [`transpile`](/api/qiskit/compiler#qiskit.compiler.transpile). See [Transpiler stages](transpiler-stages) for a description of these stages." @@ -306,6 +327,7 @@ }, { "cell_type": "markdown", + "id": "de7bff27-0e8e-48ac-9546-757b8ba36384", "metadata": {}, "source": [ "## Next steps\n", @@ -319,9 +341,9 @@ "metadata": { "description": "How to use transpiler plugins in Qiskit.", "kernelspec": { - "display_name": "documentation", + "display_name": "Python 3", "language": "python", - "name": "documentation" + "name": "python3" }, "language_info": { "codemirror_mode": { @@ -333,7 +355,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3" }, "title": "Transpiler plugins" }, From 7d00b725e9a7c365d1064a691e62e53c3bd85def Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Thu, 22 Feb 2024 16:41:57 -0500 Subject: [PATCH 22/25] add next steps: submit to ecosystem --- docs/transpile/create-a-transpiler-plugin.ipynb | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index d8c3e79f5f5..677b79efc91 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -497,12 +497,22 @@ "source": [ "If our example plugin were installed, then the name `my_clifford_synthesis` would appear in this list." ] + }, + { + "cell_type": "markdown", + "id": "a48c2d0b-c402-4b83-ae2e-42c33fe1720e", + "metadata": {}, + "source": [ + "\n", + " - [Submit your plugin to the Qiskit Ecosystem!](https://github.com/Qiskit/ecosystem?tab=readme-ov-file#how-to-join).\n", + "" + ] } ], "metadata": { "description": "How to create a Qiskit transpiler plugin.", "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -516,7 +526,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.7" + "version": "3" }, "title": "Create a transpiler plugin" }, From 10241bc576d349092b12e22d800469dfee58a106 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 26 Feb 2024 15:38:48 -0500 Subject: [PATCH 23/25] add links to learning platform --- docs/transpile/create-a-transpiler-plugin.ipynb | 1 + docs/transpile/transpiler-plugins.ipynb | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index 677b79efc91..3aa30b849d6 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -505,6 +505,7 @@ "source": [ "\n", " - [Submit your plugin to the Qiskit Ecosystem!](https://github.com/Qiskit/ecosystem?tab=readme-ov-file#how-to-join).\n", + " - Check out the tutorials on [IBM Quantum Learning](https://learning.quantum.ibm.com/catalog/tutorials) for examples of transpiling and running quantum circuits.\n", "" ] } diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index 9223f9c6352..4d35ef08ca5 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -334,6 +334,7 @@ "\n", "\n", " - [Create a transpiler plugin](create-a-transpiler-plugin).\n", + " - Check out the tutorials on [IBM Quantum Learning](https://learning.quantum.ibm.com/catalog/tutorials) for examples of transpiling and running quantum circuits.\n", "" ] } From 933745666cc195153efae3ecea8a2af9155c56ab Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 26 Feb 2024 17:36:06 -0500 Subject: [PATCH 24/25] put in separate sidebard heading --- docs/transpile/_toc.json | 15 ++++++++++----- docs/transpile/transpiler-plugins.ipynb | 4 ++-- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/transpile/_toc.json b/docs/transpile/_toc.json index 2d5f60f35b4..e969bd29cf4 100644 --- a/docs/transpile/_toc.json +++ b/docs/transpile/_toc.json @@ -24,11 +24,16 @@ }, { "title": "Transpiler plugins", - "url": "/transpile/transpiler-plugins" - }, - { - "title": "Create a transpiler plugin", - "url": "/transpile/create-a-transpiler-plugin" + "children": [ + { + "title": "Install and use transpiler plugins", + "url": "/transpile/transpiler-plugins" + }, + { + "title": "Create a transpiler plugin", + "url": "/transpile/create-a-transpiler-plugin" + } + ] }, { "title": "Use the transpile function", diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index 4d35ef08ca5..0f79e451304 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -5,7 +5,7 @@ "id": "334fb4b3-9d8d-4ee2-ba20-b6008b13c6e5", "metadata": {}, "source": [ - "# Transpiler plugins\n", + "# Install and use transpiler plugins\n", "\n", "To facilitate the development and reuse of custom transpilation code by the wider community of Qiskit users, Qiskit supports a plugin interface that enables third-party Python packages to declare that they provide extended transpilation functionality accessible via Qiskit.\n", "\n", @@ -358,7 +358,7 @@ "pygments_lexer": "ipython3", "version": "3" }, - "title": "Transpiler plugins" + "title": "Install and use transpiler plugins" }, "nbformat": 4, "nbformat_minor": 4 From 09b6006173ab4034331e8afd56156db765e724fd Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Tue, 27 Feb 2024 11:01:17 -0500 Subject: [PATCH 25/25] lengthen descriptions --- docs/transpile/create-a-transpiler-plugin.ipynb | 2 +- docs/transpile/transpiler-plugins.ipynb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/transpile/create-a-transpiler-plugin.ipynb b/docs/transpile/create-a-transpiler-plugin.ipynb index 3aa30b849d6..f1d3a0388a3 100644 --- a/docs/transpile/create-a-transpiler-plugin.ipynb +++ b/docs/transpile/create-a-transpiler-plugin.ipynb @@ -511,7 +511,7 @@ } ], "metadata": { - "description": "How to create a Qiskit transpiler plugin.", + "description": "How to create a Qiskit transpiler plugin to share your transpilation code with the Qiskit community.", "kernelspec": { "display_name": "Python 3", "language": "python", diff --git a/docs/transpile/transpiler-plugins.ipynb b/docs/transpile/transpiler-plugins.ipynb index 0f79e451304..7398cc86cf9 100644 --- a/docs/transpile/transpiler-plugins.ipynb +++ b/docs/transpile/transpiler-plugins.ipynb @@ -340,7 +340,7 @@ } ], "metadata": { - "description": "How to use transpiler plugins in Qiskit.", + "description": "How to install and use transpiler plugins in Qiskit.", "kernelspec": { "display_name": "Python 3", "language": "python",