add synthesis plugin docs (#11763)

* 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 <[email protected]>
Qiskit · Feb 15, 2024 · 9184907 · 9184907
1 parent ffe0019
commit 9184907
Show file tree

Hide file tree

Showing 11 changed files with 220 additions and 41 deletions.
diff --git 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
diff --git a/docs/apidoc/transpiler_builtin_plugins.rst b/docs/apidoc/transpiler_builtin_plugins.rst
diff --git 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:
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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