From 9bc4eb972b0e3a6f7cf244e468afaedfd54ea426 Mon Sep 17 00:00:00 2001 From: Alexander Ivrii Date: Thu, 15 Feb 2024 13:55:15 +0200 Subject: [PATCH] add synthesis plugin docs (#11763) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * very initial commit * fix? * temporarily removing * is this one adds absolute paths? * partially restoring * another experiment * adding the remaining information * Move docs to corresponding file and link from top. Remove duplicate AQC plugin entry in synthesis docs and replace with module link. Remove duplicate transpiler builtin plugin page. * Generate AQC page * Remove plugin from synthesis docs, refer to new plugin docs. * adding short descriptions of available plugins --------- Co-authored-by: Elena Peña Tapia (cherry picked from commit 9184907e1cc9b8563186a559d2e446518bbe8fac) --- docs/apidoc/index.rst | 1 - docs/apidoc/synthesis_aqc.rst | 6 - docs/apidoc/transpiler_builtin_plugins.rst | 10 -- docs/apidoc/transpiler_synthesis_plugins.rst | 2 +- qiskit/synthesis/__init__.py | 7 +- qiskit/transpiler/passes/__init__.py | 5 +- .../transpiler/passes/synthesis/aqc_plugin.py | 9 +- .../passes/synthesis/high_level_synthesis.py | 123 +++++++++++++++++- qiskit/transpiler/passes/synthesis/plugin.py | 76 ++++++++--- .../synthesis/solovay_kitaev_synthesis.py | 10 +- .../passes/synthesis/unitary_synthesis.py | 12 +- 11 files changed, 220 insertions(+), 41 deletions(-) delete mode 100644 docs/apidoc/synthesis_aqc.rst delete mode 100644 docs/apidoc/transpiler_builtin_plugins.rst diff --git a/docs/apidoc/index.rst b/docs/apidoc/index.rst index 7cc1c54c23e1..89a2a6bb9a62 100644 --- a/docs/apidoc/index.rst +++ b/docs/apidoc/index.rst @@ -37,6 +37,5 @@ API Reference transpiler_preset transpiler_plugins transpiler_synthesis_plugins - transpiler_builtin_plugins utils exceptions diff --git a/docs/apidoc/synthesis_aqc.rst b/docs/apidoc/synthesis_aqc.rst deleted file mode 100644 index 1be57fbc8182..000000000000 --- a/docs/apidoc/synthesis_aqc.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _qiskit-synthesis-unitary-aqc: - -.. automodule:: qiskit.synthesis.unitary.aqc - :no-members: - :no-inherited-members: - :no-special-members: diff --git a/docs/apidoc/transpiler_builtin_plugins.rst b/docs/apidoc/transpiler_builtin_plugins.rst deleted file mode 100644 index 8bc2b105ed22..000000000000 --- a/docs/apidoc/transpiler_builtin_plugins.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _qiskit-transpiler-builtin-plugins: - -===================================== -Built-in Transpiler Synthesis Plugins -===================================== - -.. toctree:: - :maxdepth: 2 - - synthesis_aqc diff --git a/docs/apidoc/transpiler_synthesis_plugins.rst b/docs/apidoc/transpiler_synthesis_plugins.rst index 70bef1190f40..1f97d49c259a 100644 --- a/docs/apidoc/transpiler_synthesis_plugins.rst +++ b/docs/apidoc/transpiler_synthesis_plugins.rst @@ -3,4 +3,4 @@ .. automodule:: qiskit.transpiler.passes.synthesis.plugin :no-members: :no-inherited-members: - :no-special-members: + :no-special-members: \ No newline at end of file diff --git a/qiskit/synthesis/__init__.py b/qiskit/synthesis/__init__.py index a22c967bc545..c191eac97472 100644 --- a/qiskit/synthesis/__init__.py +++ b/qiskit/synthesis/__init__.py @@ -98,7 +98,12 @@ .. autofunction:: qs_decomposition -The Approximate Quantum Compiler is available here: :mod:`qiskit.synthesis.unitary.aqc` +The Approximate Quantum Compiler is available here: + +.. autosummary:: + :toctree: ../stubs/ + + qiskit.synthesis.unitary.aqc One-Qubit Synthesis =================== diff --git a/qiskit/transpiler/passes/__init__.py b/qiskit/transpiler/passes/__init__.py index 9939581681f2..953efe51ecd7 100644 --- a/qiskit/transpiler/passes/__init__.py +++ b/qiskit/transpiler/passes/__init__.py @@ -139,6 +139,9 @@ Synthesis ========= +The synthesis transpiler plugin documentation can be found in the +:mod:`qiskit.transpiler.passes.synthesis.plugin` page. + .. autosummary:: :toctree: ../stubs/ @@ -147,8 +150,6 @@ HighLevelSynthesis HLSConfig SolovayKitaev - SolovayKitaevSynthesis - AQCSynthesisPlugin Post Layout (Post transpile qubit selection) ============================================ diff --git a/qiskit/transpiler/passes/synthesis/aqc_plugin.py b/qiskit/transpiler/passes/synthesis/aqc_plugin.py index 350683daa2e7..4c9b4b9dae97 100644 --- a/qiskit/transpiler/passes/synthesis/aqc_plugin.py +++ b/qiskit/transpiler/passes/synthesis/aqc_plugin.py @@ -10,7 +10,14 @@ # copyright notice, and modified files need to carry a notice indicating # that they have been altered from the originals. """ -An AQC synthesis plugin to Qiskit's transpiler. +============================================================================== +AQC Synthesis Plugin (in :mod:`qiskit.transpiler.passes.synthesis.aqc_plugin`) +============================================================================== + +.. autosummary:: + :toctree: ../stubs/ + + AQCSynthesisPlugin """ from functools import partial import numpy as np diff --git a/qiskit/transpiler/passes/synthesis/high_level_synthesis.py b/qiskit/transpiler/passes/synthesis/high_level_synthesis.py index bd40865772ba..345843284fa3 100644 --- a/qiskit/transpiler/passes/synthesis/high_level_synthesis.py +++ b/qiskit/transpiler/passes/synthesis/high_level_synthesis.py @@ -11,7 +11,127 @@ # that they have been altered from the originals. -"""Synthesize higher-level objects and unroll custom definitions.""" +""" + +High Level Synthesis Plugins +----------------------------- + +Clifford Synthesis +'''''''''''''''''' + +.. list-table:: Plugins for :class:`qiskit.quantum_info.Clifford` (key = ``"clifford"``) + :header-rows: 1 + + * - Plugin name + - Plugin class + - Targeted connectivity + - Description + * - ``"ag"`` + - :class:`~.AGSynthesisClifford` + - all-to-all + - greedily optimizes CX-count + * - ``"bm"`` + - :class:`~.BMSynthesisClifford` + - all-to-all + - optimal count for `n=2,3`; used in ``"default"`` for `n=2,3` + * - ``"greedy"`` + - :class:`~.GreedySynthesisClifford` + - all-to-all + - greedily optimizes CX-count; used in ``"default"`` for `n>=4` + * - ``"layers"`` + - :class:`~.LayerSynthesisClifford` + - all-to-all + - + * - ``"lnn"`` + - :class:`~.LayerLnnSynthesisClifford` + - linear + - many CX-gates but guarantees CX-depth of at most `7*n+2` + * - ``"default"`` + - :class:`~.DefaultSynthesisClifford` + - all-to-all + - usually best for optimizing CX-count (and optimal CX-count for `n=2,3`) + +.. autosummary:: + :toctree: ../stubs/ + + AGSynthesisClifford + BMSynthesisClifford + GreedySynthesisClifford + LayerSynthesisClifford + LayerLnnSynthesisClifford + DefaultSynthesisClifford + + +Linear Function Synthesis +''''''''''''''''''''''''' + +.. list-table:: Plugins for :class:`.LinearFunction` (key = ``"linear"``) + :header-rows: 1 + + * - Plugin name + - Plugin class + - Targeted connectivity + - Description + * - ``"kms"`` + - :class:`~.KMSSynthesisLinearFunction` + - linear + - many CX-gates but guarantees CX-depth of at most `5*n` + * - ``"pmh"`` + - :class:`~.PMHSynthesisLinearFunction` + - all-to-all + - greedily optimizes CX-count; used in ``"default"`` + * - ``"default"`` + - :class:`~.DefaultSynthesisLinearFunction` + - all-to-all + - best for optimizing CX-count + +.. autosummary:: + :toctree: ../stubs/ + + KMSSynthesisLinearFunction + PMHSynthesisLinearFunction + DefaultSynthesisLinearFunction + + +Permutation Synthesis +''''''''''''''''''''' + +.. list-table:: Plugins for :class:`.PermutationGate` (key = ``"permutation"``) + :header-rows: 1 + + * - Plugin name + - Plugin class + - Targeted connectivity + - Description + * - ``"basic"`` + - :class:`~.BasicSynthesisPermutation` + - all-to-all + - optimal SWAP-count; used in ``"default"`` + * - ``"acg"`` + - :class:`~.ACGSynthesisPermutation` + - all-to-all + - guarantees SWAP-depth of at most `2` + * - ``"kms"`` + - :class:`~.KMSSynthesisPermutation` + - linear + - many SWAP-gates, but guarantees SWAP-depth of at most `n` + * - ``"token_swapper"`` + - :class:`~.TokenSwapperSynthesisPermutation` + - any + - greedily optimizes SWAP-count for arbitrary connectivity + * - ``"default"`` + - :class:`~.BasicSynthesisPermutation` + - all-to-all + - best for optimizing SWAP-count + +.. autosummary:: + :toctree: ../stubs/ + + BasicSynthesisPermutation + ACGSynthesisPermutation + KMSSynthesisPermutation + TokenSwapperSynthesisPermutation +""" from typing import Optional, Union, List, Tuple @@ -522,7 +642,6 @@ def run(self, high_level_object, coupling_map=None, target=None, qubits=None, ** class BMSynthesisClifford(HighLevelSynthesisPlugin): """Clifford synthesis plugin based on the Bravyi-Maslov method. - The plugin is named The method only works on Cliffords with at most 3 qubits, for which it constructs the optimal CX cost decomposition. diff --git a/qiskit/transpiler/passes/synthesis/plugin.py b/qiskit/transpiler/passes/synthesis/plugin.py index f1bbc595d5c2..f2485bfee530 100644 --- a/qiskit/transpiler/passes/synthesis/plugin.py +++ b/qiskit/transpiler/passes/synthesis/plugin.py @@ -30,6 +30,28 @@ See :mod:`qiskit.transpiler.preset_passmanagers.plugin` for details on how to write plugins for transpiler stages. +Synthesis Plugin API +==================== + +Unitary Synthesis Plugin API +---------------------------- + +.. autosummary:: + :toctree: ../stubs/ + + UnitarySynthesisPlugin + UnitarySynthesisPluginManager + unitary_synthesis_plugin_names + +High-Level Synthesis Plugin API +------------------------------- + +.. autosummary:: + :toctree: ../stubs/ + + HighLevelSynthesisPlugin + HighLevelSynthesisPluginManager + high_level_synthesis_plugin_names Writing Plugins =============== @@ -285,7 +307,7 @@ def run(self, high_level_object, coupling_map=None, target=None, qubits=None, ** will return a list of all the installed Clifford synthesis plugins. Available Plugins ------------------ +================= High-level synthesis plugins that are directly available in Qiskit include plugins for synthesizing :class:`.Clifford` objects, :class:`.LinearFunction` objects, and @@ -314,28 +336,52 @@ def run(self, high_level_object, coupling_map=None, target=None, qubits=None, ** with respect to arbitrary coupling maps. For more detail, please refer to description of each individual plugin. -Plugin API -========== +Below are the synthesis plugin classes available in Qiskit. These classes should not be +used directly, but instead should be used through the plugin interface documented +above. The classes are listed here to ease finding the documentation for each of the +included plugins and to ease the comparison between different synthesis methods for +a given object. + Unitary Synthesis Plugins ------------------------- -.. autosummary:: - :toctree: ../stubs/ +.. automodule:: qiskit.transpiler.passes.synthesis.aqc_plugin + :no-members: + :no-inherited-members: + :no-special-members: - UnitarySynthesisPlugin - UnitarySynthesisPluginManager - unitary_synthesis_plugin_names +.. automodule:: qiskit.transpiler.passes.synthesis.unitary_synthesis + :no-members: + :no-inherited-members: + :no-special-members: -High-Level Synthesis Plugins ----------------------------- +.. automodule:: qiskit.transpiler.passes.synthesis.solovay_kitaev_synthesis + :no-members: + :no-inherited-members: + :no-special-members: -.. autosummary:: - :toctree: ../stubs/ - HighLevelSynthesisPlugin - HighLevelSynthesisPluginManager - high_level_synthesis_plugin_names +High Level Synthesis +-------------------- + +For each high-level object we give a table that lists all of its plugins available +directly in Qiskit. We include the name of the plugin, the class of the plugin, +the targeted connectivity map and optionally additional information. Recall the plugins +should be used via the previously described :class:`.HLSConfig`, for example:: + + HLSConfig(permutation=["kms"]) + +creates a high-level synthesis configuration that uses the ``kms`` plugin +for synthesizing :class:`.PermutationGate` objects -- i.e. those with +``name = "permutation"``. In this case, the plugin name is "kms", the plugin class +is :class:`~.KMSSynthesisPermutation`. This particular synthesis algorithm created +a circuit adhering to the linear nearest-neighbor connectivity. + +.. automodule:: qiskit.transpiler.passes.synthesis.high_level_synthesis + :no-members: + :no-inherited-members: + :no-special-members: """ import abc diff --git a/qiskit/transpiler/passes/synthesis/solovay_kitaev_synthesis.py b/qiskit/transpiler/passes/synthesis/solovay_kitaev_synthesis.py index dbc60999fc35..c3c51353d03f 100644 --- a/qiskit/transpiler/passes/synthesis/solovay_kitaev_synthesis.py +++ b/qiskit/transpiler/passes/synthesis/solovay_kitaev_synthesis.py @@ -9,8 +9,16 @@ # Any modifications or derivative works of this code must retain this # copyright notice, and modified files need to carry a notice indicating # that they have been altered from the originals. + """ -A Solovay-Kitaev synthesis plugin to Qiskit's transpiler. +======================================================================================================= +Solovay-Kitaev Synthesis Plugin (in :mod:`qiskit.transpiler.passes.synthesis.solovay_kitaev_synthesis`) +======================================================================================================= + +.. autosummary:: + :toctree: ../stubs/ + + SolovayKitaevSynthesis """ from __future__ import annotations diff --git a/qiskit/transpiler/passes/synthesis/unitary_synthesis.py b/qiskit/transpiler/passes/synthesis/unitary_synthesis.py index 653558d4779b..5d9ba1e6cde7 100644 --- a/qiskit/transpiler/passes/synthesis/unitary_synthesis.py +++ b/qiskit/transpiler/passes/synthesis/unitary_synthesis.py @@ -10,7 +10,17 @@ # copyright notice, and modified files need to carry a notice indicating # that they have been altered from the originals. -"""Synthesize UnitaryGates.""" +""" +========================================================================================= +Unitary Synthesis Plugin (in :mod:`qiskit.transpiler.passes.synthesis.unitary_synthesis`) +========================================================================================= + +.. autosummary:: + :toctree: ../stubs/ + + DefaultUnitarySynthesis +""" + from __future__ import annotations from math import pi, inf, isclose from typing import Any