Skip to content

cyclic_permutation

Generates a cyclic permutation matrix.

cyclic_permutation 

cyclic_permutation(n: int, k: int = 1) -> ndarray

Create the cyclic permutation matrix for a given dimension n 1.

This function creates a cyclic permutation matrix of 0's and 1's which is a special type of square matrix that represents a cyclic permutation of its rows. The function allows fixed points and successive applications.

Parameters:

  • n (int) –

    int The number of rows and columns in the cyclic permutation matrix.

  • k (int, default: 1 ) –

    int The power to which the elements are raised, representing successive applications.

Returns:

  • ndarray –

    A NumPy array representing a cyclic permutation matrix of dimension n x n. Each row of the matrix is shifted

  • ndarray –

    one position to the right in a cyclic manner, creating a circular permutation pattern. If k is specified, the

  • ndarray –

    function raises the matrix to the power of k, representing successive applications of the cyclic permutation.

Examples:

Generate fixed point.

from toqito.matrices import cyclic_permutation

print(cyclic_permutation(n=4))

[[0 0 0 1]
 [1 0 0 0]
 [0 1 0 0]
 [0 0 1 0]]

Generate successive application.

from toqito.matrices import cyclic_permutation

print(cyclic_permutation(n=4, k=3))

[[0 1 0 0]
 [0 0 1 0]
 [0 0 0 1]
 [1 0 0 0]]

References

1 Wikipedia. Cyclic permutation. link.

Source code in toqito/matrices/cyclic_permutation.py 
 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
def cyclic_permutation(n: int, k: int = 1) -> np.ndarray:
    r"""Create the cyclic permutation matrix for a given dimension `n` [@wikipediacyclic].

    This function creates a cyclic permutation matrix of 0's and 1's which is a special type of square matrix
    that represents a cyclic permutation of its rows. The function allows fixed points and successive applications.

    Args:
        n: int The number of rows and columns in the cyclic permutation matrix.
        k: int The power to which the elements are raised, representing successive applications.

    Returns:
         A NumPy array representing a cyclic permutation matrix of dimension `n x n`. Each row of the matrix is shifted
         one position to the right in a cyclic manner, creating a circular permutation pattern. If `k` is specified, the
         function raises the matrix to the power of `k`, representing successive applications of the cyclic permutation.

    Examples:
        Generate fixed point.

        ```python exec="1" source="above" result="text"
        from toqito.matrices import cyclic_permutation

        print(cyclic_permutation(n=4))
        ```

        Generate successive application.

        ```python exec="1" source="above" result="text"
        from toqito.matrices import cyclic_permutation

        print(cyclic_permutation(n=4, k=3))
        ```



    """
    if not isinstance(n, int):
        raise TypeError("'n' must be an integer.")
    if n <= 0:
        raise ValueError("'n' must be a positive integer.")
    if not isinstance(k, int):
        raise TypeError("'k' must be an integer.")

    # P^k cyclically shifts the rows of the identity down by k, equivalent to rolling the identity
    # by k % n along axis 0. This matches np.linalg.matrix_power(P, k), including negative k, since
    # Python's modulo maps -k to n - k.
    return np.roll(np.identity(n, dtype=int), k % n, axis=0)