High-level-synthesis for permutations

qiskit/circuit/library/generalized_gates/permutation.py

@@ -16,20 +16,20 @@
 
 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."""
+class Permutation(Gate):
+    """An gate that permutes qubits."""
 
     def __init__(
         self,
         num_qubits: int,
         pattern: Optional[List[int]] = None,
         seed: Optional[int] = None,
     ) -> None:
-        """Return an n_qubit permutation circuit implemented using SWAPs.
+        """Return a permutation gate.
 
         Args:
             num_qubits: circuit width.
@@ -50,20 +50,26 @@ def __init__(
             .. jupyter-execute::
                 :hide-code:
 
+                from qiskit.circuit.quantumcircuit import QuantumCircuit
                 from qiskit.circuit.library import Permutation
                 import qiskit.tools.jupyter
                 A = [2,4,3,0,1]
-                circuit = Permutation(5, A)
+                permutation = Permutation(5, A)
+                circuit = QuantumCircuit(5)
+                circuit.append(permutation, [0, 1, 2, 3, 4])
                 circuit.draw('mpl')
 
         Expanded Circuit:
             .. jupyter-execute::
                 :hide-code:
 
+                from qiskit.circuit.quantumcircuit import QuantumCircuit
                 from qiskit.circuit.library import Permutation
                 import qiskit.tools.jupyter
                 A = [2,4,3,0,1]
-                circuit = Permutation(5, A)
+                permutation = Permutation(5, A)
+                circuit = QuantumCircuit(5)
+                circuit.append(permutation, [0, 1, 2, 3, 4])
                 %circuit_library_info circuit.decompose()
         """
         if pattern is not None:
@@ -77,17 +83,59 @@ def __init__(
             pattern = np.arange(num_qubits)
             rng.shuffle(pattern)
 
-        name = "permutation_" + np.array_str(pattern).replace(" ", ",")
+        # This is needed to support qasm()
+        self._qasm_name = "permutation__" + "_".join([str(n) for n in pattern]) + "_"
+        self._qasm_definition = None
 
-        circuit = QuantumCircuit(num_qubits, name=name)
+        super().__init__(name="permutation", num_qubits=num_qubits, params=[pattern])
 
-        super().__init__(num_qubits, name=name)
+    def __array__(self, dtype=None):
+        """Return a numpy.array for the Permutation gate."""
+        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):
+        """Returns the inverse of the permutation."""
 
         # pylint: disable=cyclic-import
-        from qiskit.synthesis.permutation.permutation_utils import _get_ordered_swap
+        from qiskit.synthesis.permutation.permutation_utils import _inverse_pattern
+
+        return Permutation(self.num_qubits, pattern=_inverse_pattern(self.pattern))
+
+    def qasm(self):
+        """The qasm for a permutation."""
+
+        if not self._qasm_definition:
+
+            # pylint: disable=cyclic-import
+            from qiskit.synthesis.permutation.permutation_utils import _get_ordered_swap
 
-        for i, j in _get_ordered_swap(pattern):
-            circuit.swap(i, j)
+            # This qasm should be identical to the one produced when permutation
+            # was a circuit rather than a gate.
+            swaps = _get_ordered_swap(self.pattern)
+            gates_def = "".join(["swap q" + str(i) + ",q" + str(j) + "; " for i, j in swaps])
+            qubit_list = ",".join(["q" + str(n) for n in range(len(self.pattern))])
+            self._qasm_definition = (
+                "gate " + self._qasm_name + " " + qubit_list + " { " + gates_def + "}"
+            )
 
-        all_qubits = self.qubits
-        self.append(circuit.to_gate(), all_qubits)
+        return self._qasmif(self._qasm_name)

qiskit/circuit/quantumcircuit.py

