toqito.perms.swap
=================

.. py:module:: toqito.perms.swap

.. autoapi-nested-parse::

   Swap is used to apply the swap function within a quantum state or an operator.





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

.. py:function:: swap(rho, sys = None, dim = None, row_only = False)

   Swap two subsystems within a state or operator.

   Swaps the two subsystems of the vector or matrix `rho`, where the dimensions of the (possibly more than 2)
   subsystems are given by `dim` and the indices of the two subsystems to be swapped are specified in the 1-by-2
   vector `sys`.

   If `rho` is non-square and not a vector, 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`.

   If `row_only` is set to `True`, then only the rows of `rho` are swapped, but not the columns --
   this is equivalent to multiplying `rho` on the left by the corresponding swap operator, but not on the right.

   .. rubric:: Examples

   Consider the following matrix

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

   If we apply the `swap` function provided by `|toqito⟩` on \(X\), we should obtain the following
   matrix

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

   This can be observed by the following example in `|toqito⟩`.

   ```python exec="1" source="above"
   import numpy as np
   from toqito.perms import swap

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

   print(swap(test_mat))
   ```

   It is also possible to use the `sys` and `dim` arguments, it is possible to specify the system and
   dimension on which to apply the swap operator. For instance for `sys = [1 ,2]` and `dim = 2` we have
   that

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

   Using `|toqito⟩` we can see this gives the proper result.

   ```python exec="1" source="above"
   import numpy as np
   from toqito.perms import swap

   test_mat = np.array(
       [[1, 5, 9, 13], [2, 6, 10, 14], [3, 7, 11, 15], [4, 8, 12, 16]]
   )
   print(swap(test_mat, [1, 2], 2))
   ```

   It is also possible to perform the `swap` function on vectors in addition to matrices.

   ```python exec="1" source="above"
   import numpy as np
   from toqito.perms import swap

   test_vec = np.array([1, 2, 3, 4])

   print(swap(test_vec))
   ```

   :raises ValueError: If dimension does not match the number of subsystems.

   :param rho: A vector or matrix to have its subsystems swapped.
   :param sys: Default: [1, 2]
   :param dim: Default: `[sqrt(len(X), sqrt(len(X)))]`
   :param row_only: Default: `False`

   :returns: The swapped matrix.