qiskit 1.3.0b1__cp39-abi3-macosx_10_9_x86_64.whl

qiskit/circuit/library/__init__.py

@@ -0,0 +1,572 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2020.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# 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.
+
+"""
+===============================================
+Circuit Library (:mod:`qiskit.circuit.library`)
+===============================================
+
+.. currentmodule:: qiskit.circuit.library
+
+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:
+
+.. plot::
+   :include-source:
+
+   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:
+
+.. code-block::
+
+    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
+
+.. parsed-literal::
+
+    [[0.+0.j 1.+0.j]
+     [1.+0.j 0.+0.j]]
+    [[0.5+0.5j 0.5-0.5j]
+     [0.5-0.5j 0.5+0.5j]]
+    [[1.+0.j 0.+0.j 0.+0.j 0.+0.j]
+     [0.+0.j 0.+0.j 0.+0.j 1.+0.j]
+     [0.+0.j 0.+0.j 1.+0.j 0.+0.j]
+     [0.+0.j 1.+0.j 0.+0.j 0.+0.j]]
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   C3XGate
+   C3SXGate
+   C4XGate
+   CCXGate
+   DCXGate
+   CHGate
+   CPhaseGate
+   CRXGate
+   CRYGate
+   CRZGate
+   CSGate
+   CSdgGate
+   CSwapGate
+   CSXGate
+   CUGate
+   CU1Gate
+   CU3Gate
+   CXGate
+   CYGate
+   CZGate
+   CCZGate
+   ECRGate
+   HGate
+   IGate
+   MSGate
+   PhaseGate
+   RCCXGate
+   RC3XGate
+   RGate
+   RXGate
+   RXXGate
+   RYGate
+   RYYGate
+   RZGate
+   RZZGate
+   RZXGate
+   XXMinusYYGate
+   XXPlusYYGate
+   SGate
+   SdgGate
+   SwapGate
+   iSwapGate
+   SXGate
+   SXdgGate
+   TGate
+   TdgGate
+   UGate
+   U1Gate
+   U2Gate
+   U3Gate
+   XGate
+   YGate
+   ZGate
+   GlobalPhaseGate
+
+Standard Directives
+===================
+
+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.
+
+* :class:`qiskit.circuit.Barrier`
+
+Standard Operations
+===================
+
+Operations are non-reversible changes in the quantum state of the circuit.
+
+* :class:`qiskit.circuit.Measure`
+* :class:`qiskit.circuit.Reset`
+
+Generalized Gates
+=================
+
+These "gates" (many are :class:`~qiskit.circuit.QuantumCircuit` subclasses) allow to
+set the amount of qubits involved at instantiation time.
+
+
+.. code-block::
+
+    from qiskit.circuit.library import Diagonal
+
+    diagonal = Diagonal([1, 1])
+    print(diagonal.num_qubits)
+
+    diagonal = Diagonal([1, 1, 1, 1])
+    print(diagonal.num_qubits)
+
+.. parsed-literal::
+
+    1
+    2
+
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   Diagonal
+   DiagonalGate
+   MCMT
+   MCMTVChain
+   Permutation
+   PermutationGate
+   GMS
+   GR
+   GRX
+   GRY
+   GRZ
+   MCPhaseGate
+   MCXGate
+   MCXGrayCode
+   MCXRecursive
+   MCXVChain
+   RVGate
+   PauliGate
+   LinearFunction
+   Isometry
+   UnitaryGate
+   UCGate
+   UCPauliRotGate
+   UCRXGate
+   UCRYGate
+   UCRZGate
+
+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
+
+   AND
+   OR
+   XOR
+   InnerProduct
+
+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
+
+   QFT
+   QFTGate
+
+Arithmetic Circuits
+===================
+
+These :class:`~qiskit.circuit.QuantumCircuit`\\ s perform classical arithmetic,
+such as addition or multiplication.
+
+Amplitude Functions
+-------------------
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   LinearAmplitudeFunction
+
+Functional Pauli Rotations
+--------------------------
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   FunctionalPauliRotations
+   LinearPauliRotations
+   PolynomialPauliRotations
+   PiecewiseLinearPauliRotations
+   PiecewisePolynomialPauliRotations
+   PiecewiseChebyshev
+
+Adders
+------
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   DraperQFTAdder
+   CDKMRippleCarryAdder
+   VBERippleCarryAdder
+   WeightedAdder
+
+Multipliers
+-----------
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   HRSCumulativeMultiplier
+   RGQFTMultiplier
+
+Comparators
+-----------
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   IntegerComparator
+
+Functions on binary variables
+-----------------------------
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   QuadraticForm
+
+Other arithmetic functions
+--------------------------
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   ExactReciprocal
+
+Particular Quantum Circuits
+===========================
+
+.. autosummary::
+   :toctree: ../stubs/
+   :template: autosummary/class_no_inherited_members.rst
+
+   FourierChecking
+   GraphState
+   HiddenLinearFunction
+   IQP
+   QuantumVolume
+   PhaseEstimation
+   GroverOperator
+   PhaseOracle
+   PauliEvolutionGate
+   HamiltonianGate
+   UnitaryOverlap
+
+
+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
+
+   NLocal
+   TwoLocal
+   PauliTwoDesign
+   RealAmplitudes
+   EfficientSU2
+   EvolvedOperatorAnsatz
+   ExcitationPreserving
+   QAOAAnsatz
+
+
+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
+
+   PauliFeatureMap
+   ZFeatureMap
+   ZZFeatureMap
+   StatePreparation
+   Initialize
+
+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:
+
+.. code-block::
+
+    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
+
+.. currentmodule:: qiskit.circuit.library.templates.nct
+.. autofunction:: template_nct_2a_1
+.. autofunction:: template_nct_2a_2
+.. autofunction:: template_nct_2a_3
+.. autofunction:: template_nct_4a_1
+.. autofunction:: template_nct_4a_2
+.. autofunction:: template_nct_4a_3
+.. autofunction:: template_nct_4b_1
+.. autofunction:: template_nct_4b_2
+.. autofunction:: template_nct_5a_1
+.. autofunction:: template_nct_5a_2
+.. autofunction:: template_nct_5a_3
+.. autofunction:: template_nct_5a_4
+.. autofunction:: template_nct_6a_1
+.. autofunction:: template_nct_6a_2
+.. autofunction:: template_nct_6a_3
+.. autofunction:: template_nct_6a_4
+.. autofunction:: template_nct_6b_1
+.. autofunction:: template_nct_6b_2
+.. autofunction:: template_nct_6c_1
+.. autofunction:: template_nct_7a_1
+.. autofunction:: template_nct_7b_1
+.. autofunction:: template_nct_7c_1
+.. autofunction:: template_nct_7d_1
+.. autofunction:: template_nct_7e_1
+.. autofunction:: template_nct_9a_1
+.. autofunction:: template_nct_9c_1
+.. autofunction:: template_nct_9c_2
+.. autofunction:: template_nct_9c_3
+.. autofunction:: template_nct_9c_4
+.. autofunction:: template_nct_9c_5
+.. autofunction:: template_nct_9c_6
+.. autofunction:: template_nct_9c_7
+.. autofunction:: template_nct_9c_8
+.. autofunction:: template_nct_9c_9
+.. autofunction:: template_nct_9c_10
+.. autofunction:: template_nct_9c_11
+.. autofunction:: template_nct_9c_12
+.. autofunction:: template_nct_9d_1
+.. autofunction:: template_nct_9d_2
+.. autofunction:: template_nct_9d_3
+.. autofunction:: template_nct_9d_4
+.. autofunction:: template_nct_9d_5
+.. autofunction:: template_nct_9d_6
+.. autofunction:: template_nct_9d_7
+.. autofunction:: template_nct_9d_8
+.. autofunction:: template_nct_9d_9
+.. autofunction:: template_nct_9d_10
+.. currentmodule:: qiskit.circuit.library
+
+Clifford template circuits
+--------------------------
+
+Template circuits over Clifford gates.
+
+.. autofunction:: clifford_2_1
+.. autofunction:: clifford_2_2
+.. autofunction:: clifford_2_3
+.. autofunction:: clifford_2_4
+.. autofunction:: clifford_3_1
+.. autofunction:: clifford_4_1
+.. autofunction:: clifford_4_2
+.. autofunction:: clifford_4_3
+.. autofunction:: clifford_4_4
+.. autofunction:: clifford_5_1
+.. autofunction:: clifford_6_1
+.. autofunction:: clifford_6_2
+.. autofunction:: clifford_6_3
+.. autofunction:: clifford_6_4
+.. autofunction:: clifford_6_5
+.. autofunction:: clifford_8_1
+.. autofunction:: clifford_8_2
+.. autofunction:: clifford_8_3
+
+RZXGate template circuits
+-------------------------
+
+Template circuits with :class:`~qiskit.circuit.library.RZXGate`.
+
+.. autofunction:: rzx_yz
+.. autofunction:: rzx_xz
+.. autofunction:: rzx_cy
+.. autofunction:: rzx_zz1
+.. autofunction:: rzx_zz2
+.. autofunction:: rzx_zz3
+
+"""
+
+from .standard_gates import *
+from .templates import *
+from ..barrier import Barrier
+from ..measure import Measure
+from ..reset import Reset
+
+
+from .blueprintcircuit import BlueprintCircuit
+from .generalized_gates import (
+    Diagonal,
+    DiagonalGate,
+    MCMT,
+    MCMTVChain,
+    Permutation,
+    PermutationGate,
+    GMS,
+    MSGate,
+    GR,
+    GRX,
+    GRY,
+    GRZ,
+    RVGate,
+    PauliGate,
+    LinearFunction,
+    Isometry,
+    UnitaryGate,
+    UCGate,
+    UCPauliRotGate,
+    UCRXGate,
+    UCRYGate,
+    UCRZGate,
+)
+from .pauli_evolution import PauliEvolutionGate
+from .hamiltonian_gate import HamiltonianGate
+from .boolean_logic import (
+    AND,
+    OR,
+    XOR,
+    InnerProduct,
+)
+from .basis_change import QFT, QFTGate
+from .arithmetic import (
+    FunctionalPauliRotations,
+    LinearPauliRotations,
+    PiecewiseLinearPauliRotations,
+    PiecewisePolynomialPauliRotations,
+    PolynomialPauliRotations,
+    IntegerComparator,
+    WeightedAdder,
+    QuadraticForm,
+    LinearAmplitudeFunction,
+    VBERippleCarryAdder,
+    CDKMRippleCarryAdder,
+    DraperQFTAdder,
+    PiecewiseChebyshev,
+    HRSCumulativeMultiplier,
+    RGQFTMultiplier,
+    ExactReciprocal,
+)
+
+from .n_local import (
+    NLocal,
+    TwoLocal,
+    PauliTwoDesign,
+    RealAmplitudes,
+    EfficientSU2,
+    EvolvedOperatorAnsatz,
+    ExcitationPreserving,
+    QAOAAnsatz,
+)
+from .data_preparation import (
+    PauliFeatureMap,
+    ZFeatureMap,
+    ZZFeatureMap,
+    StatePreparation,
+    Initialize,
+)
+from .quantum_volume import QuantumVolume
+from .fourier_checking import FourierChecking
+from .graph_state import GraphState
+from .hidden_linear_function import HiddenLinearFunction
+from .iqp import IQP
+from .phase_estimation import PhaseEstimation
+from .grover_operator import GroverOperator
+from .phase_oracle import PhaseOracle
+from .overlap import UnitaryOverlap

