qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/quantum_info/operators/channel/quantum_channel.py

@@ -0,0 +1,348 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 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.
+
+"""
+Abstract base class for Quantum Channels.
+"""
+
+from __future__ import annotations
+import copy
+import math
+import sys
+from abc import abstractmethod
+from numbers import Number, Integral
+
+import numpy as np
+
+from qiskit.circuit.instruction import Instruction
+from qiskit.exceptions import QiskitError
+from qiskit.quantum_info.operators.linear_op import LinearOp
+from qiskit.quantum_info.operators.op_shape import OpShape
+from qiskit.quantum_info.operators.operator import Operator
+from qiskit.quantum_info.operators.predicates import is_positive_semidefinite_matrix
+from qiskit.quantum_info.operators.channel.transformations import _transform_rep
+from qiskit.quantum_info.operators.channel.transformations import _to_choi
+from qiskit.quantum_info.operators.channel.transformations import _to_kraus
+from qiskit.quantum_info.operators.channel.transformations import _to_operator
+from qiskit.quantum_info.operators.scalar_op import ScalarOp
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+
+class QuantumChannel(LinearOp):
+    """Quantum channel representation base class."""
+
+    def __init__(
+        self,
+        data: list | np.ndarray,
+        num_qubits: int | None = None,
+        op_shape: OpShape | None = None,
+    ):
+        """Initialize a quantum channel Superoperator operator.
+
+        Args:
+            data: quantum channel data array.
+            op_shape: the operator shape of the channel.
+            num_qubits: the number of qubits if the channel is N-qubit.
+
+        Raises:
+            QiskitError: if arguments are invalid.
+        """
+        self._data = data
+        super().__init__(num_qubits=num_qubits, op_shape=op_shape)
+
+    def __repr__(self):
+        prefix = f"{self._channel_rep}("
+        pad = len(prefix) * " "
+        return (
+            f"{prefix}{np.array2string(np.asarray(self.data), separator=', ', prefix=prefix)}"
+            f",\n{pad}input_dims={self.input_dims()}, output_dims={self.output_dims()})"
+        )
+
+    def __eq__(self, other: Self):
+        """Test if two QuantumChannels are equal."""
+        if not super().__eq__(other):
+            return False
+        return np.allclose(self.data, other.data, rtol=self.rtol, atol=self.atol)
+
+    @property
+    def data(self):
+        """Return data."""
+        return self._data
+
+    @property
+    def _channel_rep(self):
+        """Return channel representation string"""
+        return type(self).__name__
+
+    @property
+    def settings(self):
+        """Return settings."""
+        return {
+            "data": self.data,
+            "input_dims": self.input_dims(),
+            "output_dims": self.output_dims(),
+        }
+
+    # ---------------------------------------------------------------------
+    # LinearOp methods
+    # ---------------------------------------------------------------------
+
+    @abstractmethod
+    def conjugate(self):
+        r"""Return the conjugate quantum channel.
+
+        .. note::
+            This is equivalent to the matrix complex conjugate in the
+            :class:`~qiskit.quantum_info.SuperOp` representation
+            ie. for a channel :math:`\mathcal{E}`, the SuperOp of
+            the conjugate channel :math:`\overline{{\mathcal{{E}}}}` is
+            :math:`S_{\overline{\mathcal{E}^\dagger}} = \overline{S_{\mathcal{E}}}`.
+        """
+
+    @abstractmethod
+    def transpose(self) -> Self:
+        r"""Return the transpose quantum channel.
+
+        .. note::
+            This is equivalent to the matrix transpose in the
+            :class:`~qiskit.quantum_info.SuperOp` representation,
+            ie. for a channel :math:`\mathcal{E}`, the SuperOp of
+            the transpose channel :math:`\mathcal{{E}}^T` is
+            :math:`S_{mathcal{E}^T} = S_{\mathcal{E}}^T`.
+        """
+
+    def adjoint(self) -> Self:
+        r"""Return the adjoint quantum channel.
+
+        .. note::
+            This is equivalent to the matrix Hermitian conjugate in the
+            :class:`~qiskit.quantum_info.SuperOp` representation
+            ie. for a channel :math:`\mathcal{E}`, the SuperOp of
+            the adjoint channel :math:`\mathcal{{E}}^\dagger` is
+            :math:`S_{\mathcal{E}^\dagger} = S_{\mathcal{E}}^\dagger`.
+        """
+        return self.conjugate().transpose()
+
+    def power(self, n: float) -> Self:
+        r"""Return the power of the quantum channel.
+
+        Args:
+            n (float): the power exponent.
+
+        Returns:
+            CLASS: the channel :math:`\mathcal{{E}} ^n`.
+
+        Raises:
+            QiskitError: if the input and output dimensions of the
+                         CLASS are not equal.
+
+        .. note::
+            For non-positive or non-integer exponents the power is
+            defined as the matrix power of the
+            :class:`~qiskit.quantum_info.SuperOp` representation
+            ie. for a channel :math:`\mathcal{{E}}`, the SuperOp of
+            the powered channel :math:`\mathcal{{E}}^\n` is
+            :math:`S_{{\mathcal{{E}}^n}} = S_{{\mathcal{{E}}}}^n`.
+        """
+        if n > 0 and isinstance(n, Integral):
+            return super().power(n)
+
+        # Conversion to superoperator
+        if self._input_dim != self._output_dim:
+            raise QiskitError("Can only take power with input_dim = output_dim.")
+        rep = self._channel_rep
+        input_dim, output_dim = self.dim
+        superop = _transform_rep(rep, "SuperOp", self._data, input_dim, output_dim)
+        superop = np.linalg.matrix_power(superop, n)
+
+        # Convert back to original representation
+        ret = copy.copy(self)
+        ret._data = _transform_rep("SuperOp", rep, superop, input_dim, output_dim)
+        return ret
+
+    def __sub__(self, other) -> Self:
+        qargs = getattr(other, "qargs", None)
+        if not isinstance(other, type(self)):
+            other = type(self)(other)
+        return self._add(-other, qargs=qargs)
+
+    def _add(self, other, qargs=None):
+        # NOTE: this method must be overridden for subclasses
+        # that don't have a linear matrix representation
+        # ie Kraus and Stinespring
+        if not isinstance(other, type(self)):
+            other = type(self)(other)
+        self._op_shape._validate_add(other._op_shape, qargs)
+        other = ScalarOp._pad_with_identity(self, other, qargs)
+        ret = copy.copy(self)
+        ret._data = self._data + other._data
+        return ret
+
+    def _multiply(self, other):
+        # NOTE: this method must be overridden for subclasses
+        # that don't have a linear matrix representation
+        # ie Kraus and Stinespring
+        if not isinstance(other, Number):
+            raise QiskitError("other is not a number")
+        ret = copy.copy(self)
+        ret._data = other * self._data
+        return ret
+
+    # ---------------------------------------------------------------------
+    # Additional methods
+    # ---------------------------------------------------------------------
+
+    def is_cptp(self, atol: float | None = None, rtol: float | None = None) -> bool:
+        """Return True if completely-positive trace-preserving (CPTP)."""
+        choi = _to_choi(self._channel_rep, self._data, *self.dim)
+        return self._is_cp_helper(choi, atol, rtol) and self._is_tp_helper(choi, atol, rtol)
+
+    def is_tp(self, atol: float | None = None, rtol: float | None = None) -> bool:
+        """Test if a channel is trace-preserving (TP)"""
+        choi = _to_choi(self._channel_rep, self._data, *self.dim)
+        return self._is_tp_helper(choi, atol, rtol)
+
+    def is_cp(self, atol: float | None = None, rtol: float | None = None) -> bool:
+        """Test if Choi-matrix is completely-positive (CP)"""
+        choi = _to_choi(self._channel_rep, self._data, *self.dim)
+        return self._is_cp_helper(choi, atol, rtol)
+
+    def is_unitary(self, atol: float | None = None, rtol: float | None = None) -> bool:
+        """Return True if QuantumChannel is a unitary channel."""
+        try:
+            op = self.to_operator()
+            return op.is_unitary(atol=atol, rtol=rtol)
+        except QiskitError:
+            return False
+
+    def to_operator(self) -> Operator:
+        """Try to convert channel to a unitary representation Operator."""
+        mat = _to_operator(self._channel_rep, self._data, *self.dim)
+        return Operator(mat, self.input_dims(), self.output_dims())
+
+    def to_instruction(self) -> Instruction:
+        """Convert to a Kraus or UnitaryGate circuit instruction.
+
+        If the channel is unitary it will be added as a unitary gate,
+        otherwise it will be added as a kraus simulator instruction.
+
+        Returns:
+            qiskit.circuit.Instruction: A kraus instruction for the channel.
+
+        Raises:
+            QiskitError: if input data is not an N-qubit CPTP quantum channel.
+        """
+
+        # Check if input is an N-qubit CPTP channel.
+        num_qubits = int(math.log2(self._input_dim))
+        if self._input_dim != self._output_dim or 2**num_qubits != self._input_dim:
+            raise QiskitError(
+                "Cannot convert QuantumChannel to Instruction: channel is not an N-qubit channel."
+            )
+        if not self.is_cptp():
+            raise QiskitError("Cannot convert QuantumChannel to Instruction: channel is not CPTP.")
+        # Next we convert to the Kraus representation. Since channel is CPTP we know
+        # that there is only a single set of Kraus operators
+        kraus, _ = _to_kraus(self._channel_rep, self._data, *self.dim)
+        # If we only have a single Kraus operator then the channel is
+        # a unitary channel so can be converted to a UnitaryGate. We do this by
+        # converting to an Operator and using its to_instruction method
+        if len(kraus) == 1:
+            return Operator(kraus[0]).to_instruction()
+        return Instruction("kraus", num_qubits, 0, kraus)
+
+    def _is_cp_helper(self, choi, atol, rtol):
+        """Test if a channel is completely-positive (CP)"""
+        if atol is None:
+            atol = self.atol
+        if rtol is None:
+            rtol = self.rtol
+        return is_positive_semidefinite_matrix(choi, rtol=rtol, atol=atol)
+
+    def _is_tp_helper(self, choi, atol, rtol):
+        """Test if Choi-matrix is trace-preserving (TP)"""
+        if atol is None:
+            atol = self.atol
+        if rtol is None:
+            rtol = self.rtol
+        # Check if the partial trace is the identity matrix
+        d_in, d_out = self.dim
+        mat = np.trace(np.reshape(choi, (d_in, d_out, d_in, d_out)), axis1=1, axis2=3)
+        tp_cond = np.linalg.eigvalsh(mat - np.eye(len(mat)))
+        zero = np.isclose(tp_cond, 0, atol=atol, rtol=rtol)
+        return np.all(zero)
+
+    def _format_state(self, state, density_matrix=False):
+        """Format input state so it is statevector or density matrix"""
+        state = np.array(state)
+        shape = state.shape
+        ndim = state.ndim
+        if ndim > 2:
+            raise QiskitError("Input state is not a vector or matrix.")
+        # Flatten column-vector to vector
+        if ndim == 2:
+            if shape[1] != 1 and shape[1] != shape[0]:
+                raise QiskitError("Input state is not a vector or matrix.")
+            if shape[1] == 1:
+                # flatten column-vector to vector
+                state = np.reshape(state, shape[0])
+        # Convert statevector to density matrix if required
+        if density_matrix and ndim == 1:
+            state = np.outer(state, np.transpose(np.conj(state)))
+        return state
+
+    @abstractmethod
+    def _evolve(self, state, qargs=None):
+        """Evolve a quantum state by the quantum channel.
+
+        Args:
+            state (DensityMatrix or Statevector): The input state.
+            qargs (list): a list of quantum state subsystem positions to apply
+                           the quantum channel on.
+
+        Returns:
+            DensityMatrix: the output quantum state as a density matrix.
+
+        Raises:
+            QiskitError: if the quantum channel dimension does not match the
+                         specified quantum state subsystem dimensions.
+        """
+        pass
+
+    @classmethod
+    def _init_transformer(cls, data):
+        """Convert input into a QuantumChannel subclass object or Operator object"""
+        # This handles common conversion for all QuantumChannel subclasses.
+        # If the input is already a QuantumChannel subclass it will return
+        # the original object
+        if isinstance(data, QuantumChannel):
+            return data
+        if hasattr(data, "to_quantumchannel"):
+            # If the data object is not a QuantumChannel it will give
+            # preference to a 'to_quantumchannel' attribute that allows
+            # an arbitrary object to define its own conversion to any
+            # quantum channel subclass.
+            return data.to_quantumchannel()
+        if hasattr(data, "to_channel"):
+            # TODO: this 'to_channel' method is the same case as the above
+            # but is used by current version of Aer. It should be removed
+            # once Aer is nupdated to use `to_quantumchannel`
+            # instead of `to_channel`,
+            return data.to_channel()
+        # Finally if the input is not a QuantumChannel and doesn't have a
+        # 'to_quantumchannel' conversion method we try and initialize it as a
+        # regular matrix Operator which can be converted into a QuantumChannel.
+        return Operator(data)

