# toqito.perms.permute_systems¶

toqito.perms.permute_systems(input_mat: np.ndarray, perm: np.ndarray | list[int], dim: np.ndarray | list[int] = None, row_only: bool = False, inv_perm: bool = False) → np.ndarray[source]

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.

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 $$[2,1]$$ 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

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

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

$\begin{split}X_{[2,1]} = \begin{pmatrix} 1 & 3 & 2 & 4 \\ 9 & 11 & 10 & 12 \\ 5 & 7 & 6 & 8 \\ 13 & 15 & 14 & 16 \end{pmatrix}.\end{split}$
>>> 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 $$\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 $$[2,3,1]$$ 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

$\begin{split}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},\end{split}$

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

$\begin{split}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}.\end{split}$
>>> 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. input_mat – The vector or matrix. perm – A permutation vector. dim – The default has all subsystems of equal dimension. row_only – Default: False inv_perm – Default: True The matrix or vector that has been permuted.