toqito.matrices.cyclic_permutation_matrix
=========================================

.. py:module:: toqito.matrices.cyclic_permutation_matrix

.. autoapi-nested-parse::

   Generates a cyclic permutation matrix.





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

.. py:function:: cyclic_permutation_matrix(n, k = 1)

   Create the cyclic permutation matrix for a given dimension `n` [@WikiCyclicPermutation].

   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.

   .. rubric:: Examples

   Generate fixed point.

   ```python exec="1" source="above"
   from toqito.matrices import cyclic_permutation_matrix

   print(cyclic_permutation_matrix(n=4))
   ```

   Generate successive application.

   ```python exec="1" source="above"
   from toqito.matrices import cyclic_permutation_matrix

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

   :param n: int The number of rows and columns in the cyclic permutation matrix.
   :param 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.