Add some explanation and example to circuit library documentation

qiskit/circuit/__init__.py

@@ -187,9 +187,6 @@
    Gate
    ControlledGate
    Delay
-   Barrier
-   Measure
-   Reset
    Instruction
    InstructionSet
    EquivalenceLibrary

qiskit/circuit/library/__init__.py

@@ -17,9 +17,45 @@
 
 .. currentmodule:: qiskit.circuit.library
 
-Standard Gates
+The circuit library is a collection of well-studied and valuable circuits, directives, and gates.
+We call them valuable for different reasons, for instance they can serve as building blocks for
+algorithms or they are circuits that we think are hard to simulate classically.
+
+Each element can be plugged into a circuit using the :meth:`.QuantumCircuit.append`
+method and so the circuit library allows users to program at higher levels of abstraction.
+For example, to append a multi-controlled CNOT:
+
+.. jupyter-execute::
+
+    from qiskit.circuit.library import MCXGate
+    gate = MCXGate(4)
+
+    from qiskit import QuantumCircuit
+    circuit = QuantumCircuit(5)
+    circuit.append(gate, [0, 1, 4, 2, 3])
+    circuit.draw('mpl')
+
+The library is organized in several sections.
+
+Standard gates
 ==============
 
+These operations are reversible unitary gates and they all subclass
+:class:`~qiskit.circuit.Gate`. As a consequence, they all have the methods
+:meth:`~qiskit.circuit.Gate.to_matrix`, :meth:`~qiskit.circuit.Gate.power`,
+and :meth:`~qiskit.circuit.Gate.control`, which we can generally only apply to unitary operations.
+
+For example:
+
+.. jupyter-execute::
+
+    from qiskit.circuit.library import XGate
+    gate = XGate()
+    print(gate.to_matrix())             # X gate
+    print(gate.power(1/2).to_matrix())  # √X gate
+    print(gate.control(1).to_matrix())  # CX (controlled X) gate
+
+
 .. autosummary::
    :toctree: ../stubs/
    :template: autosummary/class_no_inherited_members.rst
@@ -44,11 +80,7 @@
    CZGate
    HGate
    IGate
-   MCPhaseGate
-   MCXGate
-   MCXGrayCode
-   MCXRecursive
-   MCXVChain
+   MSGate
    PhaseGate
    RCCXGate
    RC3XGate
@@ -86,15 +118,44 @@
     This summary table deliberately does not generate toctree entries; these directives are "owned"
     by ``qiskit.circuit``.
 
+Directives are operations to the quantum stack that are meant to be interpreted by the backend or
+the transpiler. In general, the transpiler or backend might optionally ignore them if there is no
+implementation for them.
+
 .. autosummary::
+   :toctree: ../stubs/
+
+   Barrier
 
-   ~qiskit.circuit.Barrier
-   ~qiskit.circuit.Measure
-   ~qiskit.circuit.Reset
+Standard Operations
+===================
+
+Operations are non-reversible changes in the quantum state of the circuit.
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   Measure
+   Reset
 
 Generalized Gates
 =================
 
+These "gates" (many are :class:`~qiskit.circuit.QuantumCircuit` subclasses) allow to
+set the amount of qubits involved at instantiation time.
+
+
+.. jupyter-execute::
+
+    from qiskit.circuit.library import Diagonal
+
+    diagonal = Diagonal([1, 1])
+    print(diagonal.num_qubits)
+
+    diagonal = Diagonal([1, 1, 1, 1])
+    print(diagonal.num_qubits)
+
+
 .. autosummary::
    :toctree: ../stubs/
    :template: autosummary/class_no_inherited_members.rst
@@ -104,18 +165,27 @@
    MCMTVChain
    Permutation
    GMS
-   MSGate
    GR
    GRX
    GRY
    GRZ
+   MCPhaseGate
+   MCXGate
+   MCXGrayCode
+   MCXRecursive
+   MCXVChain
    RVGate
    PauliGate
    LinearFunction
 
 Boolean Logic Circuits
 ======================
 
+These are :class:`~qiskit.circuit.QuantumCircuit` subclasses
+that implement boolean logic operations, such as the logical
+or of a set of qubit states.
+
+
 .. autosummary::
    :toctree: ../stubs/
    :template: autosummary/class_no_inherited_members.rst
