Merge branch 'main' into drop-base-backend

Cargo.toml

@@ -20,7 +20,7 @@ ahash = "0.7.6"
 num-complex = "0.4"
 
 [dependencies.pyo3]
-version = "0.16.3"
+version = "0.16.4"
 features = ["extension-module", "hashbrown", "num-complex"]
 
 [dependencies.ndarray]

qiskit/algorithms/amplitude_amplifiers/grover.py

@@ -29,6 +29,14 @@
 class Grover(AmplitudeAmplifier):
     r"""Grover's Search algorithm.
 
+    .. note::
+
+        If you want to learn more about the theory behind Grover's Search algorithm, check
+        out the `Qiskit Textbook <https://qiskit.org/textbook/ch-algorithms/grover.html>`_.
+        or the `Qiskit Tutorials
+        <https://qiskit.org/documentation/tutorials/algorithms/07_grover_examples.html>`_
+        for more concrete how-to examples.
+
     Grover's Search [1, 2] is a well known quantum algorithm that can be used for
     searching through unstructured collections of records for particular targets
     with quadratic speedup compared to classical algorithms.
@@ -97,7 +105,6 @@ class Grover(AmplitudeAmplifier):
         [3]: Brassard, G., Hoyer, P., Mosca, M., & Tapp, A. (2000).
             Quantum Amplitude Amplification and Estimation.
             `arXiv:quant-ph/0005055 <http://arxiv.org/abs/quant-ph/0005055>`_.
-
     """
 
     def __init__(

qiskit/circuit/__init__.py

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

qiskit/circuit/instruction.py

@@ -69,6 +69,7 @@ def __init__(self, name, num_qubits, num_clbits, params, duration=None, unit="dt
 
         Raises:
             CircuitError: when the register is not in the correct format.
+            TypeError: when the optional label is provided, but it is not a string.
         """
         if not isinstance(num_qubits, int) or not isinstance(num_clbits, int):
             raise CircuitError("num_qubits and num_clbits must be integer.")
@@ -86,6 +87,8 @@ def __init__(self, name, num_qubits, num_clbits, params, duration=None, unit="dt
         #       already set is a temporary work around that can be removed after
         #       the next stable qiskit-aer release
         if not hasattr(self, "_label"):
+            if label is not None and not isinstance(label, str):
+                raise TypeError("label expects a string or None")
             self._label = label
         # tuple (ClassicalRegister, int), tuple (Clbit, bool) or tuple (Clbit, int)
         # when the instruction has a conditional ("if")

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,