qiskit 2.0.3__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/circuit/library/generalized_gates/isometry.py

@@ -0,0 +1,370 @@
+# 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=invalid-name
+# pylint: disable=unused-variable
+# pylint: disable=missing-param-doc
+# pylint: disable=missing-type-doc
+
+"""
+Generic isometries from m to n qubits.
+"""
+
+from __future__ import annotations
+
+import math
+import numpy as np
+from qiskit.circuit.exceptions import CircuitError
+from qiskit.circuit.instruction import Instruction
+from qiskit.circuit.quantumcircuit import QuantumCircuit
+from qiskit.circuit import QuantumRegister
+from qiskit.exceptions import QiskitError
+from qiskit.quantum_info.operators.predicates import is_isometry
+from qiskit._accelerate import isometry as isometry_rs
+
+from .diagonal import DiagonalGate
+from .uc import UCGate
+from .mcg_up_to_diagonal import MCGupDiag
+
+_EPS = 1e-10  # global variable used to chop very small numbers to zero
+
+
+class Isometry(Instruction):
+    r"""Decomposition of arbitrary isometries from :math:`m` to :math:`n` qubits.
+
+    In particular, this allows to decompose unitaries (m=n) and to do state preparation (:math:`m=0`).
+
+    The decomposition is based on [1].
+
+    References:
+        1. Iten et al., Quantum circuits for isometries (2016).
+           `Phys. Rev. A 93, 032318
+           <https://journals.aps.org/pra/abstract/10.1103/PhysRevA.93.032318>`__.
+
+    """
+
+    # Notation: In the following decomposition we label the qubit by
+    # 0 -> most significant one
+    # ...
+    # n -> least significant one
+    # finally, we convert the labels back to the qubit numbering used in Qiskit
+    # (using: _get_qubits_by_label)
+
+    def __init__(
+        self,
+        isometry: np.ndarray,
+        num_ancillas_zero: int,
+        num_ancillas_dirty: int,
+        epsilon: float = _EPS,
+    ) -> None:
+        r"""
+        Args:
+            isometry: An isometry from :math:`m` to :math`n` qubits, i.e., a complex
+                ``np.ndarray`` of dimension :math:`2^n \times 2^m` with orthonormal columns (given
+                in the computational basis specified by the order of the ancillas
+                and the input qubits, where the ancillas are considered to be more
+                significant than the input qubits).
+            num_ancillas_zero: Number of additional ancillas that start in the state :math:`|0\rangle`
+                (the :math:`n-m` ancillas required for providing the output of the isometry are
+                not accounted for here).
+            num_ancillas_dirty: Number of additional ancillas that start in an arbitrary state.
+            epsilon: Error tolerance of calculations.
+        """
+        # Convert to numpy array in case not already an array
+        isometry = np.array(isometry, dtype=complex)
+
+        # change a row vector to a column vector (in the case of state preparation)
+        if len(isometry.shape) == 1:
+            isometry = isometry.reshape(isometry.shape[0], 1)
+
+        self.iso_data = isometry
+
+        self.num_ancillas_zero = num_ancillas_zero
+        self.num_ancillas_dirty = num_ancillas_dirty
+        self._inverse = None
+        self._epsilon = epsilon
+
+        # Check if the isometry has the right dimension and if the columns are orthonormal
+        n = math.log2(isometry.shape[0])
+        m = math.log2(isometry.shape[1])
+        if not n.is_integer() or n < 0:
+            raise QiskitError(
+                "The number of rows of the isometry is not a non negative power of 2."
+            )
+        if not m.is_integer() or m < 0:
+            raise QiskitError(
+                "The number of columns of the isometry is not a non negative power of 2."
+            )
+        if m > n:
+            raise QiskitError(
+                "The input matrix has more columns than rows and hence it can't be an isometry."
+            )
+        if not is_isometry(isometry, self._epsilon):
+            raise QiskitError(
+                "The input matrix has non orthonormal columns and hence it is not an isometry."
+            )
+
+        num_qubits = int(n) + num_ancillas_zero + num_ancillas_dirty
+
+        super().__init__("isometry", num_qubits, 0, [isometry])
+
+    def _define(self):
+        # TODO The inverse().inverse() is because there is code to uncompute (_gates_to_uncompute)
+        #  an isometry, but not for generating its decomposition. It would be cheaper to do the
+        #  later here instead.
+        gate = self.inv_gate()
+        gate = gate.inverse()
+        q = QuantumRegister(self.num_qubits, "q")
+        iso_circuit = QuantumCircuit(q, name="isometry")
+        iso_circuit.append(gate, q[:])
+        self.definition = iso_circuit
+
+    def inverse(self, annotated: bool = False):
+        self.params = []
+        inv = super().inverse(annotated=annotated)
+        self.params = [self.iso_data]
+        return inv
+
+    def _gates_to_uncompute(self):
+        """
+        Call to create a circuit with gates that take the desired isometry to the first 2^m columns
+         of the 2^n*2^n identity matrix (see https://arxiv.org/abs/1501.06911)
+        """
+        q = QuantumRegister(self.num_qubits, "q")
+        circuit = QuantumCircuit(q, name="isometry_to_uncompute")
+        (
+            q_input,
+            q_ancillas_for_output,
+            q_ancillas_zero,
+            q_ancillas_dirty,
+        ) = self._define_qubit_role(q)
+        # Copy the isometry (this is computationally expensive for large isometries but guarantees
+        # to keep a copyof the input isometry)
+        remaining_isometry = self.iso_data.astype(complex)  # note: "astype" does copy the isometry
+        diag = []
+        m = int(math.log2(self.iso_data.shape[1]))
+        # Decompose the column with index column_index and attache the gate to the circuit object.
+        # Return the isometry that is left to decompose, where the columns up to index column_index
+        # correspond to the firstfew columns of the identity matrix up to diag, and hence we only
+        # have to save a list containing them.
+        for column_index in range(2**m):
+            remaining_isometry, diag = self._decompose_column(
+                circuit, q, diag, remaining_isometry, column_index
+            )
+            # extract phase of the state that was sent to the basis state ket(column_index)
+            diag.append(remaining_isometry[column_index, 0])
+            # remove first column (which is now stored in diag)
+            remaining_isometry = remaining_isometry[:, 1:]
+        if len(diag) > 1 and not isometry_rs.diag_is_identity_up_to_global_phase(
+            diag, self._epsilon
+        ):
+            diagonal = DiagonalGate(np.conj(diag))
+            circuit.append(diagonal, q_input)
+        return circuit
+
+    def _decompose_column(self, circuit, q, diag, remaining_isometry, column_index):
+        """
+        Decomposes the column with index column_index.
+        """
+        n = int(math.log2(self.iso_data.shape[0]))
+        for s in range(n):
+            remaining_isometry, diag = self._disentangle(
+                circuit, q, diag, remaining_isometry, column_index, s
+            )
+        return remaining_isometry, diag
+
+    def _disentangle(self, circuit, q, diag, remaining_isometry, column_index, s):
+        """
+        Disentangle the s-th significant qubit (starting with s = 0) into the zero or the one state
+        (dependent on column_index)
+        """
+        # To shorten the notation, we introduce:
+        k = column_index
+        # k_prime is the index of the column with index column_index in the remaining isometry
+        # (note that we remove columns of the isometry during the procedure for efficiency)
+        k_prime = 0
+        v = remaining_isometry
+        n = int(math.log2(self.iso_data.shape[0]))
+
+        # MCG to set one entry to zero (preparation for disentangling with UCGate):
+        index1 = 2 * isometry_rs.a(k, s + 1) * 2**s + isometry_rs.b(k, s + 1)
+        index2 = (2 * isometry_rs.a(k, s + 1) + 1) * 2**s + isometry_rs.b(k, s + 1)
+        target_label = n - s - 1
+        # Check if a MCG is required
+        if (
+            isometry_rs.k_s(k, s) == 0
+            and isometry_rs.b(k, s + 1) != 0
+            and np.abs(v[index2, k_prime]) > self._epsilon
+        ):
+            # Find the MCG, decompose it and apply it to the remaining isometry
+            gate = isometry_rs.reverse_qubit_state(
+                [v[index1, k_prime], v[index2, k_prime]], 0, self._epsilon
+            )
+            control_labels = [
+                i
+                for i, x in enumerate(_get_binary_rep_as_list(k, n))
+                if x == 1 and i != target_label
+            ]
+            diagonal_mcg = self._append_mcg_up_to_diagonal(
+                circuit, q, gate, control_labels, target_label
+            )
+            # apply the MCG to the remaining isometry
+            v = isometry_rs.apply_multi_controlled_gate(v, control_labels, target_label, gate)
+            # correct for the implementation "up to diagonal"
+            diag_mcg_inverse = np.conj(diagonal_mcg).astype(complex, copy=False)
+            v = isometry_rs.apply_diagonal_gate(
+                v, control_labels + [target_label], diag_mcg_inverse
+            )
+            # update the diag according to the applied diagonal gate
+            diag = isometry_rs.apply_diagonal_gate_to_diag(
+                diag, control_labels + [target_label], diag_mcg_inverse, n
+            )
+
+        # UCGate to disentangle a qubit:
+        # Find the UCGate, decompose it and apply it to the remaining isometry
+        single_qubit_gates = self._find_squs_for_disentangling(v, k, s)
+        if not isometry_rs.ucg_is_identity_up_to_global_phase(single_qubit_gates, self._epsilon):
+            control_labels = list(range(target_label))
+            diagonal_ucg = self._append_ucg_up_to_diagonal(
+                circuit, q, single_qubit_gates, control_labels, target_label
+            )
+            # merge the diagonal into the UCGate for efficient application of both together
+            diagonal_ucg_inverse = np.conj(diagonal_ucg).astype(complex, copy=False)
+            single_qubit_gates = isometry_rs.merge_ucgate_and_diag(
+                single_qubit_gates, diagonal_ucg_inverse
+            )
+            # apply the UCGate (with the merged diagonal gate) to the remaining isometry
+            v = isometry_rs.apply_ucg(v, len(control_labels), single_qubit_gates)
+            # update the diag according to the applied diagonal gate
+            diag = isometry_rs.apply_diagonal_gate_to_diag(
+                diag, control_labels + [target_label], diagonal_ucg_inverse, n
+            )
+            # # correct for the implementation "up to diagonal"
+            # diag_inv = np.conj(diag).tolist()
+            # _apply_diagonal_gate(v, control_labels + [target_label], diag_inv)
+        return v, diag
+
+    # This method finds the single-qubit gates for a UCGate to disentangle a qubit:
+    # we consider the n-qubit state v[:,0] starting with k zeros (in the computational basis).
+    # The qubit with label n-s-1 is disentangled into the basis state k_s(k,s).
+    def _find_squs_for_disentangling(self, v, k, s):
+        res = isometry_rs.find_squs_for_disentangling(
+            v, k, s, self._epsilon, n=int(math.log2(self.iso_data.shape[0]))
+        )
+        return res
+
+    # Append a UCGate up to diagonal to the circuit circ.
+    def _append_ucg_up_to_diagonal(self, circ, q, single_qubit_gates, control_labels, target_label):
+        (
+            q_input,
+            q_ancillas_for_output,
+            q_ancillas_zero,
+            q_ancillas_dirty,
+        ) = self._define_qubit_role(q)
+        n = int(math.log2(self.iso_data.shape[0]))
+        qubits = q_input + q_ancillas_for_output
+        # Note that we have to reverse the control labels, since controls are provided by
+        # increasing qubit number toa UCGate by convention
+        control_qubits = _reverse_qubit_oder(_get_qubits_by_label(control_labels, qubits, n))
+        target_qubit = _get_qubits_by_label([target_label], qubits, n)[0]
+        ucg = UCGate(single_qubit_gates, up_to_diagonal=True)
+        circ.append(ucg, [target_qubit] + control_qubits)
+        return ucg._get_diagonal()
+
+    # Append a MCG up to diagonal to the circuit circ. The diagonal should only act on the control
+    # and target qubits and not on the ancillas. In principle, it would be allowed to act on the
+    # dirty ancillas on which we perform the isometry (i.e., on the qubits listed in "qubits"
+    # below). But for simplicity, the current code version ignores this future optimization
+    # possibility.
+    def _append_mcg_up_to_diagonal(self, circ, q, gate, control_labels, target_label):
+        (
+            q_input,
+            q_ancillas_for_output,
+            q_ancillas_zero,
+            q_ancillas_dirty,
+        ) = self._define_qubit_role(q)
+        n = int(math.log2(self.iso_data.shape[0]))
+        qubits = q_input + q_ancillas_for_output
+        control_qubits = _reverse_qubit_oder(_get_qubits_by_label(control_labels, qubits, n))
+        target_qubit = _get_qubits_by_label([target_label], qubits, n)[0]
+        # The qubits on which we neither act nor control on with the MCG, can be used
+        # as dirty ancillas
+        ancilla_dirty_labels = [i for i in range(n) if i not in control_labels + [target_label]]
+        ancillas_dirty = (
+            _reverse_qubit_oder(_get_qubits_by_label(ancilla_dirty_labels, qubits, n))
+            + q_ancillas_dirty
+        )
+        mcg_up_to_diag = MCGupDiag(
+            gate, len(control_qubits), len(q_ancillas_zero), len(ancillas_dirty)
+        )
+        circ.append(
+            mcg_up_to_diag, [target_qubit] + control_qubits + q_ancillas_zero + ancillas_dirty
+        )
+        return mcg_up_to_diag._get_diagonal()
+
+    def _define_qubit_role(self, q):
+
+        n = int(math.log2(self.iso_data.shape[0]))
+        m = int(math.log2(self.iso_data.shape[1]))
+
+        # Define the role of the qubits
+        q_input = q[:m]
+        q_ancillas_for_output = q[m:n]
+        q_ancillas_zero = q[n : n + self.num_ancillas_zero]
+        q_ancillas_dirty = q[n + self.num_ancillas_zero :]
+        return q_input, q_ancillas_for_output, q_ancillas_zero, q_ancillas_dirty
+
+    def validate_parameter(self, parameter):
+        """Isometry parameter has to be an ndarray."""
+        if isinstance(parameter, np.ndarray):
+            return parameter
+        if isinstance(parameter, (list, int)):
+            return parameter
+        else:
+            raise CircuitError(f"invalid param type {type(parameter)} for gate {self.name}")
+
+    def inv_gate(self):
+        """Return the adjoint of the unitary."""
+        if self._inverse is None:
+            # call to generate the circuit that takes the isometry to the first 2^m columns
+            # of the 2^n identity matrix
+            iso_circuit = self._gates_to_uncompute()
+            # invert the circuit to create the circuit implementing the isometry
+            self._inverse = iso_circuit.to_instruction()
+        return self._inverse
+
+
+# Get the qubits in the list qubits corresponding to the labels listed in labels. The total number
+# of qubits is given by num_qubits (and determines the convention for the qubit labeling)
+
+# Remark: We labeled the qubits with decreasing significance. So we have to transform the labels to
+# be compatible with the standard convention of Qiskit.
+
+
+def _get_qubits_by_label(labels, qubits, num_qubits):
+    return [qubits[num_qubits - label - 1] for label in labels]
+
+
+def _reverse_qubit_oder(qubits):
+    return list(reversed(qubits))
+
+
+# Convert list of binary digits to integer
+
+
+def _get_binary_rep_as_list(n, num_digits):
+    binary_string = np.binary_repr(n).zfill(num_digits)
+    binary = []
+    for line in binary_string:
+        for c in line:
+            binary.append(int(c))
+    return binary[-num_digits:]