@@ -128,6 +198,10 @@
 Basis Change Circuits
 =====================
 
+These circuits allow basis transformations of the qubit states. For example,
+in the case of the Quantum Fourier Transform (QFT), it transforms between
+the computational basis and the Fourier basis.
+
 .. autosummary::
    :toctree: ../stubs/
    :template: autosummary/class_no_inherited_members.rst
@@ -137,6 +211,9 @@
 Arithmetic Circuits
 ===================
 
+These :class:`~qiskit.circuit.QuantumCircuit`\\ s perform classical arithmetic,
+such as addition or multiplication.
+
 Amplitude Functions
 -------------------
 
@@ -209,15 +286,6 @@
 
    ExactReciprocal
 
-Amplitude Functions
-===================
-
-.. autosummary::
-   :toctree: ../stubs/
-   :template: autosummary/class_no_inherited_members.rst
-
-   LinearAmplitudeFunction
-
 Particular Quantum Circuits
 ===========================
 
@@ -240,6 +308,10 @@
 N-local circuits
 ================
 
+These :class:`~qiskit.circuit.library.BlueprintCircuit` subclasses are used
+as parameterized models (a.k.a. ansatzes or variational forms) in variational algorithms.
+They are heavily used in near-term algorithms in e.g. Chemistry, Physics or Optimization.
+
 .. autosummary::
    :toctree: ../stubs/
    :template: autosummary/class_no_inherited_members.rst
@@ -256,6 +328,9 @@
 Data encoding circuits
 ======================
 
+These :class:`~qiskit.circuit.library.BlueprintCircuit` encode classical
+data in quantum states and are used as feature maps for classification.
+
 .. autosummary::
    :toctree: ../stubs/
    :template: autosummary/class_no_inherited_members.rst
@@ -265,8 +340,38 @@
    ZZFeatureMap
    StatePreparation
 
+Template circuits
+=================
+
+Templates are functions that return circuits that compute the identity. They are used at
+circuit optimization where matching part of the template allows the compiler
+to replace the match with the inverse of the remainder from the template.
+
+In this example, the identity constant in a template is checked:
+
+.. jupyter-execute::
+
+    from qiskit.circuit.library.templates import template_nct_4b_1
+    from qiskit.quantum_info import Operator
+    import numpy as np
+
+    template = template_nct_4b_1()
+
+    identity = np.identity(2 ** len(template.qubits), dtype=complex)
+    data = Operator(template).data
+    np.allclose(data, identity)  # True, template_nct_4b_1 is the identity
+
 NCT (Not-CNOT-Toffoli) template circuits
-========================================
+----------------------------------------
+
+Template circuits for :class:`~qiskit.circuit.library.XGate`,
+:class:`~qiskit.circuit.library.CXGate`,
+and :class:`~qiskit.circuit.library.CCXGate` (Toffoli) gates.
+
+**Reference:**
+Maslov, D. and Dueck, G. W. and Miller, D. M.,
+Techniques for the synthesis of reversible Toffoli networks, 2007
+http://dx.doi.org/10.1145/1278349.1278355
 
 .. autosummary::
    :toctree: ../stubs/
@@ -295,7 +400,6 @@
    templates.nct.template_nct_7c_1
    templates.nct.template_nct_7d_1
    templates.nct.template_nct_7e_1
-   templates.nct.template_nct_2a_1
    templates.nct.template_nct_9a_1
    templates.nct.template_nct_9c_1
    templates.nct.template_nct_9c_2
@@ -321,7 +425,9 @@
    templates.nct.template_nct_9d_10
 
 Clifford template circuits
-==========================
+--------------------------
+
+Template circuits over Clifford gates.
 
 .. autosummary::
    :toctree: ../stubs/
@@ -346,7 +452,9 @@
    clifford_8_3
 
 RZXGate template circuits
-=========================
+-------------------------
+
+Template circuits with :class:`~qiskit.circuit.library.RZXGate`.
 
 .. autosummary::
    :toctree: ../stubs/
@@ -366,6 +474,7 @@
 from ..measure import Measure
 from ..reset import Reset
 
+
 from .blueprintcircuit import BlueprintCircuit
 from .generalized_gates import (
     Diagonal,