@@ -1691,20 +1691,30 @@ def qasm(
                     operation = operation.copy(name=_qasm_escape_gate_name(operation.name))
 
                 # decompose gate using definitions if they are not defined in OpenQASM2
-                if (
-                    operation.name not in existing_gate_names
-                    and operation not in existing_composite_circuits
-                ):
-                    if operation.name in [
-                        operation.name for operation in existing_composite_circuits
-                    ]:
-                        # append operation id to name of operation copy to make it unique
-                        operation = operation.copy(name=f"{operation.name}_{id(operation)}")
-
-                    existing_composite_circuits.append(operation)
-                    _add_sub_instruction_to_existing_composite_circuits(
-                        operation, existing_gate_names, existing_composite_circuits
-                    )
+                if operation.name not in existing_gate_names:
+                    # If the operation has a unique qasm name, we set the name of the operation
+                    # to this qasm name. This is now the case for the permutation gate, for which
+                    # the unique qasm name is based on the permutation pattern.
+                    op_qasm_name = getattr(operation, "_qasm_name", None)
+                    if op_qasm_name:
+                        operation = operation.copy(name=op_qasm_name)
+
+                    if operation not in existing_composite_circuits:
+                        if operation.name in [
+                            operation.name for operation in existing_composite_circuits
+                        ]:
+                            # append operation id to name of operation copy to make it unique
+                            operation = operation.copy(name=f"{operation.name}_{id(operation)}")
+
+                        existing_composite_circuits.append(operation)
+
+                        # Strictly speaking, the code below does not work for operations that
+                        # do not have the "definition" method but require a complex (recursive)
+                        # "_qasm_definition". Fortunately, right now we do not have any such operations.
+                        if getattr(operation, "definition", None) is not None:
+                            _add_sub_instruction_to_existing_composite_circuits(
+                                operation, existing_gate_names, existing_composite_circuits
+                            )
 
                 # Insert qasm representation of the original instruction
                 string_temp += "{} {};\n".format(
@@ -4073,6 +4083,21 @@ def pauli(
 
         return self.append(PauliGate(pauli_string), qubits, [])
 
+    def permutation(self, pattern: List[int], qubits: Sequence[QubitSpecifier]) -> InstructionSet:
+        r"""Apply :class:`~qiskit.circuit.library.Permutation`.
+
+        Args:
+            pattern: The permutation pattern.
+            qubits: The qubit(s) to apply the gate to.
+
+        Returns:
+            A handle to the instructions created.
+        """
+        # pylint: disable=cyclic-import
+        from .library.generalized_gates.permutation import Permutation
+
+        return self.append(Permutation(len(pattern), pattern), qubits, [])
+
     def _push_scope(
         self,
         qubits: Iterable[Qubit] = (),

qiskit/qpy/binary_io/circuits.py

@@ -276,6 +276,8 @@ def _read_instruction(file_obj, circuit, registers, custom_operations, version,
                 params = [len(qargs)]
             elif gate_name in {"BreakLoopOp", "ContinueLoopOp"}:
                 params = [len(qargs), len(cargs)]
+            elif gate_name == "Permutation":
+                params = [len(qargs), params[0]]
             gate = gate_class(*params)
         gate.condition = condition_tuple
     if instruction.label_size > 0:

qiskit/synthesis/__init__.py

@@ -46,6 +46,8 @@
    :toctree: ../stubs/
 
    synth_permutation_depth_lnn_kms
+   synth_permutation_basic
+   synth_permutation_acg
 
 Clifford Synthesis
 ==================
@@ -79,8 +81,12 @@
     QDrift,
 )
 
+from .permutation import (
+    synth_permutation_depth_lnn_kms,
+    synth_permutation_basic,
+    synth_permutation_acg,
+)
 from .linear import synth_cnot_count_full_pmh, synth_cnot_depth_line_kms
-from .permutation import synth_permutation_depth_lnn_kms
 from .clifford import (
     synth_clifford_full,
     synth_clifford_ag,

qiskit/synthesis/permutation/__init__.py

@@ -14,3 +14,4 @@
 
 
 from .permutation_lnn import synth_permutation_depth_lnn_kms
+from .permutation_full import synth_permutation_basic, synth_permutation_acg

qiskit/synthesis/permutation/permutation_full.py

@@ -0,0 +1,90 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# 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.
+
+"""Synthesis algorithm for Permutation gates for full-connectivity."""
+
+from qiskit.circuit.quantumcircuit import QuantumCircuit
+from .permutation_utils import (
+    _get_ordered_swap,
+    _inverse_pattern,
+    _pattern_to_cycles,
+    _decompose_cycles,
+)
+
+
+def synth_permutation_basic(pattern):
+    """Synthesize a permutation circuit for a fully-connected
+    architecture using sorting.
+
+    More precisely, if the input permutation is a cycle of length ``m``,
+    then this creates a quantum circuit with ``m-1`` SWAPs (and of depth ``m-1``);
+    if the input  permutation consists of several disjoint cycles, then each cycle
+    is essentially treated independently.
+
+    Args:
+        pattern (Union[list[int], np.ndarray]): 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
+            position ``1``, etc.
+
+    Returns:
+        QuantumCircuit: the synthesized quantum circuit.
+    """
+    # This is the very original Qiskit algorithm for synthesizing permutations.
+
+    num_qubits = len(pattern)
+    qc = QuantumCircuit(num_qubits)
+
+    swaps = _get_ordered_swap(pattern)
+
+    for swap in swaps:
+        qc.swap(swap[0], swap[1])
+
+    return qc
+
+
+def synth_permutation_acg(pattern):
+    """Synthesize a permutation circuit for a fully-connected
+    architecture using the Alon, Chung, Graham method.
+
+    This produces a quantum circuit of depth 2 (measured in the number of SWAPs).
+
+    This implementation is based on the Theorem 2 in the paper
+    "Routing Permutations on Graphs Via Matchings" (1993),
+    available at https://www.cs.tau.ac.il/~nogaa/PDFS/r.pdf.
+
+    Args:
+        pattern (Union[list[int], np.ndarray]): 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
+            position ``1``, etc.
+
+    Returns:
+        QuantumCircuit: the synthesized quantum circuit.
+    """
+
+    num_qubits = len(pattern)
+    qc = QuantumCircuit(num_qubits)
+
+    # invert pattern (Qiskit notation is opposite)
+    cur_pattern = _inverse_pattern(pattern)
+    cycles = _pattern_to_cycles(cur_pattern)
+    swaps = _decompose_cycles(cycles)
+
+    for swap in swaps:
+        qc.swap(swap[0], swap[1])
+
+    return qc

qiskit/synthesis/permutation/permutation_utils.py

@@ -42,3 +42,32 @@ def _inverse_pattern(pattern):
     """Finds inverse of a permutation pattern."""
     b_map = {pos: idx for idx, pos in enumerate(pattern)}
     return [b_map[pos] for pos in range(len(pattern))]
+
+
+def _pattern_to_cycles(pattern):
+    """Given a permutation pattern, creates its disjoint cycle decomposition."""
+    nq = len(pattern)
+    explored = [False] * nq
+    cycles = []
+    for i in pattern:
+        cycle = []
+        while not explored[i]:
+            cycle.append(i)
+            explored[i] = True
+            i = pattern[i]
+        if len(cycle) >= 2:
+            cycles.append(cycle)
+    return cycles
+
+
+def _decompose_cycles(cycles):
+    """Given a disjoint cycle decomposition, decomposes every cycle into a SWAP
+    circuit of depth 2."""
+    swap_list = []
+    for cycle in cycles:
+        m = len(cycle)
+        for i in range((m - 1) // 2):
+            swap_list.append((cycle[i - 1], cycle[m - 3 - i]))
+        for i in range(m // 2):
+            swap_list.append((cycle[i - 1], cycle[m - 2 - i]))
+    return swap_list