qiskit/circuit/library/arithmetic/__init__.py

@@ -0,0 +1,27 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# 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.
+
+"""The arithmetic circuit library."""
+
+from .functional_pauli_rotations import FunctionalPauliRotations
+from .integer_comparator import IntegerComparator
+from .linear_pauli_rotations import LinearPauliRotations
+from .piecewise_linear_pauli_rotations import PiecewiseLinearPauliRotations
+from .piecewise_polynomial_pauli_rotations import PiecewisePolynomialPauliRotations
+from .polynomial_pauli_rotations import PolynomialPauliRotations
+from .weighted_adder import WeightedAdder
+from .quadratic_form import QuadraticForm
+from .linear_amplitude_function import LinearAmplitudeFunction
+from .adders import VBERippleCarryAdder, CDKMRippleCarryAdder, DraperQFTAdder
+from .piecewise_chebyshev import PiecewiseChebyshev
+from .multipliers import HRSCumulativeMultiplier, RGQFTMultiplier
+from .exact_reciprocal import ExactReciprocal

qiskit/circuit/library/arithmetic/adders/__init__.py

@@ -0,0 +1,17 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# 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.
+
+"""The adder circuit library."""
+
+from .cdkm_ripple_carry_adder import CDKMRippleCarryAdder
+from .draper_qft_adder import DraperQFTAdder
+from .vbe_ripple_carry_adder import VBERippleCarryAdder

