qiskit 1.3.0b1__cp39-abi3-macosx_10_9_x86_64.whl

qiskit/circuit/library/generalized_gates/mcg_up_to_diagonal.py

@@ -0,0 +1,143 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2019.
+#
+# 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.
+
+# pylint: disable=unused-variable
+
+"""Multi controlled single-qubit unitary up to diagonal."""
+
+# ToDo: This code should be merged wth the implementation of MCGs
+# ToDo: (introducing a decomposition mode "up_to_diagonal").
+
+import numpy as np
+
+from qiskit.circuit import Gate
+from qiskit.circuit.quantumcircuit import QuantumRegister, QuantumCircuit
+from qiskit.circuit.exceptions import CircuitError
+from qiskit.exceptions import QiskitError
+from qiskit.quantum_info.operators.predicates import is_isometry
+
+from .uc import UCGate
+
+_EPS = 1e-10  # global variable used to chop very small numbers to zero
+
+
+class MCGupDiag(Gate):
+    r"""
+    Decomposes a multi-controlled gate :math:`U` up to a diagonal :math:`D` acting on the control
+    and target qubit (but not on the ancilla qubits), i.e., it implements a circuit corresponding to
+    a unitary :math:`U'`, such that :math:`U = D U'`.
+    """
+
+    def __init__(
+        self, gate: np.ndarray, num_controls: int, num_ancillas_zero: int, num_ancillas_dirty: int
+    ) -> None:
+        r"""
+        Args:
+            gate: :math:`2 \times 2` unitary given as a (complex) ``ndarray``.
+            num_controls: Number of control qubits.
+            num_ancillas_zero: Number of ancilla qubits that start in the state zero.
+            num_ancillas_dirty: Number of ancilla qubits that are allowed to start in an
+                arbitrary state.
+
+        Raises:
+            QiskitError: if the input format is wrong; if the array gate is not unitary
+        """
+
+        self.num_controls = num_controls
+        self.num_ancillas_zero = num_ancillas_zero
+        self.num_ancillas_dirty = num_ancillas_dirty
+        # Check if the gate has the right dimension
+        if not gate.shape == (2, 2):
+            raise QiskitError("The dimension of the controlled gate is not equal to (2,2).")
+        # Check if the single-qubit gate is unitary
+        if not is_isometry(gate, _EPS):
+            raise QiskitError("The controlled gate is not unitary.")
+        # Create new gate.
+        num_qubits = 1 + num_controls + num_ancillas_zero + num_ancillas_dirty
+        super().__init__("MCGupDiag", num_qubits, [gate])
+
+    def _define(self):
+        mcg_up_diag_circuit, _ = self._dec_mcg_up_diag()
+        gate = mcg_up_diag_circuit.to_instruction()
+        q = QuantumRegister(self.num_qubits, "q")
+        mcg_up_diag_circuit = QuantumCircuit(q, name="mcg_up_to_diagonal")
+        mcg_up_diag_circuit.append(gate, q[:])
+        self.definition = mcg_up_diag_circuit
+
+    def inverse(self, annotated: bool = False) -> Gate:
+        """Return the inverse.
+
+        Note that the resulting Gate object has an empty ``params`` property.
+        """
+        if not annotated:
+            inverse_gate = Gate(
+                name=self.name + "_dg", num_qubits=self.num_qubits, params=[]
+            )  # removing the params because arrays are deprecated
+
+            definition = QuantumCircuit(*self.definition.qregs)
+            for inst in reversed(self._definition):
+                definition._append(
+                    inst.replace(operation=inst.operation.inverse(annotated=annotated))
+                )
+            inverse_gate.definition = definition
+        else:
+            inverse_gate = super().inverse(annotated=annotated)
+        return inverse_gate
+
+    # Returns the diagonal up to which the gate is implemented.
+    def _get_diagonal(self):
+        # Important: for a control list q_controls = [q[0],...,q_[k-1]] the diagonal gate is
+        # provided in the computational basis of the qubits q[k-1],...,q[0],q_target, decreasingly
+        # ordered with respect to the significance of the qubit in the computational basis
+        _, diag = self._dec_mcg_up_diag()
+        return diag
+
+    def _dec_mcg_up_diag(self):
+        """
+        Call to create a circuit with gates that implement the MCG up to a diagonal gate.
+        Remark: The qubits the gate acts on are ordered in the following way:
+            q=[q_target,q_controls,q_ancilla_zero,q_ancilla_dirty]
+        """
+        diag = np.ones(2 ** (self.num_controls + 1)).tolist()
+        q = QuantumRegister(self.num_qubits, "q")
+        circuit = QuantumCircuit(q, name="mcg_up_to_diagonal")
+        (q_target, q_controls, q_ancillas_zero, q_ancillas_dirty) = self._define_qubit_role(q)
+        # ToDo: Keep this threshold updated such that the lowest gate count is achieved:
+        # ToDo: we implement the MCG with a UCGate up to diagonal if the number of controls is
+        # ToDo: smaller than the threshold.
+        threshold = float("inf")
+        if self.num_controls < threshold:
+            # Implement the MCG as a UCGate (up to diagonal)
+            gate_list = [np.eye(2, 2) for i in range(2**self.num_controls)]
+            gate_list[-1] = self.params[0]
+            ucg = UCGate(gate_list, up_to_diagonal=True)
+            circuit.append(ucg, [q_target] + q_controls)
+            diag = ucg._get_diagonal()
+            # else:
+            # ToDo: Use the best decomposition for MCGs up to diagonal gates here
+            # ToDo: (with all available ancillas)
+        return circuit, diag
+
+    def _define_qubit_role(self, q):
+        # Define the role of the qubits
+        q_target = q[0]
+        q_controls = q[1 : self.num_controls + 1]
+        q_ancillas_zero = q[self.num_controls + 1 : self.num_controls + 1 + self.num_ancillas_zero]
+        q_ancillas_dirty = q[self.num_controls + 1 + self.num_ancillas_zero :]
+        return q_target, q_controls, q_ancillas_zero, q_ancillas_dirty
+
+    def validate_parameter(self, parameter):
+        """Multi controlled single-qubit unitary gate parameter has to be an ndarray."""
+        if isinstance(parameter, np.ndarray):
+            return parameter
+        else:
+            raise CircuitError(f"invalid param type {type(parameter)} in gate {self.name}")

