toqito.channels.pauli_channel
=============================

.. py:module:: toqito.channels.pauli_channel

.. autoapi-nested-parse::

   Generates and applies Pauli Channel to a matrix.





Module Contents
---------------

.. py:function:: pauli_channel(prob, return_kraus_ops = False, input_mat = None)

   Generate and apply a Pauli channel to a matrix.

   Generates the Choi matrix of a Pauli channel with given probabilities and optionally applies it
   to an input matrix. The Pauli channel is defined by the set of Pauli operators weighted by
   the probability vector. For a given probability vector \((p_0, \ldots, p_{4^q -1 })\), the
   channel is defined as shown below. Where, $q$ is the number of qubits.

   \[
       \Phi(\rho) = \sum_{i=0}^{4^q - 1} p_i P_i \rho P_i^*
   \]

   where \(P_i\) are Pauli operators generated by a lexographically increasing sequence of pauli operators of
   length strictly equal to \(q\), and \(p_i\) is the corresponding probability of that operator.
   For example, when \(q = 2\),

   \(P_{0} = I \otimes I\), \(P_{1} = I \otimes X\), \(P_{2} = I \otimes Y\), \(P_{3} = I \otimes Z\),
   \(P_{4} = X \otimes I\), \(P_{5} = X \otimes Y , \ldots P_{15} = Z \otimes Z\)

   If `prob` is a scalar, it generates a random `prob`-qubit Pauli channel.
   The length of the probability vector (if provided) must be \(4^q\) for some
   integer \(q\) (number of qubits).

   .. rubric:: Examples

   Generate a random single-qubit Pauli channel:

   ```python exec="1" source="above"
   from toqito.channels import pauli_channel

   print(pauli_channel(prob=1))
   ```

   Apply a specific two-qubit Pauli channel to an input matrix:

   ```python exec="1" source="above"
   import numpy as np
   from toqito.channels import pauli_channel

   _, output = pauli_channel(
       prob=np.array([0.1, 0.2, 0.3, 0.4]), input_mat=np.eye(2)
   )
   print(output)
   ```

   :raises ValueError: If probabilities are negative or don't sum to 1.
   :raises ValueError: If length of probability vector is not ``4^q`` for some integer ``q``.

   :param prob: Probability vector for Pauli operators. If scalar, generates random probabilities for \(q =\) `prob`
   :param qubits. The probabilities correspond to Pauli operators in lexographical order of length strictly equal to \: ,when `prob` is a vector.
   :type qubits. The probabilities correspond to Pauli operators in lexographical order of length strictly equal to \: q\
   :param return_kraus_ops: Flag to return Kraus operators. Default is ``False``.
   :param input_mat: Optional input matrix to apply the channel to. Default is ``None``.

   :returns: The Choi matrix of the channel. If ``input_mat`` is provided, also returns the output matrix.
             If ``return_kraus_ops`` is ``True``, returns Kraus operators as well.