toqito.matrix_ops.partial_transpose
===================================

.. py:module:: toqito.matrix_ops.partial_transpose

.. autoapi-nested-parse::

   Generates the partial transpose of a matrix.





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

.. py:function:: partial_transpose(rho, sys = None, dim = None)

   Compute the partial transpose of a matrix [@WikiPeresHorodecki].

   The *partial transpose* is defined as

   \[
       \left( \text{T} \otimes \mathbb{I}_{\mathcal{Y}} \right)
       \left(X\right)
   \]

   where \(X \in \text{L}(\mathcal{X})\) is a linear operator over the complex Euclidean
   space \(\mathcal{X}\) and where \(\text{T}\) is the transpose mapping
   \(\text{T} \in \text{T}(\mathcal{X})\) defined as

   \[
       \text{T}(X) = X^{\text{T}}
   \]

   for all \(X \in \text{L}(\mathcal{X})\).

   By default, the returned matrix is the partial transpose of the matrix `rho`, where it
   is assumed that the number of rows and columns of `rho` are both perfect squares and
   both subsystems have equal dimension. The transpose is applied to the second subsystem.

   In the case where `sys` amd `dim` are specified, this function gives the partial
   transpose of the matrix `rho` where the dimensions of the (possibly more than 2)
   subsystems are given by the vector `dim` and the subsystems to take the partial
   transpose are given by the scalar or vector `sys`. If `rho` is non-square,
   different row and column dimensions can be specified by putting the row dimensions in the
   first row of `dim` and the column dimensions in the second row of `dim`.

   .. rubric:: Examples

   Consider the following matrix

   \[
       X = \begin{pmatrix}
               1 & 2 & 3 & 4 \\
               5 & 6 & 7 & 8 \\
               9 & 10 & 11 & 12 \\
               13 & 14 & 15 & 16
           \end{pmatrix}.
   \]

   Performing the partial transpose on the matrix \(X\) over the second
   subsystem yields the following matrix

   \[
       X_{pt, 2} = \begin{pmatrix}
                   1 & 5 & 3 & 7 \\
                   2 & 6 & 4 & 8 \\
                   9 & 13 & 11 & 15 \\
                   10 & 14 & 12 & 16
                \end{pmatrix}.
   \]

   By default, in `|toqito⟩`, the partial transpose function performs the transposition on
   the second subsystem as follows.

   ```python exec="1" source="above"
   import numpy as np
   from toqito.matrix_ops import partial_transpose

   test_input_mat = np.arange(1, 17).reshape(4, 4)

   print(partial_transpose(test_input_mat))
   ```

   By specifying the `sys = 1` argument, we can perform the partial transpose over the
   first subsystem (instead of the default second subsystem as done above). Performing the
   partial transpose over the first subsystem yields the following matrix

   \[
       X_{pt, 1} = \begin{pmatrix}
                       1 & 2 & 9 & 10 \\
                       5 & 6 & 13 & 14 \\
                       3 & 4 & 11 & 12 \\
                       7 & 8 & 15 & 16
                   \end{pmatrix}.
   \]

   ```python exec="1" source="above"
   import numpy as np
   from toqito.matrix_ops import partial_transpose

   test_input_mat = np.arange(1, 17).reshape(4, 4)

   print(partial_transpose(test_input_mat, 1))
   ```

   :raises ValueError: If matrix dimensions are not square.

   :param rho: A matrix.
   :param sys: Scalar or vector specifying the size of the subsystems.
   :param dim: Dimension of the subsystems. If `None`, all dimensions are assumed to be equal.

   :returns: The partial transpose of matrix `rho`.