qiskit/circuit/library/generalized_gates/linear_function.py

@@ -0,0 +1,318 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2024.
+#
+# 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.
+
+"""Linear Function."""
+
+from __future__ import annotations
+import numpy as np
+from qiskit.circuit.quantumcircuit import QuantumCircuit, Gate
+from qiskit.circuit.exceptions import CircuitError
+from qiskit.circuit.library.generalized_gates.permutation import PermutationGate
+from qiskit.utils.deprecation import deprecate_func
+
+# pylint: disable=cyclic-import
+from qiskit.quantum_info import Clifford
+
+
+class LinearFunction(Gate):
+    r"""A linear reversible circuit on n qubits.
+
+    Internally, a linear function acting on n qubits is represented
+    as a n x n matrix of 0s and 1s in numpy array format.
+
+    A linear function can be synthesized into CX and SWAP gates using the Patel–Markov–Hayes
+    algorithm, as implemented in :func:`~qiskit.synthesis.synth_cnot_count_full_pmh`
+    based on reference [1].
+
+    For efficiency, the internal n x n matrix is stored in the format expected
+    by cnot_synth, which is the big-endian (and not the little-endian) bit-ordering convention.
+
+    **Example:** the circuit
+
+    .. code-block:: text
+
+        q_0: ──■──
+             ┌─┴─┐
+        q_1: ┤ X ├
+             └───┘
+        q_2: ─────
+
+    is represented by a 3x3 linear matrix
+
+    .. math::
+
+            \begin{pmatrix}
+                1 & 0 & 0 \\
+                1 & 1 & 0 \\
+                0 & 0 & 1
+            \end{pmatrix}
+
+
+    **References:**
+
+    [1] Ketan N. Patel, Igor L. Markov, and John P. Hayes,
+    Optimal synthesis of linear reversible circuits,
+    Quantum Inf. Comput. 8(3) (2008).
+    `Online at umich.edu. <https://web.eecs.umich.edu/~imarkov/pubs/jour/qic08-cnot.pdf>`_
+    """
+
+    def __init__(
+        self,
+        linear: (
+            list[list[bool]]
+            | np.ndarray[bool]
+            | QuantumCircuit
+            | LinearFunction
+            | PermutationGate
+            | Clifford
+        ),
+        validate_input: bool = False,
+    ) -> None:
+        """Create a new linear function.
+
+        Args:
+            linear: data from which a linear function can be constructed. It can be either a
+                nxn matrix (describing the linear transformation), a permutation (which is a
+                special case of a linear function), another linear function, a clifford (when
+                it corresponds to a linear function), or a quantum circuit composed of
+                linear gates (CX and SWAP) and other objects described above, including
+                nested subcircuits.
+
+            validate_input: if True, performs more expensive input validation checks,
+                such as checking that a given n x n matrix is invertible.
+
+        Raises:
+            CircuitError: if the input is invalid:
+                either the input matrix is not square or not invertible,
+                or the input quantum circuit contains non-linear objects
+                (for example, a Hadamard gate, or a Clifford that does
+                not correspond to a linear function).
+        """
+
+        original_circuit = None
+
+        if isinstance(linear, (list, np.ndarray)):
+            # Normalize to numpy array (coercing entries to 0s and 1s)
+            try:
+                linear = np.array(linear, dtype=bool, copy=True)
+            except ValueError:
+                raise CircuitError(
+                    "A linear function must be represented by a square matrix."
+                ) from None
+
+            # Check that the matrix is square
+            if len(linear.shape) != 2 or linear.shape[0] != linear.shape[1]:
+                raise CircuitError("A linear function must be represented by a square matrix.")
+
+            # Optionally, check that the matrix is invertible
+            if validate_input:
+                from qiskit.synthesis.linear import check_invertible_binary_matrix
+
+                if not check_invertible_binary_matrix(linear):
+                    raise CircuitError(
+                        "A linear function must be represented by an invertible matrix."
+                    )
+
+        elif isinstance(linear, QuantumCircuit):
+            # The following function will raise a CircuitError if there are nonlinear gates.
+            original_circuit = linear
+            linear = LinearFunction._circuit_to_mat(linear)
+
+        elif isinstance(linear, LinearFunction):
+            linear = linear.linear.copy()
+
+        elif isinstance(linear, PermutationGate):
+            linear = LinearFunction._permutation_to_mat(linear)
+
+        elif isinstance(linear, Clifford):
+            # The following function will raise a CircuitError if clifford does not correspond
+            # to a linear function.
+            linear = LinearFunction._clifford_to_mat(linear)
+
+        # Note: if we wanted, we could also try to construct a linear function from a
+        # general operator, by first attempting to convert it to clifford, and then to
+        # a linear function.
+
+        else:
+            raise CircuitError("A linear function cannot be successfully constructed.")
+
+        super().__init__(
+            name="linear_function", num_qubits=len(linear), params=[linear, original_circuit]
+        )
+
+    @staticmethod
+    def _circuit_to_mat(qc: QuantumCircuit):
+        """This creates a nxn matrix corresponding to the given quantum circuit."""
+        nq = qc.num_qubits
+        mat = np.eye(nq, nq, dtype=bool)
+
+        for instruction in qc.data:
+            if instruction.operation.name in ("barrier", "delay"):
+                # can be ignored
+                continue
+            if instruction.operation.name == "cx":
+                # implemented directly
+                cb = qc.find_bit(instruction.qubits[0]).index
+                tb = qc.find_bit(instruction.qubits[1]).index
+                mat[tb, :] = (mat[tb, :]) ^ (mat[cb, :])
+                continue
+            if instruction.operation.name == "swap":
+                # implemented directly
+                cb = qc.find_bit(instruction.qubits[0]).index
+                tb = qc.find_bit(instruction.qubits[1]).index
+                mat[[cb, tb]] = mat[[tb, cb]]
+                continue
+
+            # In all other cases, we construct the linear function for the operation.
+            # and compose (multiply) linear matrices.
+
+            if getattr(instruction.operation, "definition", None) is not None:
+                other = LinearFunction(instruction.operation.definition)
+            else:
+                other = LinearFunction(instruction.operation)
+
+            positions = [qc.find_bit(q).index for q in instruction.qubits]
+            other = other.extend_with_identity(len(mat), positions)
+            mat = np.dot(other.linear.astype(int), mat.astype(int)) % 2
+            mat = mat.astype(bool)
+
+        return mat
+
+    @staticmethod
+    def _clifford_to_mat(cliff):
+        """This creates a nxn matrix corresponding to the given Clifford, when Clifford
+        can be converted to a linear function. This is possible when the clifford has
+        tableau of the form [[A, B], [C, D]], with B = C = 0 and D = A^{-1}^t, and zero
+        phase vector. In this case, the required matrix is A^t.
+        Raises an error otherwise.
+        """
+        # Note: since cliff is a valid Clifford, then the condition D = A^{-1}^t
+        # holds automatically once B = C = 0.
+        if cliff.phase.any() or cliff.destab_z.any() or cliff.stab_x.any():
+            raise CircuitError("The given clifford does not correspond to a linear function.")
+        return np.transpose(cliff.destab_x)
+
+    @staticmethod
+    def _permutation_to_mat(perm):
+        """This creates a nxn matrix from a given permutation gate."""
+        nq = len(perm.pattern)
+        mat = np.zeros((nq, nq), dtype=bool)
+        for i, j in enumerate(perm.pattern):
+            mat[i, j] = True
+        return mat
+
+    def __eq__(self, other):
+        """Check if two linear functions represent the same matrix."""
+        if not isinstance(other, LinearFunction):
+            return False
+        return (self.linear == other.linear).all()
+
+    def validate_parameter(self, parameter):
+        """Parameter validation"""
+        return parameter
+
+    def _define(self):
+        """Populates self.definition with a decomposition of this gate."""
+        from qiskit.synthesis.linear import synth_cnot_count_full_pmh
+
+        self.definition = synth_cnot_count_full_pmh(self.linear)
+
+    @deprecate_func(
+        since="1.3",
+        pending=True,
+        additional_msg="Call LinearFunction.definition instead, or compile the circuit.",
+    )
+    def synthesize(self):
+        """Synthesizes the linear function into a quantum circuit.
+
+        Returns:
+            QuantumCircuit: A circuit implementing the evolution.
+        """
+        return self.definition
+
+    @property
+    def linear(self):
+        """Returns the n x n matrix representing this linear function."""
+        return self.params[0]
+
+    @property
+    def original_circuit(self):
+        """Returns the original circuit used to construct this linear function
+        (including None, when the linear function is not constructed from a circuit).
+        """
+        return self.params[1]
+
+    def is_permutation(self) -> bool:
+        """Returns whether this linear function is a permutation,
+        that is whether every row and every column of the n x n matrix
+        has exactly one 1.
+        """
+        linear = self.linear
+        perm = np.all(np.sum(linear, axis=0) == 1) and np.all(np.sum(linear, axis=1) == 1)
+        return perm
+
+    def permutation_pattern(self):
+        """This method first checks if a linear function is a permutation and raises a
+        `qiskit.circuit.exceptions.CircuitError` if not. In the case that this linear function
+        is a permutation, returns the permutation pattern.
+        """
+        if not self.is_permutation():
+            raise CircuitError("The linear function is not a permutation")
+
+        linear = self.linear
+        locs = np.where(linear == 1)
+        return locs[1]
+
+    def extend_with_identity(self, num_qubits: int, positions: list[int]) -> LinearFunction:
+        """Extend linear function to a linear function over nq qubits,
+        with identities on other subsystems.
+
+        Args:
+            num_qubits: number of qubits of the extended function.
+
+            positions: describes the positions of original qubits in the extended
+                function's qubits.
+
+        Returns:
+            LinearFunction: extended linear function.
+        """
+        extended_mat = np.eye(num_qubits, dtype=bool)
+
+        for i, pos in enumerate(positions):
+            extended_mat[positions, pos] = self.linear[:, i]
+
+        return LinearFunction(extended_mat)
+
+    def mat_str(self):
+        """Return string representation of the linear function
+        viewed as a matrix with 0/1 entries.
+        """
+        return str(self.linear.astype(int))
+
+    def function_str(self):
+        """Return string representation of the linear function
+        viewed as a linear transformation.
+        """
+        out = "("
+        mat = self.linear
+        for row in range(self.num_qubits):
+            first_entry = True
+            for col in range(self.num_qubits):
+                if mat[row, col]:
+                    if not first_entry:
+                        out += " + "
+                    out += "x_" + str(col)
+                    first_entry = False
+            if row != self.num_qubits - 1:
+                out += ", "
+        out += ")\n"
+        return out