toqito.rand.random_circulant_gram_matrix
========================================

.. py:module:: toqito.rand.random_circulant_gram_matrix

.. autoapi-nested-parse::

   Generates a random circulant Gram matrix.





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

.. py:function:: random_circulant_gram_matrix(dim, seed = None)

   Generate a random circulant Gram matrix of specified dimension.

   A circulant matrix is a square matrix where the elements of each row are identical to the elements of the
   previous row such that the elements in one row are relocated by 1 position (in a cyclic manner) compared
   to the previous row. The eigenvalues and eigenvectors of this matrix are derived from the Discrete
   Fourier Transform (DFT).

   For more information on circulant matrices, see [@WikiCirculantMat]. This function utilizes the
   normalized DFT, a variation of DFT with normalized basis vectors.

   For additional information, see [@DSPNormDFT].

   The function creates a circulant matrix from a random diagonal matrix and the normalized DFT matrix.
   First, it generates a diagonal matrix with random non-negative entries. Next, it constructs the
   normalized DFT matrix. Finally, it computes the circulant matrix, which is real due to its origin
   from the DFT of a real diagonal matrix.

   .. rubric:: Examples

   Generate a random circulant Gram matrix of dimension 4.

   ```python exec="1" source="above" session="random_circulant_gram_matrix_example"
   import numpy as np
   from toqito.rand import random_circulant_gram_matrix

   circulant_matrix = random_circulant_gram_matrix(4)

   print(f"Shape of circulant matrix is {circulant_matrix.shape}")
   ```

   ```python exec="1" source="above" session="random_circulant_gram_matrix_example"
   print(np.allclose(circulant_matrix, circulant_matrix.T))
   ```

   ```python exec="1" source="above" session="random_circulant_gram_matrix_example"
   print(circulant_matrix)
   ```

   It is also possible to pass a seed to this function for reproducibility.

   ```python exec="1" source="above"
   from toqito.rand import random_circulant_gram_matrix

   circulant_matrix = random_circulant_gram_matrix(4, seed=42)

   print(circulant_matrix)
   ```

   :param dim: int The dimension of the circulant matrix to generate.
   :param seed: int | None A seed used to instantiate numpy's random number generator.

   :returns: numpy.ndarray A `dim` x `dim` real, symmetric, circulant matrix.