qiskit/circuit/library/generalized_gates/mcmt.py

@@ -0,0 +1,256 @@
+# 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.
+
+"""Multiple-Control, Multiple-Target Gate."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from qiskit import circuit
+from qiskit.circuit import ControlledGate, Gate, QuantumRegister, QuantumCircuit
+from qiskit.exceptions import QiskitError
+
+# pylint: disable=cyclic-import
+from ..standard_gates import XGate, YGate, ZGate, HGate, TGate, TdgGate, SGate, SdgGate
+
+
+class MCMT(QuantumCircuit):
+    """The multi-controlled multi-target gate, for an arbitrary singly controlled target gate.
+
+    For example, the H gate controlled on 3 qubits and acting on 2 target qubit is represented as:
+
+    .. parsed-literal::
+
+        ───■────
+           │
+        ───■────
+           │
+        ───■────
+        ┌──┴───┐
+        ┤0     ├
+        │  2-H │
+        ┤1     ├
+        └──────┘
+
+    This default implementations requires no ancilla qubits, by broadcasting the target gate
+    to the number of target qubits and using Qiskit's generic control routine to control the
+    broadcasted target on the control qubits. If ancilla qubits are available, a more efficient
+    variant using the so-called V-chain decomposition can be used. This is implemented in
+    :class:`~qiskit.circuit.library.MCMTVChain`.
+    """
+
+    def __init__(
+        self,
+        gate: Gate | Callable[[QuantumCircuit, circuit.Qubit, circuit.Qubit], circuit.Instruction],
+        num_ctrl_qubits: int,
+        num_target_qubits: int,
+    ) -> None:
+        """Create a new multi-control multi-target gate.
+
+        Args:
+            gate: The gate to be applied controlled on the control qubits and applied to the target
+                qubits. Can be either a Gate or a circuit method.
+                If it is a callable, it will be casted to a Gate.
+            num_ctrl_qubits: The number of control qubits.
+            num_target_qubits: The number of target qubits.
+
+        Raises:
+            AttributeError: If the gate cannot be casted to a controlled gate.
+            AttributeError: If the number of controls or targets is 0.
+        """
+        if num_ctrl_qubits == 0 or num_target_qubits == 0:
+            raise AttributeError("Need at least one control and one target qubit.")
+
+        # set the internal properties and determine the number of qubits
+        self.gate = self._identify_gate(gate)
+        self.num_ctrl_qubits = num_ctrl_qubits
+        self.num_target_qubits = num_target_qubits
+        num_qubits = num_ctrl_qubits + num_target_qubits + self.num_ancilla_qubits
+
+        # initialize the circuit object
+        super().__init__(num_qubits, name="mcmt")
+        self._label = f"{num_target_qubits}-{self.gate.name.capitalize()}"
+
+        # build the circuit
+        self._build()
+
+    def _build(self):
+        """Define the MCMT gate without ancillas."""
+        if self.num_target_qubits == 1:
+            # no broadcasting needed (makes for better circuit diagrams)
+            broadcasted_gate = self.gate
+        else:
+            broadcasted = QuantumCircuit(self.num_target_qubits, name=self._label)
+            for target in list(range(self.num_target_qubits)):
+                broadcasted.append(self.gate, [target], [])
+            broadcasted_gate = broadcasted.to_gate()
+
+        mcmt_gate = broadcasted_gate.control(self.num_ctrl_qubits)
+        self.append(mcmt_gate, self.qubits, [])
+
+    @property
+    def num_ancilla_qubits(self):
+        """Return the number of ancillas."""
+        return 0
+
+    def _identify_gate(self, gate):
+        """Case the gate input to a gate."""
+        valid_gates = {
+            "ch": HGate(),
+            "cx": XGate(),
+            "cy": YGate(),
+            "cz": ZGate(),
+            "h": HGate(),
+            "s": SGate(),
+            "sdg": SdgGate(),
+            "x": XGate(),
+            "y": YGate(),
+            "z": ZGate(),
+            "t": TGate(),
+            "tdg": TdgGate(),
+        }
+        if isinstance(gate, ControlledGate):
+            base_gate = gate.base_gate
+        elif isinstance(gate, Gate):
+            if gate.num_qubits != 1:
+                raise AttributeError("Base gate must act on one qubit only.")
+            base_gate = gate
+        elif isinstance(gate, QuantumCircuit):
+            if gate.num_qubits != 1:
+                raise AttributeError(
+                    "The circuit you specified as control gate can only have one qubit!"
+                )
+            base_gate = gate.to_gate()  # raises error if circuit contains non-unitary instructions
+        else:
+            if callable(gate):  # identify via name of the passed function
+                name = gate.__name__
+            elif isinstance(gate, str):
+                name = gate
+            else:
+                raise AttributeError(f"Invalid gate specified: {gate}")
+            base_gate = valid_gates[name]
+
+        return base_gate
+
+    def control(self, num_ctrl_qubits=1, label=None, ctrl_state=None, annotated=False):
+        """Return the controlled version of the MCMT circuit."""
+        if not annotated and ctrl_state is None:
+            gate = MCMT(self.gate, self.num_ctrl_qubits + num_ctrl_qubits, self.num_target_qubits)
+        else:
+            gate = super().control(num_ctrl_qubits, label, ctrl_state, annotated=annotated)
+        return gate
+
+    def inverse(self, annotated: bool = False):
+        """Return the inverse MCMT circuit, which is itself."""
+        return MCMT(self.gate, self.num_ctrl_qubits, self.num_target_qubits)
+
+
+class MCMTVChain(MCMT):
+    """The MCMT implementation using the CCX V-chain.
+
+    This implementation requires ancillas but is decomposed into a much shallower circuit
+    than the default implementation in :class:`~qiskit.circuit.library.MCMT`.
+
+    **Expanded Circuit:**
+
+    .. plot::
+
+       from qiskit.circuit.library import MCMTVChain, ZGate
+       from qiskit.visualization.library import _generate_circuit_library_visualization
+       circuit = MCMTVChain(ZGate(), 2, 2)
+       _generate_circuit_library_visualization(circuit.decompose())
+
+    **Examples:**
+
+        >>> from qiskit.circuit.library import HGate
+        >>> MCMTVChain(HGate(), 3, 2).draw()
+
+        q_0: ──■────────────────────────■──
+               │                        │
+        q_1: ──■────────────────────────■──
+               │                        │
+        q_2: ──┼────■──────────────■────┼──
+               │    │  ┌───┐       │    │
+        q_3: ──┼────┼──┤ H ├───────┼────┼──
+               │    │  └─┬─┘┌───┐  │    │
+        q_4: ──┼────┼────┼──┤ H ├──┼────┼──
+             ┌─┴─┐  │    │  └─┬─┘  │  ┌─┴─┐
+        q_5: ┤ X ├──■────┼────┼────■──┤ X ├
+             └───┘┌─┴─┐  │    │  ┌─┴─┐└───┘
+        q_6: ─────┤ X ├──■────■──┤ X ├─────
+                  └───┘          └───┘
+    """
+
+    def _build(self):
+        """Define the MCMT gate."""
+        control_qubits = self.qubits[: self.num_ctrl_qubits]
+        target_qubits = self.qubits[
+            self.num_ctrl_qubits : self.num_ctrl_qubits + self.num_target_qubits
+        ]
+        ancilla_qubits = self.qubits[self.num_ctrl_qubits + self.num_target_qubits :]
+
+        if len(ancilla_qubits) > 0:
+            master_control = ancilla_qubits[-1]
+        else:
+            master_control = control_qubits[0]
+
+        self._ccx_v_chain_rule(control_qubits, ancilla_qubits, reverse=False)
+        for qubit in target_qubits:
+            self.append(self.gate.control(), [master_control, qubit], [])
+        self._ccx_v_chain_rule(control_qubits, ancilla_qubits, reverse=True)
+
+    @property
+    def num_ancilla_qubits(self):
+        """Return the number of ancilla qubits required."""
+        return max(0, self.num_ctrl_qubits - 1)
+
+    def _ccx_v_chain_rule(
+        self,
+        control_qubits: QuantumRegister | list[circuit.Qubit],
+        ancilla_qubits: QuantumRegister | list[circuit.Qubit],
+        reverse: bool = False,
+    ) -> None:
+        """Get the rule for the CCX V-chain.
+
+        The CCX V-chain progressively computes the CCX of the control qubits and puts the final
+        result in the last ancillary qubit.
+
+        Args:
+            control_qubits: The control qubits.
+            ancilla_qubits: The ancilla qubits.
+            reverse: If True, compute the chain down to the qubit. If False, compute upwards.
+
+        Returns:
+            The rule for the (reversed) CCX V-chain.
+
+        Raises:
+            QiskitError: If an insufficient number of ancilla qubits was provided.
+        """
+        if len(ancilla_qubits) == 0:
+            return
+
+        if len(ancilla_qubits) < len(control_qubits) - 1:
+            raise QiskitError("Insufficient number of ancilla qubits.")
+
+        iterations = list(enumerate(range(2, len(control_qubits))))
+        if not reverse:
+            self.ccx(control_qubits[0], control_qubits[1], ancilla_qubits[0])
+            for i, j in iterations:
+                self.ccx(control_qubits[j], ancilla_qubits[i], ancilla_qubits[i + 1])
+        else:
+            for i, j in reversed(iterations):
+                self.ccx(control_qubits[j], ancilla_qubits[i], ancilla_qubits[i + 1])
+            self.ccx(control_qubits[0], control_qubits[1], ancilla_qubits[0])
+
+    def inverse(self, annotated: bool = False):
+        return MCMTVChain(self.gate, self.num_ctrl_qubits, self.num_target_qubits)

qiskit/circuit/library/generalized_gates/pauli.py

@@ -0,0 +1,85 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 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.
+
+"""
+Simulator command to perform multiple pauli gates in a single pass
+"""
+from qiskit.circuit.quantumcircuitdata import CircuitInstruction
+from qiskit.circuit.quantumregister import QuantumRegister
+from qiskit.circuit.library.standard_gates.x import XGate
+from qiskit.circuit.library.standard_gates.y import YGate
+from qiskit.circuit.library.standard_gates.z import ZGate
+
+from qiskit.circuit.gate import Gate
+from qiskit.circuit.exceptions import CircuitError
+
+
+class PauliGate(Gate):
+    r"""A multi-qubit Pauli gate.
+
+    This gate exists for optimization purposes for the
+    quantum statevector simulation, since applying multiple
+    pauli gates to different qubits at once can be done via
+    a single pass on the statevector.
+
+    The functionality is equivalent to applying
+    the pauli gates sequentially using standard Qiskit gates.
+
+    Can be applied to a :class:`~qiskit.circuit.QuantumCircuit`
+    with the :meth:`~qiskit.circuit.QuantumCircuit.pauli` method.
+    """
+
+    def __init__(self, label):
+        super().__init__("pauli", len(label), [label])
+
+    def _define(self):
+        """
+        gate pauli (p1 a1,...,pn an) { p1 a1; ... ; pn an; }
+        """
+        # pylint: disable=cyclic-import
+        from qiskit.circuit.quantumcircuit import QuantumCircuit
+
+        gates = {"X": XGate, "Y": YGate, "Z": ZGate}
+        q = QuantumRegister(len(self.params[0]), "q")
+        qc = QuantumCircuit(q, name=f"{self.name}({self.params[0]})")
+
+        paulis = self.params[0]
+        for i, p in enumerate(reversed(paulis)):
+            if p == "I":
+                continue
+            qc._append(CircuitInstruction(gates[p](), (q[i],), ()))
+        self.definition = qc
+
+    def inverse(self, annotated: bool = False):
+        r"""Return inverted pauli gate (itself)."""
+        return PauliGate(self.params[0])  # self-inverse
+
+    def __array__(self, dtype=None, copy=None):
+        """Return a Numpy.array for the pauli gate.
+        i.e. tensor product of the paulis"""
+        # pylint: disable=cyclic-import
+        from qiskit.quantum_info.operators import Pauli
+
+        return Pauli(self.params[0]).__array__(dtype=dtype, copy=copy)
+
+    def validate_parameter(self, parameter):
+        if isinstance(parameter, str):
+            if all(c in ["I", "X", "Y", "Z"] for c in parameter):
+                return parameter
+            else:
+                raise CircuitError(
+                    f"Parameter string {parameter} should contain only 'I', 'X', 'Y', 'Z' characters"
+                )
+        else:
+            raise CircuitError(
+                f"Parameter {parameter} should be a string of 'I', 'X', 'Y', 'Z' characters"
+            )

qiskit/circuit/library/generalized_gates/permutation.py

@@ -0,0 +1,192 @@
+# 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.
+
+"""Permutation circuit (the old way to specify permutations, which is required for
+backward compatibility and which will be eventually deprecated) and the permutation
+gate (the new way to specify permutations, allowing a variety of synthesis algorithms).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from qiskit.circuit.quantumcircuit import QuantumCircuit
+from qiskit.circuit.quantumcircuit import Gate
+from qiskit.circuit.exceptions import CircuitError
+
+
+class Permutation(QuantumCircuit):
+    """An n_qubit circuit that permutes qubits."""
+
+    def __init__(
+        self,
+        num_qubits: int,
+        pattern: list[int] | np.ndarray | None = None,
+        seed: int | None = None,
+    ) -> None:
+        """Return an n_qubit permutation circuit implemented using SWAPs.
+
+        Args:
+            num_qubits: circuit width.
+            pattern: permutation pattern, describing which qubits occupy the
+                positions 0, 1, 2, etc. after applying the permutation, that
+                is ``pattern[k] = m`` when the permutation maps qubit ``m``
+                to position ``k``. As an example, the pattern ``[2, 4, 3, 0, 1]``
+                means that qubit ``2`` goes to position ``0``, qubit ``4``
+                goes to the position ``1``, etc. The pattern can also be ``None``,
+                in which case a random permutation over ``num_qubits`` is
+                created.
+            seed: random seed in case a random permutation is requested.
+
+        Raises:
+            CircuitError: if permutation pattern is malformed.
+
+        Reference Circuit:
+            .. plot::
+
+               from qiskit.circuit.library import Permutation
+               A = [2,4,3,0,1]
+               circuit = Permutation(5, A)
+               circuit.draw('mpl')
+
+        Expanded Circuit:
+            .. plot::
+
+               from qiskit.circuit.library import Permutation
+               from qiskit.visualization.library import _generate_circuit_library_visualization
+               A = [2,4,3,0,1]
+               circuit = Permutation(5, A)
+               _generate_circuit_library_visualization(circuit.decompose())
+        """
+        if pattern is not None:
+            if sorted(pattern) != list(range(num_qubits)):
+                raise CircuitError(
+                    "Permutation pattern must be some ordering of 0..num_qubits-1 in a list."
+                )
+            pattern = np.array(pattern)
+        else:
+            rng = np.random.default_rng(seed)
+            pattern = np.arange(num_qubits)
+            rng.shuffle(pattern)
+
+        name = "permutation_" + np.array_str(pattern).replace(" ", ",")
+
+        super().__init__(num_qubits, name=name)
+
+        # pylint: disable=cyclic-import
+        from qiskit.synthesis.permutation import synth_permutation_basic
+
+        circuit = synth_permutation_basic(pattern)
+        circuit.name = name
+
+        all_qubits = self.qubits
+        self.append(circuit.to_gate(), all_qubits)
+
+
+class PermutationGate(Gate):
+    """A gate that permutes qubits."""
+
+    def __init__(
+        self,
+        pattern: list[int],
+    ) -> None:
+        """Return a permutation gate.
+
+        Args:
+            pattern: permutation pattern, describing which qubits occupy the
+                positions 0, 1, 2, etc. after applying the permutation, that
+                is ``pattern[k] = m`` when the permutation maps qubit ``m``
+                to position ``k``. As an example, the pattern ``[2, 4, 3, 0, 1]``
+                means that qubit ``2`` goes to position ``0``, qubit ``4``
+                goes to the position ``1``, etc.
+
+        Raises:
+            CircuitError: if permutation pattern is malformed.
+
+        Reference Circuit:
+            .. plot::
+
+                from qiskit.circuit.quantumcircuit import QuantumCircuit
+                from qiskit.circuit.library import PermutationGate
+                A = [2,4,3,0,1]
+                permutation = PermutationGate(A)
+                circuit = QuantumCircuit(5)
+                circuit.append(permutation, [0, 1, 2, 3, 4])
+                circuit.draw('mpl')
+
+        Expanded Circuit:
+            .. plot::
+
+                from qiskit.circuit.quantumcircuit import QuantumCircuit
+                from qiskit.circuit.library import PermutationGate
+                from qiskit.visualization.library import _generate_circuit_library_visualization
+                A = [2,4,3,0,1]
+                permutation = PermutationGate(A)
+                circuit = QuantumCircuit(5)
+                circuit.append(permutation, [0, 1, 2, 3, 4])
+
+                _generate_circuit_library_visualization(circuit.decompose())
+        """
+        num_qubits = len(pattern)
+        if sorted(pattern) != list(range(num_qubits)):
+            raise CircuitError(
+                "Permutation pattern must be some ordering of 0..num_qubits-1 in a list."
+            )
+        pattern = np.array(pattern)
+
+        super().__init__(name="permutation", num_qubits=num_qubits, params=[pattern])
+
+    def __array__(self, dtype=None, copy=None):
+        """Return a numpy.array for the Permutation gate."""
+        if copy is False:
+            raise ValueError("unable to avoid copy while creating an array as requested")
+
+        nq = len(self.pattern)
+        mat = np.zeros((2**nq, 2**nq), dtype=dtype)
+
+        for r in range(2**nq):
+            # convert row to bitstring, reverse, apply permutation pattern, reverse again,
+            # and convert to row
+            bit = bin(r)[2:].zfill(nq)[::-1]
+            permuted_bit = "".join([bit[j] for j in self.pattern])
+            pr = int(permuted_bit[::-1], 2)
+            mat[pr, r] = 1
+
+        return mat
+
+    def validate_parameter(self, parameter):
+        """Parameter validation."""
+        return parameter
+
+    @property
+    def pattern(self):
+        """Returns the permutation pattern defining this permutation."""
+        return self.params[0]
+
+    def inverse(self, annotated: bool = False):
+        """Returns the inverse of the permutation."""
+
+        # pylint: disable=cyclic-import
+        from qiskit.synthesis.permutation.permutation_utils import _inverse_pattern
+
+        return PermutationGate(pattern=_inverse_pattern(self.pattern))
+
+    def _qasm2_decomposition(self):
+        # pylint: disable=cyclic-import
+        from qiskit.synthesis.permutation import synth_permutation_basic
+
+        name = f"permutation__{'_'.join(str(n) for n in self.pattern)}_"
+
+        out = synth_permutation_basic(self.pattern)
+        out.name = name
+
+        return out.to_gate()