qiskit/circuit/library/arithmetic/adders/adder.py

@@ -0,0 +1,58 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# 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.
+
+"""Compute the sum of two equally sized qubit registers."""
+
+from qiskit.circuit import QuantumCircuit
+
+
+class Adder(QuantumCircuit):
+    r"""Compute the sum of two equally sized qubit registers.
+
+    For two registers :math:`|a\rangle_n` and :math:|b\rangle_n` with :math:`n` qubits each, an
+    adder performs the following operation
+
+    .. math::
+
+        |a\rangle_n |b\rangle_n \mapsto |a\rangle_n |a + b\rangle_{n + 1}.
+
+    The quantum register :math:`|a\rangle_n` (and analogously :math:`|b\rangle_n`)
+
+    .. math::
+
+        |a\rangle_n = |a_0\rangle \otimes \cdots \otimes |a_{n - 1}\rangle,
+
+    for :math:`a_i \in \{0, 1\}`, is associated with the integer value
+
+    .. math::
+
+        a = 2^{0}a_{0} + 2^{1}a_{1} + \cdots + 2^{n - 1}a_{n - 1}.
+
+    """
+
+    def __init__(self, num_state_qubits: int, name: str = "Adder") -> None:
+        """
+        Args:
+            num_state_qubits: The number of qubits in each of the registers.
+            name: The name of the circuit.
+        """
+        super().__init__(name=name)
+        self._num_state_qubits = num_state_qubits
+
+    @property
+    def num_state_qubits(self) -> int:
+        """The number of state qubits, i.e. the number of bits in each input register.
+
+        Returns:
+            The number of state qubits.
+        """
+        return self._num_state_qubits