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,