:py:mod:`perms.permute_systems`
===============================

.. py:module:: perms.permute_systems

.. autoapi-nested-parse::

   Permute systems.



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


Functions
~~~~~~~~~

.. autoapisummary::

   perms.permute_systems.permute_systems



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

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

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

   .. rubric:: Examples

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

   For example, if we define :math:`X \in \mathcal{A} \otimes \mathcal{B}` as

   .. math::
       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 :math:`X` to obtain :math:`X \in \mathcal{B} \otimes \mathcal{A}`
   yield the following matrix

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

   >>> from toqito.perms import permute_systems
   >>> import numpy as np
   >>> test_input_mat = np.array([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12], [13, 14, 15, 16]])
   >>> permute_systems(test_input_mat, [2, 1])
   [[ 1  3  2  4]
    [ 9 11 10 12]
    [ 5  7  6  8]
    [13 15 14 16]]

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

   For example, if we define :math:`X \in \mathcal{A} \otimes \mathcal{B} \otimes \mathcal{C}` as

   .. math::
       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 :math:`X` to obtain :math:`X \in \mathcal{B} \otimes \mathcal{C}
   \otimes \mathcal{C}` yield the following matrix

   .. math::
       X_{[2, 3, 1]} =
       \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}.

   >>> from toqito.perms import permute_systems
   >>> import numpy as np
   >>> test_input_mat = np.array(
   >>>    [
   >>>        [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],
   >>>    ]
   >>> )
   >>> permute_systems(test_input_mat, [2, 3, 1])
   [[ 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]]

   :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: :code:`False`
   :param inv_perm: Default: :code:`True`
   :return: The matrix or vector that has been permuted.