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

.. py:module:: rand.random_circulant_gram_matrix

.. autoapi-nested-parse::

   Generates a random circulant Gram matrix.



Functions
---------

.. autoapisummary::

   rand.random_circulant_gram_matrix.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 :cite:`WikiCirculantMat`. This function utilizes the
   normalized DFT, a variation of DFT with normalized basis vectors.

   For additional information, see :cite:`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.

   >>> import numpy as np
   >>> from toqito.rand import random_circulant_gram_matrix
   >>> circulant_matrix = random_circulant_gram_matrix(4)
   >>> circulant_matrix.shape
   (4, 4)
   >>> np.allclose(circulant_matrix, circulant_matrix.T)
   True
   >>> circulant_matrix  # doctest: +SKIP
   array([[0.42351891, 0.21058986, 0.04257471, 0.21058986],
          [0.21058986, 0.42351891, 0.21058986, 0.04257471],
          [0.04257471, 0.21058986, 0.42351891, 0.21058986],
          [0.21058986, 0.04257471, 0.21058986, 0.42351891]])

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

   >>> from toqito.rand import random_circulant_gram_matrix
   >>> circulant_matrix = random_circulant_gram_matrix(4, seed=42)
   >>> circulant_matrix
   array([[ 0.69220011, -0.02116047,  0.12407687, -0.02116047],
          [-0.02116047,  0.69220011, -0.02116047,  0.12407687],
          [ 0.12407687, -0.02116047,  0.69220011, -0.02116047],
          [-0.02116047,  0.12407687, -0.02116047,  0.69220011]])

   .. rubric:: References

   .. bibliography::
       :filter: docname in docnames

   :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.

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