toqito.perms.permute_systems
============================

.. py:module:: toqito.perms.permute_systems

.. autoapi-nested-parse::

   Permute systems is used to permute subsystems within a quantum state or an operator.





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

.. py:function:: permute_systems(input_mat, perm, dim = None, row_only = False, inv_perm = False)

   Permute subsystems within a state or operator.

   Permutes the order of the subsystems of the vector or matrix `input_mat` according to the permutation vector
   `perm`, where the dimensions of the subsystems are given by the vector `dim`. If `input_mat` 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 columns dimensions in the second row of `dim`.

   If `row_only = True`, then only the rows of `input_mat` are permuted, but not the columns -- this is
   equivalent to multiplying `input_mat` on the left by the corresponding permutation operator, but not on the
   right.

   If `row_only = False`, then `dim` only needs to contain the row dimensions of the subsystems, even if
   `input_mat` is not square. If `inv_perm = True`, then the inverse permutation of `perm` is applied
   instead of `perm` itself.

   .. rubric:: Examples

   For spaces \(\mathcal{A}\) and \(\mathcal{B}\) where \(\text{dim}(\mathcal{A}) =
   \text{dim}(\mathcal{B}) = 2\) we may consider an operator \(X \in \mathcal{A} \otimes \mathcal{B}\).
   Applying the
   `permute_systems` function with vector \([1,0]\) on \(X\), we may reorient the spaces such that \(X \in
   \mathcal{B} \otimes \mathcal{A}\).

   For example, if we define \(X \in \mathcal{A} \otimes \mathcal{B}\) as

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

   then applying the `permute_systems` function on \(X\) to obtain \(X \in \mathcal{B} \otimes \mathcal{A}\)
   yield the following matrix

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

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

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

   print(permute_systems(test_input_mat, [1, 0]))
   ```


   For spaces \(\mathcal{A}, \mathcal{B}\), and \(\mathcal{C}\) where \(\text{dim}(\mathcal{A}) =
   \text{dim}(\mathcal{B}) = \text{dim}(\mathcal{C}) = 2\) we may consider an operator \(X \in \mathcal{A} \otimes
   \mathcal{B} \otimes \mathcal{C}\). Applying the `permute_systems` function with vector \([1,2,0]\) on
   \(X\), we may reorient the spaces such that \(X \in \mathcal{B} \otimes \mathcal{C} \otimes \mathcal{A}\).

   For example, if we define \(X \in \mathcal{A} \otimes \mathcal{B} \otimes \mathcal{C}\) as

   \[
       X =
       \begin{pmatrix}
           1 & 2 & 3 & 4, 5 & 6 & 7 & 8 \\
           9 & 10 & 11 & 12 & 13 & 14 & 15 & 16 \\
           17 & 18 & 19 & 20 & 21 & 22 & 23 & 24 \\
           25 & 26 & 27 & 28 & 29 & 30 & 31 & 32 \\
           33 & 34 & 35 & 36 & 37 & 38 & 39 & 40 \\
           41 & 42 & 43 & 44 & 45 & 46 & 47 & 48 \\
           49 & 50 & 51 & 52 & 53 & 54 & 55 & 56 \\
           57 & 58 & 59 & 60 & 61 & 62 & 63 & 64
       \end{pmatrix},
   \]

   then applying the `permute_systems` function on \(X\) to obtain \(X \in \mathcal{B} \otimes \mathcal{C}
   \otimes \mathcal{C}\) yield the following matrix

   \[
       X_{[1, 2, 0]} =
       \begin{pmatrix}
           1 & 5 & 2 & 6 & 3 & 7 & 4, 8 \\
           33 & 37 & 34 & 38 & 35 & 39 & 36 & 40 \\
           9 & 13 & 10 & 14 & 11 & 15 & 12 & 16 \\
           41 & 45 & 42 & 46 & 43 & 47 & 44 & 48 \\
           17 & 21 & 18 & 22 & 19 & 23 & 20 & 24 \\
           49 & 53 & 50 & 54 & 51 & 55 & 52 & 56 \\
           25 & 29 & 26 & 30 & 27 & 31 & 28 & 32 \\
           57 & 61 & 58 & 62 & 59 & 63 & 60 & 64
       \end{pmatrix}.
   \]

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

   test_input_mat = np.arange(1, 65).reshape(8, 8)

   print(permute_systems(test_input_mat, [1, 2, 0]))
   ```

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

   :param input_mat: The vector or matrix.
   :param perm: A permutation vector.
   :param dim: The default has all subsystems of equal dimension.
   :param row_only: Default: `False`
   :param inv_perm: Default: `True`

   :returns: The matrix or vector that has been permuted.