qiskit/quantum_info/operators/channel/stinespring.py

@@ -0,0 +1,296 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 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.
+"""
+Stinespring representation of a Quantum Channel.
+"""
+
+from __future__ import annotations
+import copy
+import math
+from numbers import Number
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from qiskit.circuit.quantumcircuit import QuantumCircuit
+from qiskit.circuit.instruction import Instruction
+from qiskit.exceptions import QiskitError
+from qiskit.quantum_info.operators.predicates import is_identity_matrix
+from qiskit.quantum_info.operators.channel.quantum_channel import QuantumChannel
+from qiskit.quantum_info.operators.op_shape import OpShape
+from qiskit.quantum_info.operators.channel.kraus import Kraus
+from qiskit.quantum_info.operators.channel.choi import Choi
+from qiskit.quantum_info.operators.channel.superop import SuperOp
+from qiskit.quantum_info.operators.channel.transformations import _to_stinespring
+from qiskit.quantum_info.operators.mixins import generate_apidocs
+from qiskit.quantum_info.operators.base_operator import BaseOperator
+
+if TYPE_CHECKING:
+    from qiskit import circuit
+
+
+class Stinespring(QuantumChannel):
+    r"""Stinespring representation of a quantum channel.
+
+    The Stinespring representation of a quantum channel :math:`\mathcal{E}`
+    is a rectangular matrix :math:`A` such that the evolution of a
+    :class:`~qiskit.quantum_info.DensityMatrix` :math:`\rho` is given by
+
+    .. math::
+
+        \mathcal{E}(ρ) = \mbox{Tr}_2\left[A ρ A^\dagger\right]
+
+    where :math:`\mbox{Tr}_2` is the :func:`partial_trace` over subsystem 2.
+
+    A general operator map :math:`\mathcal{G}` can also be written using the
+    generalized Stinespring representation which is given by two matrices
+    :math:`A`, :math:`B` such that
+
+    .. math::
+
+        \mathcal{G}(ρ) = \mbox{Tr}_2\left[A ρ B^\dagger\right]
+
+    See reference [1] for further details.
+
+    References:
+        1. C.J. Wood, J.D. Biamonte, D.G. Cory, *Tensor networks and graphical calculus
+           for open quantum systems*, Quant. Inf. Comp. 15, 0579-0811 (2015).
+           `arXiv:1111.6950 [quant-ph] <https://arxiv.org/abs/1111.6950>`_
+    """
+
+    def __init__(
+        self,
+        data: QuantumCircuit | circuit.instruction.Instruction | BaseOperator | np.ndarray,
+        input_dims: int | tuple | None = None,
+        output_dims: int | tuple | None = None,
+    ):
+        """Initialize a quantum channel Stinespring operator.
+
+        Args:
+            data: data to initialize superoperator.
+            input_dims: the input subsystem dimensions.
+            output_dims: the output subsystem dimensions.
+
+        Raises:
+            QiskitError: if input data cannot be initialized as a
+                         a list of Kraus matrices.
+
+        Additional Information:
+            If the input or output dimensions are None, they will be
+            automatically determined from the input data. This can fail for the
+            Stinespring operator if the output dimension cannot be automatically
+            determined.
+        """
+        # If the input is a list or tuple we assume it is a pair of general
+        # Stinespring matrices. If it is a numpy array we assume that it is
+        # a single Stinespring matrix.
+        if isinstance(data, (list, tuple, np.ndarray)):
+            if not isinstance(data, tuple):
+                # Convert single Stinespring set to length 1 tuple
+                stine = (np.asarray(data, dtype=complex), None)
+            if isinstance(data, tuple) and len(data) == 2:
+                if data[1] is None:
+                    stine = (np.asarray(data[0], dtype=complex), None)
+                else:
+                    stine = (np.asarray(data[0], dtype=complex), np.asarray(data[1], dtype=complex))
+
+            dim_left, dim_right = stine[0].shape
+            # If two Stinespring matrices check they are same shape
+            if stine[1] is not None:
+                if stine[1].shape != (dim_left, dim_right):
+                    raise QiskitError("Invalid Stinespring input.")
+            input_dim = dim_right
+            if output_dims:
+                output_dim = np.prod(output_dims)
+            else:
+                output_dim = input_dim
+            if dim_left % output_dim != 0:
+                raise QiskitError("Invalid output_dim")
+            op_shape = OpShape.auto(
+                dims_l=output_dims, dims_r=input_dims, shape=(output_dim, input_dim)
+            )
+        else:
+            # Otherwise we initialize by conversion from another Qiskit
+            # object into the QuantumChannel.
+            if isinstance(data, (QuantumCircuit, Instruction)):
+                # If the input is a Terra QuantumCircuit or Instruction we
+                # convert it to a SuperOp
+                data = SuperOp._init_instruction(data)
+            else:
+                # We use the QuantumChannel init transform to intialize
+                # other objects into a QuantumChannel or Operator object.
+                data = self._init_transformer(data)
+            op_shape = data._op_shape
+            output_dim, input_dim = op_shape.shape
+            # Now that the input is an operator we convert it to a
+            # Stinespring operator
+            rep = getattr(data, "_channel_rep", "Operator")
+            stine = _to_stinespring(rep, data._data, input_dim, output_dim)
+
+        # Initialize either single or general Stinespring
+        if stine[1] is None or (stine[1] == stine[0]).all():
+            # Standard Stinespring map
+            data = (stine[0], None)
+        else:
+            # General (non-CPTP) Stinespring map
+            data = stine
+        super().__init__(data, op_shape=op_shape)
+
+    @property
+    def data(self):
+        # Override to deal with data being either tuple or not
+        if self._data[1] is None:
+            return self._data[0]
+        else:
+            return self._data
+
+    def is_cptp(self, atol=None, rtol=None):
+        """Return True if completely-positive trace-preserving."""
+        if atol is None:
+            atol = self.atol
+        if rtol is None:
+            rtol = self.rtol
+        if self._data[1] is not None:
+            return False
+        check = np.dot(np.transpose(np.conj(self._data[0])), self._data[0])
+        return is_identity_matrix(check, rtol=self.rtol, atol=self.atol)
+
+    def _evolve(self, state, qargs=None):
+        return SuperOp(self)._evolve(state, qargs)
+
+    # ---------------------------------------------------------------------
+    # BaseOperator methods
+    # ---------------------------------------------------------------------
+
+    def conjugate(self):
+        ret = copy.copy(self)
+        stine_l = np.conjugate(self._data[0])
+        stine_r = None
+        if self._data[1] is not None:
+            stine_r = np.conjugate(self._data[1])
+        ret._data = (stine_l, stine_r)
+        return ret
+
+    def transpose(self):
+        ret = copy.copy(self)
+        ret._op_shape = self._op_shape.transpose()
+        din, dout = self.dim
+        dtr = self._data[0].shape[0] // dout
+        stine = [None, None]
+        for i, mat in enumerate(self._data):
+            if mat is not None:
+                stine[i] = np.reshape(
+                    np.transpose(np.reshape(mat, (dout, dtr, din)), (2, 1, 0)), (din * dtr, dout)
+                )
+        ret._data = (stine[0], stine[1])
+        return ret
+
+    def compose(
+        self, other: Stinespring, qargs: list | None = None, front: bool = False
+    ) -> Stinespring:
+        if qargs is None:
+            qargs = getattr(other, "qargs", None)
+        if qargs is not None:
+            return Stinespring(SuperOp(self).compose(other, qargs=qargs, front=front))
+        # Otherwise we convert via Kraus representation rather than
+        # superoperator to avoid unnecessary representation conversions
+        return Stinespring(Kraus(self).compose(other, front=front))
+
+    def tensor(self, other: Stinespring) -> Stinespring:
+        if not isinstance(other, Stinespring):
+            other = Stinespring(other)
+        return self._tensor(self, other)
+
+    def expand(self, other: Stinespring) -> Stinespring:
+        if not isinstance(other, Stinespring):
+            other = Stinespring(other)
+        return self._tensor(other, self)
+
+    @classmethod
+    def _tensor(cls, a, b):
+        # Tensor Stinespring ops
+        sa_l, sa_r = a._data
+        sb_l, sb_r = b._data
+
+        # Reshuffle tensor dimensions
+        din_a, dout_a = a.dim
+        din_b, dout_b = b.dim
+        dtr_a = sa_l.shape[0] // dout_a
+        dtr_b = sb_l.shape[0] // dout_b
+
+        shape_in = (dout_a, dtr_a, dout_b, dtr_b, din_a * din_b)
+        shape_out = (dout_a * dtr_a * dout_b * dtr_b, din_a * din_b)
+        sab_l = np.kron(sa_l, sb_l)
+        # Reravel indices
+        sab_l = np.reshape(np.transpose(np.reshape(sab_l, shape_in), (0, 2, 1, 3, 4)), shape_out)
+
+        # Compute right Stinespring op
+        if sa_r is None and sb_r is None:
+            sab_r = None
+        else:
+            if sa_r is None:
+                sa_r = sa_l
+            elif sb_r is None:
+                sb_r = sb_l
+            sab_r = np.kron(sa_r, sb_r)
+            # Reravel indices
+            sab_r = np.reshape(
+                np.transpose(np.reshape(sab_r, shape_in), (0, 2, 1, 3, 4)), shape_out
+            )
+        ret = copy.copy(a)
+        ret._op_shape = a._op_shape.tensor(b._op_shape)
+        ret._data = (sab_l, sab_r)
+        return ret
+
+    def __add__(self, other):
+        qargs = getattr(other, "qargs", None)
+        if not isinstance(other, QuantumChannel):
+            other = Choi(other)
+        return self._add(other, qargs=qargs)
+
+    def __sub__(self, other):
+        qargs = getattr(other, "qargs", None)
+        if not isinstance(other, QuantumChannel):
+            other = Choi(other)
+        return self._add(-other, qargs=qargs)
+
+    def _add(self, other, qargs=None):
+        # Since we cannot directly add two channels in the Stinespring
+        # representation we convert to the Choi representation
+        return Stinespring(Choi(self)._add(other, qargs=qargs))
+
+    def _multiply(self, other):
+        if not isinstance(other, Number):
+            raise QiskitError("other is not a number")
+
+        ret = copy.copy(self)
+        # If the number is complex or negative we need to convert to
+        # general Stinespring representation so we first convert to
+        # the Choi representation
+        if isinstance(other, complex) or other < 1:
+            # Convert to Choi-matrix
+            ret._data = Stinespring(Choi(self)._multiply(other))._data
+            return ret
+        # If the number is real we can update the Kraus operators
+        # directly
+        num = math.sqrt(other)
+        stine_l, stine_r = self._data
+        stine_l = num * self._data[0]
+        stine_r = None
+        if self._data[1] is not None:
+            stine_r = num * self._data[1]
+        ret._data = (stine_l, stine_r)
+        return ret
+
+
+# Update docstrings for API docs
+generate_apidocs(Stinespring)