toqito.matrix_ops.partial_trace
===============================

.. py:module:: toqito.matrix_ops.partial_trace

.. autoapi-nested-parse::

   Generates the partial trace of a matrix.





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

.. py:function:: partial_trace(input_mat, sys = None, dim = None)

   Compute the partial trace of a matrix [@WikiPartialTr].

   The *partial trace* is defined as

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

   where \(X \in \text{L}(\mathcal{X})\) and \(Y \in \text{L}(\mathcal{Y})\) are linear
   operators over complex Euclidean spaces \(\mathcal{X}\) and \(\mathcal{Y}\).

   Gives the partial trace of the matrix X, where the dimensions of the (possibly more than 2)
   subsystems are given by the vector `dim` and the subsystems to take the trace on are
   given by the scalar or vector `sys`.

   .. 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}.
   \]

   Taking the partial trace over the second subsystem of \(X\) yields the following matrix

   \[
       X_{pt, 2} = \begin{pmatrix}
                   7 & 11 \\
                   23 & 27
                \end{pmatrix}.
   \]

   By default, the partial trace function in `|toqito⟩` takes the trace of the second
   subsystem.

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

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

   print(partial_trace(test_input_mat))
   ```


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

   \[
       X_{pt, 1} = \begin{pmatrix}
                       12 & 14 \\
                       20 & 22
                   \end{pmatrix}
   \]

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

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

   print(partial_trace(test_input_mat, [0]))
   ```

   We can also specify both dimension and system size as `list` arguments. Consider the
   following \(16\)-by-\(16\) matrix.

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

   test_input_mat = np.arange(1, 257).reshape(16, 16)
   print(test_input_mat)
   ```


   We can take the partial trace on the first and third subsystems and assume that the size of
   each of the 4 systems is of dimension 2.

   ```python exec="1" source="above"
   import numpy as np
   from toqito.matrix_ops import partial_trace
   test_input_mat = np.arange(1, 257).reshape(16, 16)

   print(partial_trace(test_input_mat, [0, 2], [2, 2, 2, 2]))
   ```

   :raises ValueError: If matrix dimension is not equal to the number of subsystems.

   :param input_mat: A square 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 trace of matrix `input_mat`.