skrmt.ensemble package

Submodules

skrmt.ensemble.base_ensemble module

Base Ensemble Module

This module contains the general implementation of the matrix ensembles. This file contains the common attributes and methods for all the random matrix ensembles. It also defines the basic interface to be supported by inherited classes.

class skrmt.ensemble.base_ensemble.BaseEnsemble[source]

Bases: object

General abstract ensemble class.

This class contains common attributes and methods for all the ensembles. It also defines the basic interface to be supported by inherited classes.

matrix

instance of the random matrix ensemble of size n times n.

Type:: numpy array

_eigvals

array of computed eigenvalues. This array is None until the method eigvals is called. The computed eigenvalues are cached in the attribute _eigvals to avoid re-computing them. The eigenvalues are re-calculated again if the matrix sample changes.

Type:: numpy array

eigval_norm_cost

constant that is used to normalize the eigenvalues so their support is always the same independently of the sample size. This is really useful for plotting, since the representation interval will always be the same no matter how many eigenvalues are sampled.

Type:: float

__str__() → str[source]: String representation of the ensemble instance.

eigval_hist(bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, normalize: bool = False, avoid_img: bool = False) → Tuple[ndarray, ndarray][source]

Calculates the histogram of the matrix eigenvalues.

Calculates the histogram of the current sampled matrix eigenvalues. Some ensembles like Gaussian (Hermite) ensemble or Wishart (Laguerre) ensemble might have improved routines to avoid calculating the eigenvalues, so instead the histogram is built using certain techniques to boost efficiency. It is important to underline that this function works with real eigenvalues, if the matrix eigenvalues are complex, they are casted to its real part.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
avoid_img (bool, default=False) – If True, eigenvalue imaginary part is ignored. This should be used when the eigenvalue compatation is expected to generate complex eigenvalues with really small imaginary part because of computing rounding errors. E.g.: MANOVA Ensemble eigenvalues.

Returns:

(tuple) tuple containing – observed (array): List of eigenvalues frequencies per bin. If density is True these values are the relative frequencies in order to get an area under the histogram equal to 1. Otherwise, this list contains the absolute frequencies of the eigenvalues. bin_edges (array): The edges of the bins. Length nbins + 1 (nbins left edges and right edge of last bin)

Raises:

ValueError if interval is not a tuple. –

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

abstract eigvals(normalize: bool = False) → ndarray[source]

abstract joint_eigval_pdf(eigvals: ndarray = None) → float[source]

plot_eigval_hist(bins: int | Sequence, interval: Tuple = None, density: bool = False, normalize: bool = False, savefig_path: str = None, avoid_img: bool = False) → None[source]

Computes and plots the histogram of the matrix eigenvalues.

Calculates and plots the histogram of the current sampled matrix eigenvalues. Some ensembles like Gaussian (Hermite) ensemble or Wishart (Laguerre) ensemble have improved routines to avoid calculating the eigenvalues, so the histogram is built using certain techniques to boost efficiency. It is important to underline that this function works with real and complex eigenvalues: if the matrix eigenvalues are complex, they are plotted in the complex plane next to a heap map to study eigenvalue density.

Parameters:

bins (int or sequence) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
avoid_img (bool, default=False) – If True, eigenvalue imaginary part is ignored. This should be used when the eigenvalue compatation is expected to generate complex eigenvalues with really small imaginary part because of computing rounding errors. E.g.: MANOVA Ensemble eigenvalues.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

abstract resample(random_state: int = None) → ndarray[source]

This is an alias for the method sample. It samples new random matrix.

The sampling algorithm depends on the inherited classes, so it should be specified by them.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: numpy array containing new matrix sampled.

abstract sample(random_state: int = None) → ndarray[source]

Samples new random matrix.

The sampling algorithm depends on the inherited classes, so it should be specified by them.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: numpy array containing new matrix sampled.

skrmt.ensemble.circular_ensemble module

Circular Ensemble Module

This module contains the implementation of the Circular Ensemble. This ensemble of random matrices contains mainly three sub-ensembles: Circular Orthogonal Ensemble (COE), Circular Unitary Ensemble (CUE) and Circular Symplectic Ensemble (CSE).

class skrmt.ensemble.circular_ensemble.CircularEnsemble(beta: int, n: int, random_state: int = None)[source]

Bases: BaseEnsemble

General Circular Ensemble class.

This class contains common attributes and methods for all the Circular ensembles. Circular Ensembles are divided in: - Circular Orthogonal Ensemble (COE, beta=1): the distribution of the matrices of this ensemble are invariant under orthogonal conjugation, i.e., if X is in COE(n) and O is an orthogonal matrix, then O*X*O^T is equally distributed as X. - Circular Unitary Ensemble (CUE, beta=2): the distribution of the matrices of this ensemble are invariant under unitary conjugation, i.e., if X is in CUE(n) and O is an unitary matrix, then O*X*O^T is equally distributed as X. - Circular Symplectic Ensemble (CSE, beta=4): the distribution of the matrices of this ensemble are invariant under conjugation by the symplectic group.

matrix

instance of the COE, CUE or CSE random matrix ensemble of size n times n if it is COE or CUE, or of size 2n times 2n if it is CSE.

Type:: numpy array

beta

descriptive integer of the gaussian ensemble type. For COE beta=1, for CUE beta=2, for CSE beta=4.

Type:: int

n

random matrix size. Circular ensemble matrices are squared matrices. COE and CUE are of size n times n, and CSE are of size 2n times 2n.

Type:: int

References

Killip, R. and Zozhan, R.
Matrix Models and Eigenvalue Statistics for Truncations of Classical Ensembles of Random Unitary Matrices. Communications in Mathematical Physics. 349 (2017): 991-1027.
“Circular ensemble”. Wikipedia.
en.wikipedia.org/wiki/Circular_ensemble

eigvals(normalize: bool = False) → ndarray[source]

Calculates the random matrix eigenvalues.

Calculates the random matrix eigenvalues using numpy standard procedure. If the matrix ensemble is symmetric, a faster algorithm is used.

Returns:: numpy array with the calculated eigenvalues.

joint_eigval_pdf(eigvals: ndarray = None) → float[source]

Computes joint eigenvalue pdf.

Calculates joint eigenvalue probability density function given an array of eigenvalues. If the array of eigenvalues is not provided, the current random matrix sample (so its eigenvalues) is used. This function depends on beta, i.e., in the sub-Circular ensemble.

Parameters:: eigvals (np.ndarray, default=None) – numpy array with the values (eigenvalues) to evaluate the joint pdf in.
Returns:: real number. Value of the joint pdf of the eigenvalues.

References

Killip, R. and Zozhan, R.
Matrix Models and Eigenvalue Statistics for Truncations of Classical Ensembles of Random Unitary Matrices. Communications in Mathematical Physics. 349 (2017): 991-1027.
“Circular ensemble”. Wikipedia.
en.wikipedia.org/wiki/Circular_ensemble

plot_eigval_hist(bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, normalize: bool = False, savefig_path: str = None) → None[source]

Computes and plots the histogram of the matrix eigenvalues.

Calculates and plots the histogram of the current sampled matrix eigenvalues. It is important to underline that this function works with real and complex eigenvalues: if the matrix eigenvalues are complex, they are plotted in the complex plane next to a heap map to study eigenvalue density.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

References

Killip, R. and Zozhan, R.
Matrix Models and Eigenvalue Statistics for Truncations of Classical Ensembles of Random Unitary Matrices. Communications in Mathematical Physics. 349 (2017): 991-1027.

resample(random_state: int = None) → ndarray[source]

Re-samples new Circular Ensemble random matrix.

It re-samples a new random matrix from the Circular ensemble. This is an alias for method sample.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample(random_state: int = None) → ndarray[source]

Samples new Circular Ensemble random matrix.

The sampling algorithm depends on the specification of beta parameter. If beta=1, COE matrix is sampled; if beta=2 CUE matrix is sampled and if beta=4 CSE matrix is sampled.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Killip, R. and Zozhan, R.
Matrix Models and Eigenvalue Statistics for Truncations of Classical Ensembles of Random Unitary Matrices. Communications in Mathematical Physics. 349 (2017): 991-1027.
“Circular ensemble”. Wikipedia.
en.wikipedia.org/wiki/Circular_ensemble

skrmt.ensemble.gaussian_ensemble module

Gaussian Ensemble Module

This module contains the implementation of the Gaussian Ensemble, also known as Hermite Ensemble. This ensemble of random matrices contains mainly three sub-ensembles: Gaussian Orthogonal Ensemble (GOE), Gaussian Unitary Ensemble (GUE) and Gaussian Symplectic Ensemble (GSE).

class skrmt.ensemble.gaussian_ensemble.GaussianEnsemble(beta: int, n: int, tridiagonal_form: bool = False, sigma: float = 1.0, random_state: int = None)[source]

Bases: BaseEnsemble

General Gaussian Ensemble class.

This class contains common attributes and methods for all the gaussian ensembles. Gaussian Ensembles are divided in: - Gaussian Orthogonal Ensemble (GOE, beta=1): the distribution of the matrices of this ensemble are invariant under orthogonal conjugation, i.e., if X is in GOE(n) and O is an orthogonal matrix, then O*X*O^T is equally distributed as X. - Gaussian Unitary Ensemble (GUE, beta=2): the distribution of the matrices of this ensemble are invariant under unitary conjugation, i.e., if X is in GUE(n) and O is an unitary matrix, then O*X*O^T is equally distributed as X. - Gaussian Symplectic Ensemble (GSE, beta=4): the distribution of the matrices of this ensemble are invariant under conjugation by the symplectic group.

matrix

instance of the GOE, GUE or GSE random matrix ensemble of size n times n if it is GOE or GUE, or of size 2n times 2n if it is GSE.

Type:: numpy array

beta

descriptive integer of the gaussian ensemble type. For GOE beta=1, for GUE beta=2, for GSE beta=4.

Type:: int

n

random matrix size. Gaussian ensemble matrices are squared matrices. GOE and GUE are of size n times n, and GSE are of size 2n times 2n.

Type:: int

tridiagonal_form

if set to True, Gaussian Ensemble matrices are sampled in its tridiagonal form, which has the same eigenvalues than its standard form. Otherwise, it is sampled using its standard form.

Type:: bool

sigma

scale (standard deviation) of the random entries of the sampled matrix.

Type:: float

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

eigval_hist(bins: int | Sequence, interval: Tuple = None, density: bool = False, normalize: bool = False, avoid_img: bool = False) → Tuple[ndarray, ndarray][source]

Calculates the histogram of the matrix eigenvalues.

Calculates the histogram of the current sampled matrix eigenvalues. Some ensembles like Gaussian (Hermite) ensemble or Wishart (Laguerre) ensemble might have improved routines to avoid calculating the eigenvalues, so instead the histogram is built using certain techniques to boost efficiency. It is important to underline that this function works with real eigenvalues, if the matrix eigenvalues are complex, they are casted to its real part.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
avoid_img (bool, default=False) – If True, eigenvalue imaginary part is ignored. This should be used when the eigenvalue compatation is expected to generate complex eigenvalues with really small imaginary part because of computing rounding errors. E.g.: MANOVA Ensemble eigenvalues.

Returns:

(tuple) tuple containing – observed (array): List of eigenvalues frequencies per bin. If density is True these values are the relative frequencies in order to get an area under the histogram equal to 1. Otherwise, this list contains the absolute frequencies of the eigenvalues. bin_edges (array): The edges of the bins. Length nbins + 1 (nbins left edges and right edge of last bin)

Raises:

ValueError if interval is not a tuple. –

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

eigvals(normalize: bool = False) → ndarray[source]

Computes the random matrix eigenvalues.

Calculates the random matrix eigenvalues using numpy standard procedure. If the matrix ensemble is symmetric, a faster algorithm is used.

Returns:: numpy array with the calculated eigenvalues.

joint_eigval_pdf(eigvals: ndarray = None) → float[source]

Computes joint eigenvalue pdf.

Calculates joint eigenvalue probability density function given an array of eigenvalues. If the array of eigenvalues is not provided, the current random matrix sample (so its eigenvalues) is used. This function depends on beta, i.e., in the sub-Gaussian ensemble.

Parameters:: eigvals (np.ndarray, default=None) – numpy array with the values (eigenvalues) to evaluate the joint pdf in.
Returns:: real number. Value of the joint pdf of the eigenvalues.

References

Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_eigval_hist(bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, normalize: bool = False, savefig_path: str = None) → None[source]

Computes and plots the histogram of the matrix eigenvalues.

Calculates and plots the histogram of the current sampled matrix eigenvalues. Gaussian (Hermite) ensemble and Wishart (Laguerre) ensemble have improved routines to avoid calculating the eigenvalues, so the histogram is built using certain techniques to boost efficiency.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are not normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

resample(tridiagonal_form: bool = None, random_state: int = None) → ndarray[source]

Re-samples a random matrix from the Gaussian ensemble with the specified form.

It re-samples a random matrix from the Gaussian ensemble with the specified form. If the specified form is different than the original form (tridiagonal vs standard) the property self.tridiagonal_form is updated and the random matrix is sampled with the updated form. If tridiagonal_form is not specified, this methods returns a re-sampled random matrix of the initialized form by calling the method sample.

Parameters:

tridiagonal_form (bool, default=None) – form to generate the new random matrix sample. If set to True, a random matrix in tridiagonal form is returned. Otherwise, the random matrix is sampled in standard form.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

Returns:

(ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample(random_state: int = None) → ndarray[source]

Samples new Gaussian Ensemble random matrix.

The sampling algorithm depends on the specification of tridiagonal_form parameter. If tridiagonal_form is set to True, a Gaussian Ensemble random matrix in its tridiagonal form is sampled. Otherwise, it is sampled using the standard form.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample_tridiagonal() → ndarray[source]

Samples a Gaussian Ensemble random matrix in its tridiagonal form.

Samples a random matrix of the specified Gaussian Ensemble (remember, beta=1 is GOE, beta=2 is GUE and beta=4 is GSE) in its tridiagonal form.

Returns:: numpy array containing new matrix sampled.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

skrmt.ensemble.manova_ensemble module

Manova Ensemble Module

This module contains the implementation of the Manova Ensemble, also known as Jacobi Ensemble. This ensemble of random matrices contains mainly three sub-ensembles: Manova Real Ensemble, Manova Complex Ensemble and Manova Quaternion Ensemble.

class skrmt.ensemble.manova_ensemble.ManovaEnsemble(beta: int, m: int, n1: int, n2: int, random_state: int = None)[source]

Bases: BaseEnsemble

General Manova Ensemble class.

This class contains common attributes and methods for all the Manova ensembles. It also defines the basic interface to be supported by inherited classes. Manova Ensembles are divided in: - Manova Real Ensemble (MRE, beta=1): the random matrices of this ensemble are formed by sampling two random real standard guassian matrices (X and Y) of size m times n1 and m times n2 respectively. Then, matrix A = (X * X’) / (X * X’ + Y * Y’) generates a matrix of the Manova Real Ensemble. - Manova Complex Ensemble (MCE, beta=2): the random matrices of this ensemble are formed by sampling two random complex standard guassian matrices (X and Y) of size m times n1 and m times n2 respectively. Then, matrix A = (X * X’) / (X * X’ + Y * Y’) generates a matrix of the Manova Complex Ensemble. - Manova Quaternion Ensemble (MQE, beta=4): the random matrices of this ensemble are formed by: sampling two random complex standard guassian matrices (X1 and X2), both of size m times n1. Another two random complex standard guassian matrices (Y1 and Y2), both of size m times n2, are sampled. They are stacked forming matrices X and Y: X = [X1 X2; -conj(X2) conj(X1)] Y = [Y1 Y2; -conj(Y2) conj(Y1)] Finally, matrix A = (X * X’) / (X * X’ + Y * Y’) generates a matrix of the Manova Quaternion Ensemble of size m times m.

matrix

instance of the ManovaReal, ManovaComplex or ManovaQuaternion random ensembles. If it is an instance of ManovaReal or ManovaComplex, the random matrix is of size m times m. If it is a ManovaQuaternion, the random matrix is of size 2m times 2m.

Type:: numpy array

beta

descriptive integer of the Manova ensemble type. For Real beta=1, for Complex beta=2, for Quaternion beta=4.

Type:: int

m

number of rows of the random guassian matrices that generates the matrix of the corresponding ensemble.

Type:: int

n1

number of columns of the first random guassian matrix that generates the matrix of the corresponding ensemble.

Type:: int

n2

number of columns of the second random guassian matrix that generates the matrix of the corresponding ensemble.

Type:: int

References

Erdos, L. and Farrell, B.
“Local Eigenvalue Density for General MANOVA Matrices”. Journal of Statistical Physics. 152.6 (2013): 1003-1032.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

eigvals(normalize: bool = False) → ndarray[source]

Computes the random matrix eigenvalues.

Calculates the random matrix eigenvalues using numpy standard procedure. If the matrix ensemble is symmetric, a faster algorithm is used.

Returns:: numpy array with the calculated eigenvalues.

joint_eigval_pdf(eigvals: ndarray = None) → float[source]

Computes joint eigenvalue pdf.

Calculates joint eigenvalue probability density function given an array of eigenvalues. If the array of eigenvalues is not provided, the current random matrix sample (so its eigenvalues) is used. This function depends on beta, i.e., in the sub-Manova ensemble.

Parameters:: eigvals (np.ndarray, default=None) – numpy array with the values (eigenvalues) to evaluate the joint pdf in.
Returns:: real number. Value of the joint pdf of the eigenvalues.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_eigval_hist(bins: int | Sequence = 100, interval: Tuple = (0, 1), density: bool = False, normalize: bool = False, savefig_path: str = None) → None[source]

Computes and plots the histogram of the matrix eigenvalues

Calculates and plots the histogram of the current sampled matrix eigenvalues.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=(0,1)) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are not normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

References

Erdos, L. and Farrell, B.
“Local Eigenvalue Density for General MANOVA Matrices”. Journal of Statistical Physics. 152.6 (2013): 1003-1032.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

resample(random_state: int = None) → ndarray[source]

Re-samples new Manova Ensemble random matrix.

It re-samples a new random matrix from the Manova ensemble. This is an alias for method sample.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample(random_state: int = None) → ndarray[source]

Samples new Manova Ensemble random matrix.

The sampling algorithm depends on the specification of beta parameter. If beta=1, Manova Real is sampled; if beta=2 Manova Complex is sampled and if beta=4 Manova Quaternion is sampled.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

skrmt.ensemble.misc module

Miscellaneous - useful functions

skrmt.ensemble.misc.get_bins_centers_and_contour(bin_edges: List[float]) → List[float][source]

Calculates the centers and contour of the given the bins edges.

Computes the centers of the given the bins edges. Also, the smallest and the largest bin delimitiers are included to define the countour of the representation interval.

Parameters:: bin_edges (list) – list of numbers (floats) that specify each bin delimiter.
Returns:: list of numbers (floats) consisting in the list of bin centers and contour.

skrmt.ensemble.misc.get_logger(logger_name: str) → Logger[source]: Get a pre-configured logger

skrmt.ensemble.misc.indicator(x: float, start: float = None, stop: float = None, inclusive: str = 'both') → ndarray[source]

Element-wise indicator function within a real interval. The interval can be left-closed, right-closed, closed or open. Visit https://en.wikipedia.org/wiki/Indicator_function for more information.

Parameters:

x (ndarray) – list of numbers to compute its element-wise indicator image.
start (double, default=None) – left value of the interval. If not provided, the left value is equivalent to \(- {\infty}\).
stop (double, default=None) – right value of the interval. If not provided, the right value is equivalent to \(+ {\infty}\).
inclusive (string, default=”both”) – type of interval. For left-closed interval use “left”, for right-closed interval use “right”, for closed interval use “both” and for open interval use “neither”.

Returns:

array_like consisting in the element-wise indicator function image of the given values.

skrmt.ensemble.misc.plot_func(interval: Tuple, func: Callable, num_x_vals: int = 1000, plot_title: str = None, plot_ylabel: str = None, savefig_path: str = None) → None[source]

Plots a given 1D function (callable) within the provided interval.

It plots a given 1-dimensional function (python Callable) within the provided interval. The x values are computed by generating `n_

Parameters:

interval (tuple) – Delimiters (xmin, xmax) of the histogram.
func (callable) – Function to be evaluated. The image of the function builds the y-axis values that are plotted.
num_x_vals (int, default=100) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
plot_title (string, default=None) – Title of the plot.
plot_ylabel (string, default=None) – Label of the y-axis.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

skrmt.ensemble.misc.relu(x: float | ndarray)[source]

Element-wise maximum between the value and zero.

Parameters:: x (ndarray) – list of numbers to compute its element-wise maximum.
Returns:: array_like consisting in the element-wise maximum vector of the given values.

skrmt.ensemble.spectral_law module

Spectral Law module

This module contains classes that implement the main spectral distributions. When the limiting behaviour of the spectrum of a random matrix ensemble is well-known, it is often described with a mathematical proven law. Probability density functions and cumulative distribution functions are provided for the Wigner Semicircle Law, Marchenko-Pastur Law, Tracy-Widom Law and for the spectrum of the Manova Ensemble.

class skrmt.ensemble.spectral_law.ManovaSpectrumDistribution(ratio_a: float, ratio_b: float, beta: int = 1)[source]

Bases: rv_continuous

Manova Spectrum Distribution class.

The spectrum of the random matrices of the Manova Ensemble converge to a well-defined function implemented in this class. The class provides methods to sample values following the Manova spectrum distribution, computing the PDF, computing the CDF and simple methods to plot the former two.

a

first random matrix size ratio. This is the ratio between the number of degrees of freedom ‘p’ and the first sample size ‘n1’. The value of a = p/n1. Remember a Manova randon matrix is considered a double-Wishart matrix, that’s why there are two sample sizes ‘n1’ and ‘n2’ (see below).

Type:: float

b

second random matrix size ratio. This is the ratio between the number of degrees of freedom ‘p’ and the second sample size ‘n2’. The value of b = p/n2. Remember a Manova randon matrix is considered a double-Wishart matrix, that’s why there are two sample sizes ‘n1’ and ‘n2’.

Type:: float

beta

descriptive integer of the Manova ensemble type. For MRE beta=1, for WME beta=2, for MQE beta=4.

Type:: int, default=1

sigma

scale of the distribution. This value also corresponds to the standard deviation of the random entries of the sampled matrix.

Type:: float

lambda_minus

lower bound of the support of the Manova spectrum distribution. It depends on beta, on the scale (sigma) and on the ratio.

Type:: float

lambda_plus

upper bound of the support of the Manova spectrum distribution. It depends on beta, on the scale (sigma) and on the ratio.

Type:: float

References

Erdos, L. and Farrell, B.
“Local Eigenvalue Density for General MANOVA Matrices”. Journal of Statistical Physics. 152.6 (2013): 1003-1032.

plot_cdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the CDF of the Manova Spectrum distribution.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, a, and b.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

plot_empirical_pdf(sample_size: int = 1000, bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, plot_law_pdf: bool = False, savefig_path: str = None, random_state: int = None) → None[source]

Computes and plots Manova spectrum empirical pdf.

Calculates and plots the Manova spectrum empirical distribution by sampling random values from the Manova spectrum PDF equation. Remember that ratio_a and ratio_b will determine the shape of the distribution.

Parameters:

sample_size (int, default=1000) – number of random samples that can be interpreted as random eigenvalues of a Wigner matrix. This is the sample size.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored. If one of the bounds of the specified interval is outside of the minimum default interval, this will be adjusted to show the distribution bulk properly.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
plot_law_pdf (bool, default=False) – If True, the theoretical law is plotted. If set to False, just the empirical histogram is shown. This parameter is only considered when the argument ‘density’ is set also to True.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown are the end of the routine.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

References

Laszlo, L. and Farrel, B.
“Local Eigenvalue Density for General MANOVA Matrices”. Journal of Statistical Physics. 152.6 (2013): 1003-1032.
Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_pdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the PDF of the Manova Spectrum distribution.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, a, and b.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

class skrmt.ensemble.spectral_law.MarchenkoPasturDistribution(ratio: float, beta: int = 1, sigma: float = 1.0)[source]

Bases: rv_continuous

Marchenko-Pastur Distribution class.

The Marchenko-Pastur Law describes the spectrum of the Wishart random matrices. Therefore the spectrum of the random matrices of this ensemble converge to the Marchenko-Pastur Law when the matrix size goes to infinity. This class provides methods to sample eigenvalues following Marchenko-Pastur distribution, computing the PDF, computing the CDF and simple methods to plot the former two.

ratio

random matrix size ratio. This is the ratio between the number of degrees of freedom ‘p’ and the sample size ‘n’. The value of ratio = p/n.

Type:: float

beta

descriptive integer of the Wishart ensemble type. For WRE beta=1, for WCE beta=2, for WQE beta=4.

Type:: int

sigma

scale of the distribution. This value also corresponds to the standard deviation of the random entries of the sampled matrix.

Type:: float

lambda_minus

lower bound of the support of the Marchenko-Pastur Law. It depends on beta, on the scale (sigma) and on the ratio.

Type:: float

lambda_plus

upper bound of the support of the Marchenko-Pastur Law. It depends on beta, on the scale (sigma) and on the ratio.

Type:: float

References

Bar, Z.D. and Silverstain, J.W.
“Spectral Analysis of Large Dimensional Random Matrices”. 2nd edition. Springer. (2010).

ARCTAN_OF_INFTY = 1.5707963267948966

plot_cdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the CDF of the Marchenko-Pastur Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, ratio, and scale.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

plot_empirical_pdf(sample_size: int = 1000, bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, plot_law_pdf: bool = False, savefig_path: str = None, random_state: int = None) → None[source]

Computes and plots Marchenko-Pastur empirical PDF.

Calculates and plots Marchenko-Pastur law by generating samples from the known Marchenko-Pastur PDF. Remember that the ratio specified when instantiating the class will determine the shape of the distribution.

Parameters:

sample_size (int, default=1000) – number of random samples that can be interpreted as random eigenvalues of a Wigner matrix. This is the sample size.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored. If one of the bounds of the specified interval is outside of the minimum default interval, this will be adjusted to show the distribution bulk properly.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
plot_law_pdf (bool, default=False) – If True, the theoretical law is plotted. If set to False, just the empirical histogram is shown. This parameter is only considered when the argument ‘density’ is set also to True.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown are the end of the routine.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_pdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the PDF of the Marchenko-Pastur Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, ratio, and scale.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

class skrmt.ensemble.spectral_law.TracyWidomDistribution(beta: int = 1)[source]

Bases: rv_continuous

Tracy-Widom Distribution class.

The Tracy-Widom Law describes the behaviour of the largest eigenvalue of the Wigner random matrices. In particular, random matrices of the Gaussian Ensemble are Wigner matrices, and therefore the largest eigenvalues of the spectrum of the random matrices of this ensemble converge to the Tracy-Widom Law when the matrix size and the sample size (number of times a Wigner matrix is generated to compute the largest eigenvalue) goes to infinity. This class provides methods to sample eigenvalues following Tracy-Widom distribution, computing the PDF, computing the CDF and simple methods to plot the former two.

beta

descriptive integer of the Gaussian ensemble type. For GOE beta=1, for GUE beta=2, for GSE beta=4.

Type:: int

References

Bauman, S.
“The Tracy-Widom Distribution and its Application to Statistical Physics”. http://web.mit.edu/8.334/www/grades/projects/projects17/SamBauman.pdf MIT Department of Physics. (2017).
Tracy, C.A. and Widom, H.
“On orthogonal and symplectic matrix ensembles”. Communications in Mathematical Physics. 177.3. (1996).
Bejan, A.
“Largest eigenvalues and sample covariance matrices”. Tracy-Widom and Painleve II: Computational aspects and realization in S-Plus with applications, M.Sc. dissertation, Department of Statistics, The University of Warwick. (2005).
Borot, G. and Nadal, C.
“Right tail expansion of Tracy-Widom beta laws”. Random Matrices: Theory and Applications. 01.03. (2012).

plot_cdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the PDF of the Tracy-Widom Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

plot_empirical_pdf(sample_size: int = 1000, bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, plot_law_pdf: bool = False, savefig_path: str = None, random_state: int = None) → None[source]

Computes and plots Tracy-Widom empirical law.

Calculates and plots Tracy-Widom law by generating samples from the Tracy-Widom PDF.

Parameters:

sample_size (int, default=1000) – number of random samples that can be interpreted as random eigenvalues of a Wigner matrix. This is the sample size.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored. If one of the bounds of the specified interval is outside of the minimum default interval, this will be adjusted to show the distribution bulk properly.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
plot_law_pdf (bool, default=False) – If True, the theoretical law is plotted. If set to False, just the empirical histogram is shown. This parameter is only considered when the argument ‘density’ is set also to True.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown are the end of the routine.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_ensemble_max_eigvals(ensemble: BaseEnsemble, n_eigvals: int = 1, bins: int | Sequence = 100, random_state: int = None, savefig_path: str = None) → None[source]

Plots the histogram of the maximum eigenvalues of a random ensemble with the Tracy-Widom PDF.

It computes samples of normalized maximum eigenvalues of the specified random matrix ensemble and plots their histogram alongside the Tracy-Widom PDF. Note that only random matrices from the Gaussian ensemble are Wigner matrices, so only the largest eigenvalue of these type of random matrices follow Tracy-Widom distribution. This library provides this method to compare Tracy-Widom law with the distribution of the largest eigenvalue of any type of random ensemble.

Parameters:

ensemble (BaseEnsemble) – a random matrix ensemble instance.
n_eigvals (int, default=1) – number of maximum eigenvalues to compute. This is the number of times the random matrix is re-sampled in order to get several samples of the maximum eigenvalue.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

plot_pdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the PDF of the Tracy-Widom Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

class skrmt.ensemble.spectral_law.WignerSemicircleDistribution(beta: int = 1, center: float = 0.0, sigma: float = 1.0)[source]

Bases: object

Wigner Semicircle Distribution class.

The Wigner Semicircle Law describes the spectrum of the Wigner random matrices. In particular, random matrices of the Gaussian Ensemble are Wigner matrices, and therefore the spectrum of the random matrices of this ensemble converge to the Wigner Semicircle Law when the matrix size goes to infinity. This class provides methods to sample eigenvalues following Wigner Semicircle distribution, computing the PDF, computing the CDF and simple methods to plot the former two.

beta

descriptive integer of the Gaussian ensemble type. For GOE beta=1, for GUE beta=2, for GSE beta=4.

Type:: int

center

center of the distribution. Since the distribution has the shape of a semicircle, the center corresponds to its center.

Type:: float

sigma

scale of the distribution. This value also corresponds to the standard deviation of the random entries of the sampled matrix.

Type:: float

radius

radius of the semicircle of the Wigner law. This depends on the scale (sigma) and on beta.

Type:: float

References

Wigner, E.
“Characteristic Vectors of Bordered Matrices With Infinite Dimensions”. Annals of Mathematics. 62.3. (1955).
Wigner, E.
“On the Distribution of the Roots of Certain Symmetric Matrices”. Annals of Mathematics. 67.2. (1958).

cdf(x: float | ndarray) → float | ndarray[source]

Computes CDF of the Wigner Semicircle Law.

Parameters:: x (float or ndarray) – value or (numpy) array of values in which compute the CDF.
Returns:: float or numpy array with the computed CDF in the given value(s).

pdf(x: float | ndarray) → float | ndarray[source]

Computes PDF of the Wigner Semicircle Law.

Parameters:: x (float or ndarray) – value or (numpy) array of values in which compute the PDF.
Returns:: float or numpy array with the computed PDF in the given value(s).

plot_cdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the CDF of the Wigner Semicircle Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, center, radius and scale.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

plot_empirical_pdf(sample_size: int = 10000, bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, plot_law_pdf: bool = False, savefig_path: str = None, random_state: int = None) → None[source]

Computes and plots Wigner’s semicircle empirical law.

Calculates and plots Wigner’s semicircle empirical law using random samples generated using the relationship between the Wigner Semicircle law and the Beta distribution: the Wigner’s Semicircle distribution it is a scaled Beta distribution with parameters \({\alpha} = {\beta} = 3/2\).

Parameters:

sample_size (int, default=1000) – number of random samples that can be interpreted as random eigenvalues of a Wigner matrix. This is the sample size.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored. If one of the bounds of the specified interval is outside of the minimum default interval, this will be adjusted to show the distribution bulk properly.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
plot_law_pdf (bool, default=False) – If True, the theoretical law is plotted. If set to False, just the empirical histogram is shown. This parameter is only considered when the argument ‘density’ is set also to True.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown are the end of the routine.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_pdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the PDF of the Wigner Semicircle Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, center, radius and scale.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

rvs(size: int | Tuple[int] = None, random_state: int = None) → ndarray[source]

Samples ranfom variates following this distribution. This uses the relationship between Wigner Semicircle law and Beta distribution.

Parameters:

size (int or tuple of ints, default=None) – sample size. If None, a single value is returned.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

Returns:

numpy array with the generated samples.

skrmt.ensemble.tracy_widom_approximator module

Tracy-Widom distribution approximator

This module implements an approximator of the Tracy-Widom distribution. The code is based on the open source GitHub repository https://github.com/yymao/TracyWidom. Tracy-Widom distribution functions for beta = 1, 2 and 4 are provided.

References

Bejan, A.
“Largest eigenvalues and sample covariance matrices”. Tracy-Widom and Painleve II: Computational aspects and realization in S-Plus with applications, M.Sc. dissertation, Department of Statistics, The University of Warwick. (2005).
Borot, G. and Nadal, C.
“Right tail expansion of Tracy-Widom beta laws”. Random Matrices: Theory and Applications. 01.03. (2012).
Yao-Yuan Mao.
TracyWidom GitHUb repository. (2013). https://github.com/yymao/TracyWidom

Original License from https://github.com/yymao/TracyWidom:

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Modifications by Alejandro Santorum under the following license:

BSD 3-Clause License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

class skrmt.ensemble.tracy_widom_approximator.TW_Approximator(beta: int = 1)[source]

Bases: object

Provide the Tracy-Widom distribution functions for beta = 1, 2, or 4.

References

Bejan, A.
“Largest eigenvalues and sample covariance matrices”. Tracy-Widom and Painleve II: Computational aspects and realization in S-Plus with applications, M.Sc. dissertation, Department of Statistics, The University of Warwick. (2005).
Borot, G. and Nadal, C.
“Right tail expansion of Tracy-Widom beta laws”. Random Matrices: Theory and Applications. 01.03. (2012).

cdf(x: float | ndarray) → float | ndarray[source]

Return the cumulative distribution function at x. \(cdf(x) = \mathbb{P}(TW < x)\).

Parameters:: x (float or array-like) – value to evaluate the cdf.
Returns:: y (float or array-like) – result of y = cdf(x).

pdf(x: float | ndarray) → float | ndarray[source]

Return the probability distribution function at x. \(pdf(x) = {\frac{d}{dx}} \mathbb{P}(TW < x)\).

Parameters:: x (float or array-like) – value to evaluate the pdf.
Returns:: y (float or array-like) – result of y = pdf(x).

skrmt.ensemble.tridiagonal_utils module

Tridiagonal utils module

This module contains utilities for tridiagolization or to handle tridiagonal matrices.

skrmt.ensemble.tridiagonal_utils.householder_reduction(mtx: ndarray, ret_iterations: bool = False) → Tuple[ndarray, ndarray, ndarray][source]

Householder reduction method for tridiagonalization.

Computes Householder reduction method for tridiagonalization. It transforms a given symmetric matrix in its tridiagonal form, keeping the same eigenvalues as the original.

Parameters:

mtx (numpy array) – symmetric matrix to be tridiagonalized.
ret_iterations (bool, default=False) – If set to True, it returns rotation matrices used to perform the tridiagonalization.

Returns:

(tuple) tuple containing – mtx (nparray): tridiagonalized matrix. mtx_list (nparray): list of matrices representing the evolution of the given matrix

after each rotation. Only returned if ret_iterations is set to True.

rot_list (nparray): list of applied rotation matrices. Only returned if ret_iterations is set to True.

References

1. Hildebrand. “Householder numerically with mathematica.” 2007.
http://buzzard.ups.edu/courses/2007spring/projects/hildebrand-paper-revised.pdf

skrmt.ensemble.tridiagonal_utils.tridiag_eigval_hist(tridiag_mtx: ndarray, interval: Tuple, bins: int | Sequence = 100, density: bool = False) → Tuple[ndarray, ndarray][source]

Computes efficiently eigenvalue histogram.

Calculates the eigenvalue histogram of the given matrix, using the specified bins between the introduced interval. The given matrix has to be tridiagonal, so this function builds the histogram efficiently using Sturm sequences, avoiding to calculate eigenvalues.

Parameters:

tridiag_mtx (numpy array) – tridiagonal matrix
interval (tuple) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.

Returns:

(tuple) tuple containing – observed (array): List of eigenvalues frequencies per bin. If density is True these values are the relative frequencies in order to get an area under the histogram equal to 1. Otherwise, this list contains the absolute frequencies of the eigenvalues. bin_delimiters (array): The edges of the bins. Length nbins + 1 (nbins left edges and right edge of last bin).

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

skrmt.ensemble.tridiagonal_utils.tridiag_eigval_neg(tridiag_mtx: ndarray) → int[source]

Calculates number of negative eigenvalues.

Given a tridiagonal matrix, this function calculates the number of negative eigenvalues using Sturm sequences.

Parameters:: tridiag_mtx (numpy array) – tridiagonal matrix
Returns:: integer representing the number of negative eigenvalues.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

skrmt.ensemble.utils module

Ensemble Utils functions

This sub-module contains several useful functions to run and manage various simulations related to random matrix ensembles.

skrmt.ensemble.utils.plot_spectral_hist_and_law(ensemble: BaseEnsemble, bins: int | Sequence = 100, savefig_path: str = None) → None[source]

Plots the spectrum histogram of a random matrix ensemble alongside the PDF of the corresponding spectral law.

It illustrates the histogram of the spectrum of a given random matrix ensemble alongside the PDF of the corresponding spectral law, i.e.: - If ensemble is GaussianEnsemble then is plotted Wigner’s Semicircle law PDF. - If ensemble is WishartEnsemble then is plotted Marchenko-Pastur law PDF. - If ensemble is ManovaEnsemble then is plotted the PDF of the Manova ensemble formulated by Wachter.

Parameters:

ensemble (BaseEnsemble) – a random matrix ensemble instance. The only supported types are GaussianEnsemble, WishartEnsemble and ManovaEnsemble.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

skrmt.ensemble.utils.standard_vs_tridiag_hist(ensemble: GaussianEnsemble | WishartEnsemble, bins: int | Sequence = 100, savefig_path: str = None, random_state: int = None) → None[source]

Plots and compares the spectral histogram of a random matrix using its standard form vs using the corresponding tridiagonal form.

This function simulates the histogramming of a given random matrix ensemble in its standard form and it compares the former with the equivalent histogram computed using the tridiagonal matrix form. This is useful to illustrate both types of matrix have the same spectral distribution.

Parameters:

ensemble (BaseEnsemble) – a random matrix ensemble instance. The only supported types are GaussianEnsemble and WishartEnsemble, since spectral optimizations based on their tridiagonal forms are known.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

skrmt.ensemble.wishart_ensemble module

Wishart Ensemble Module

This module contains the implementation of the Wishart Ensemble, also known as Laguerre Ensemble. This ensemble of random matrices contains mainly three sub-ensembles: Wishart Real Ensemble, Wishart Complex Ensemble and Wishart Quaternion Ensemble.

class skrmt.ensemble.wishart_ensemble.WishartEnsemble(beta: int, p: int, n: int, tridiagonal_form: bool = False, sigma: float = 1.0, random_state: int = None)[source]

Bases: BaseEnsemble

General Wishart Ensemble class.

This class contains common attributes and methods for all the Wishart ensembles. Wishart Ensembles are divided in: - Wishart Real Ensemble (WRE, beta=1): the random matrices of this ensemble are formed by multiplying a random real standard gaussian matrix of size p times n by its transpose. - Wishart Complex Ensemble (WCE, beta=2): the random matrices of this ensemble are formed by multiplying a random complex standard gaussian matrix of size p times n by its transpose. - Wishart Quaternion Ensemble (WQE, beta=4): the random matrices of this ensemble are formed by: sampling two random complex standard guassian matrices (X and Y), stacking them to create matrix A = [X Y; -conj(Y) conj(X)]. Finally matrix A is multiplied by its transpose in order to generate a matrix of the Wishart Quaternion Ensemble.

matrix

instance of the WishartReal, WishartComplex or WishartQuaternion random ensembles. If it is an instance of WishartReal or WishartComplex, the random matrix is of size p times p. If it is a WishartQuaternion, the random matrix is of size 2p times 2p.

Type:: numpy array

beta

descriptive integer of the Wishart ensemble type. For Real beta=1, for Complex beta=2, for Quaternion beta=4.

Type:: int

p

number of rows of the guassian matrix that generates the matrix of the corresponding ensemble.

Type:: int

n

number of columns of the guassian matrix that generates the matrix of the corresponding ensemble.

Type:: int

tridiagonal_form

if set to True, Gaussian Ensemble matrices are sampled in its tridiagonal form, which has the same eigenvalues than its standard form. Otherwise, it is sampled using its standard form.

Type:: bool

sigma

scale (standard deviation) of the random entries of the sampled matrix.

Type:: float

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.
Bar, Z.D. and Silverstain, J.W.
Spectral Analysis of Large Dimensional Random Matrices. 2nd edition. Springer. (2010).

eigval_hist(bins: int | Sequence, interval: Tuple = None, density: bool = False, normalize: bool = False, avoid_img: bool = False) → Tuple[ndarray, ndarray][source]

Calculates the histogram of the matrix eigenvalues.

Calculates the histogram of the current sampled matrix eigenvalues. Some ensembles like Gaussian (Hermite) ensemble or Wishart (Laguerre) ensemble might have improved routines to avoid calculating the eigenvalues, so instead the histogram is built using certain techniques to boost efficiency. It is important to underline that this function works with real eigenvalues, if the matrix eigenvalues are complex, they are casted to its real part.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
avoid_img (bool, default=False) – If True, eigenvalue imaginary part is ignored. This should be used when the eigenvalue compatation is expected to generate complex eigenvalues with really small imaginary part because of computing rounding errors. E.g.: MANOVA Ensemble eigenvalues.

Returns:

(tuple) tuple containing – observed (array): List of eigenvalues frequencies per bin. If density is True these values are the relative frequencies in order to get an area under the histogram equal to 1. Otherwise, this list contains the absolute frequencies of the eigenvalues. bin_edges (array): The edges of the bins. Length nbins + 1 (nbins left edges and right edge of last bin)

Raises:

ValueError if interval is not a tuple. –

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

eigvals(normalize: bool = False) → ndarray[source]

Computes the random matrix eigenvalues.

Calculates the random matrix eigenvalues using numpy standard procedure. If the matrix ensemble is symmetric, a faster algorithm is used.

Returns:: numpy array with the calculated eigenvalues.

joint_eigval_pdf(eigvals: ndarray = None) → float[source]

Computes joint eigenvalue pdf.

Calculates joint eigenvalue probability density function given an array of eigenvalues. If the array of eigenvalues is not provided, the current random matrix sample (so its eigenvalues) is used. This function depends on beta, i.e., in the sub-Wishart ensemble.

Parameters:: eigvals (np.ndarray, default=None) – numpy array with the values (eigenvalues) to evaluate the joint pdf in.
Returns:: real number. Value of the joint pdf of the eigenvalues.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_eigval_hist(bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, normalize: bool = False, savefig_path: str = None) → None[source]

Computes and plots the histogram of the matrix eigenvalues.

Calculates and plots the histogram of the current sampled matrix eigenvalues. Gaussian (Hermite) ensemble and Wishart (Laguerre) ensemble have improved routines to avoid calculating the eigenvalues, so the histogram is built using certain techniques to boost efficiency.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are not normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

resample(tridiagonal_form: bool = None, random_state: int = None) → ndarray[source]

Re-samples a random matrix from the Wishart ensemble with the specified form.

It re-samples a random matrix from the Wishart ensemble with the specified form. If the specified form is different than the original form (tridiagonal vs standard) the property self.tridiagonal_form is updated and the random matrix is sampled with the updated form. If tridiagonal_form is not specified, this methods returns a re-sampled random matrix of the initialized form by calling the method sample.

Parameters:

tridiagonal_form (bool, default=None) – form to generate the new random matrix sample. If set to True, a random matrix in tridiagonal form is returned. Otherwise, the random matrix is sampled in standard form.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

Returns:

(ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample(random_state: int = None) → ndarray[source]

Samples new Wishart Ensemble random matrix.

The sampling algorithm depends on the specification of tridiagonal_form parameter. If tridiagonal_form is set to True, a Wishart Ensemble random matrix in its tridiagonal form is sampled. Otherwise, it is sampled using the standard form.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample_tridiagonal() → ndarray[source]

Samples a Wishart Ensemble random matrix in its tridiagonal form.

Samples a random matrix of the specified Wishart Ensemble (remember, beta=1 is Real, beta=2 is Complex and beta=4 is Quaternion) in its tridiagonal form.

Returns:: numpy array containing new matrix sampled.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

Module contents

The skrmt.ensemble module includes models based on random matrix ensembles.

class skrmt.ensemble.CircularEnsemble(beta: int, n: int, random_state: int = None)[source]

Bases: BaseEnsemble

General Circular Ensemble class.

This class contains common attributes and methods for all the Circular ensembles. Circular Ensembles are divided in: - Circular Orthogonal Ensemble (COE, beta=1): the distribution of the matrices of this ensemble are invariant under orthogonal conjugation, i.e., if X is in COE(n) and O is an orthogonal matrix, then O*X*O^T is equally distributed as X. - Circular Unitary Ensemble (CUE, beta=2): the distribution of the matrices of this ensemble are invariant under unitary conjugation, i.e., if X is in CUE(n) and O is an unitary matrix, then O*X*O^T is equally distributed as X. - Circular Symplectic Ensemble (CSE, beta=4): the distribution of the matrices of this ensemble are invariant under conjugation by the symplectic group.

matrix

instance of the COE, CUE or CSE random matrix ensemble of size n times n if it is COE or CUE, or of size 2n times 2n if it is CSE.

Type:: numpy array

beta

descriptive integer of the gaussian ensemble type. For COE beta=1, for CUE beta=2, for CSE beta=4.

Type:: int

n

random matrix size. Circular ensemble matrices are squared matrices. COE and CUE are of size n times n, and CSE are of size 2n times 2n.

Type:: int

References

Killip, R. and Zozhan, R.
Matrix Models and Eigenvalue Statistics for Truncations of Classical Ensembles of Random Unitary Matrices. Communications in Mathematical Physics. 349 (2017): 991-1027.
“Circular ensemble”. Wikipedia.
en.wikipedia.org/wiki/Circular_ensemble

eigvals(normalize: bool = False) → ndarray[source]

Calculates the random matrix eigenvalues.

Calculates the random matrix eigenvalues using numpy standard procedure. If the matrix ensemble is symmetric, a faster algorithm is used.

Returns:: numpy array with the calculated eigenvalues.

joint_eigval_pdf(eigvals: ndarray = None) → float[source]

Computes joint eigenvalue pdf.

Calculates joint eigenvalue probability density function given an array of eigenvalues. If the array of eigenvalues is not provided, the current random matrix sample (so its eigenvalues) is used. This function depends on beta, i.e., in the sub-Circular ensemble.

Parameters:: eigvals (np.ndarray, default=None) – numpy array with the values (eigenvalues) to evaluate the joint pdf in.
Returns:: real number. Value of the joint pdf of the eigenvalues.

References

Killip, R. and Zozhan, R.
Matrix Models and Eigenvalue Statistics for Truncations of Classical Ensembles of Random Unitary Matrices. Communications in Mathematical Physics. 349 (2017): 991-1027.
“Circular ensemble”. Wikipedia.
en.wikipedia.org/wiki/Circular_ensemble

plot_eigval_hist(bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, normalize: bool = False, savefig_path: str = None) → None[source]

Computes and plots the histogram of the matrix eigenvalues.

Calculates and plots the histogram of the current sampled matrix eigenvalues. It is important to underline that this function works with real and complex eigenvalues: if the matrix eigenvalues are complex, they are plotted in the complex plane next to a heap map to study eigenvalue density.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

References

Killip, R. and Zozhan, R.
Matrix Models and Eigenvalue Statistics for Truncations of Classical Ensembles of Random Unitary Matrices. Communications in Mathematical Physics. 349 (2017): 991-1027.

resample(random_state: int = None) → ndarray[source]

Re-samples new Circular Ensemble random matrix.

It re-samples a new random matrix from the Circular ensemble. This is an alias for method sample.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample(random_state: int = None) → ndarray[source]

Samples new Circular Ensemble random matrix.

The sampling algorithm depends on the specification of beta parameter. If beta=1, COE matrix is sampled; if beta=2 CUE matrix is sampled and if beta=4 CSE matrix is sampled.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Killip, R. and Zozhan, R.
Matrix Models and Eigenvalue Statistics for Truncations of Classical Ensembles of Random Unitary Matrices. Communications in Mathematical Physics. 349 (2017): 991-1027.
“Circular ensemble”. Wikipedia.
en.wikipedia.org/wiki/Circular_ensemble

class skrmt.ensemble.GaussianEnsemble(beta: int, n: int, tridiagonal_form: bool = False, sigma: float = 1.0, random_state: int = None)[source]

Bases: BaseEnsemble

General Gaussian Ensemble class.

This class contains common attributes and methods for all the gaussian ensembles. Gaussian Ensembles are divided in: - Gaussian Orthogonal Ensemble (GOE, beta=1): the distribution of the matrices of this ensemble are invariant under orthogonal conjugation, i.e., if X is in GOE(n) and O is an orthogonal matrix, then O*X*O^T is equally distributed as X. - Gaussian Unitary Ensemble (GUE, beta=2): the distribution of the matrices of this ensemble are invariant under unitary conjugation, i.e., if X is in GUE(n) and O is an unitary matrix, then O*X*O^T is equally distributed as X. - Gaussian Symplectic Ensemble (GSE, beta=4): the distribution of the matrices of this ensemble are invariant under conjugation by the symplectic group.

matrix

instance of the GOE, GUE or GSE random matrix ensemble of size n times n if it is GOE or GUE, or of size 2n times 2n if it is GSE.

Type:: numpy array

beta

descriptive integer of the gaussian ensemble type. For GOE beta=1, for GUE beta=2, for GSE beta=4.

Type:: int

n

random matrix size. Gaussian ensemble matrices are squared matrices. GOE and GUE are of size n times n, and GSE are of size 2n times 2n.

Type:: int

tridiagonal_form

if set to True, Gaussian Ensemble matrices are sampled in its tridiagonal form, which has the same eigenvalues than its standard form. Otherwise, it is sampled using its standard form.

Type:: bool

sigma

scale (standard deviation) of the random entries of the sampled matrix.

Type:: float

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

eigval_hist(bins: int | Sequence, interval: Tuple = None, density: bool = False, normalize: bool = False, avoid_img: bool = False) → Tuple[ndarray, ndarray][source]

Calculates the histogram of the matrix eigenvalues.

Calculates the histogram of the current sampled matrix eigenvalues. Some ensembles like Gaussian (Hermite) ensemble or Wishart (Laguerre) ensemble might have improved routines to avoid calculating the eigenvalues, so instead the histogram is built using certain techniques to boost efficiency. It is important to underline that this function works with real eigenvalues, if the matrix eigenvalues are complex, they are casted to its real part.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
avoid_img (bool, default=False) – If True, eigenvalue imaginary part is ignored. This should be used when the eigenvalue compatation is expected to generate complex eigenvalues with really small imaginary part because of computing rounding errors. E.g.: MANOVA Ensemble eigenvalues.

Returns:

(tuple) tuple containing – observed (array): List of eigenvalues frequencies per bin. If density is True these values are the relative frequencies in order to get an area under the histogram equal to 1. Otherwise, this list contains the absolute frequencies of the eigenvalues. bin_edges (array): The edges of the bins. Length nbins + 1 (nbins left edges and right edge of last bin)

Raises:

ValueError if interval is not a tuple. –

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

eigvals(normalize: bool = False) → ndarray[source]

Computes the random matrix eigenvalues.

Calculates the random matrix eigenvalues using numpy standard procedure. If the matrix ensemble is symmetric, a faster algorithm is used.

Returns:: numpy array with the calculated eigenvalues.

joint_eigval_pdf(eigvals: ndarray = None) → float[source]

Computes joint eigenvalue pdf.

Calculates joint eigenvalue probability density function given an array of eigenvalues. If the array of eigenvalues is not provided, the current random matrix sample (so its eigenvalues) is used. This function depends on beta, i.e., in the sub-Gaussian ensemble.

Parameters:: eigvals (np.ndarray, default=None) – numpy array with the values (eigenvalues) to evaluate the joint pdf in.
Returns:: real number. Value of the joint pdf of the eigenvalues.

References

Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_eigval_hist(bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, normalize: bool = False, savefig_path: str = None) → None[source]

Computes and plots the histogram of the matrix eigenvalues.

Calculates and plots the histogram of the current sampled matrix eigenvalues. Gaussian (Hermite) ensemble and Wishart (Laguerre) ensemble have improved routines to avoid calculating the eigenvalues, so the histogram is built using certain techniques to boost efficiency.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are not normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

resample(tridiagonal_form: bool = None, random_state: int = None) → ndarray[source]

Re-samples a random matrix from the Gaussian ensemble with the specified form.

It re-samples a random matrix from the Gaussian ensemble with the specified form. If the specified form is different than the original form (tridiagonal vs standard) the property self.tridiagonal_form is updated and the random matrix is sampled with the updated form. If tridiagonal_form is not specified, this methods returns a re-sampled random matrix of the initialized form by calling the method sample.

Parameters:

tridiagonal_form (bool, default=None) – form to generate the new random matrix sample. If set to True, a random matrix in tridiagonal form is returned. Otherwise, the random matrix is sampled in standard form.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

Returns:

(ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample(random_state: int = None) → ndarray[source]

Samples new Gaussian Ensemble random matrix.

The sampling algorithm depends on the specification of tridiagonal_form parameter. If tridiagonal_form is set to True, a Gaussian Ensemble random matrix in its tridiagonal form is sampled. Otherwise, it is sampled using the standard form.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample_tridiagonal() → ndarray[source]

Samples a Gaussian Ensemble random matrix in its tridiagonal form.

Samples a random matrix of the specified Gaussian Ensemble (remember, beta=1 is GOE, beta=2 is GUE and beta=4 is GSE) in its tridiagonal form.

Returns:: numpy array containing new matrix sampled.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

class skrmt.ensemble.ManovaEnsemble(beta: int, m: int, n1: int, n2: int, random_state: int = None)[source]

Bases: BaseEnsemble

General Manova Ensemble class.

This class contains common attributes and methods for all the Manova ensembles. It also defines the basic interface to be supported by inherited classes. Manova Ensembles are divided in: - Manova Real Ensemble (MRE, beta=1): the random matrices of this ensemble are formed by sampling two random real standard guassian matrices (X and Y) of size m times n1 and m times n2 respectively. Then, matrix A = (X * X’) / (X * X’ + Y * Y’) generates a matrix of the Manova Real Ensemble. - Manova Complex Ensemble (MCE, beta=2): the random matrices of this ensemble are formed by sampling two random complex standard guassian matrices (X and Y) of size m times n1 and m times n2 respectively. Then, matrix A = (X * X’) / (X * X’ + Y * Y’) generates a matrix of the Manova Complex Ensemble. - Manova Quaternion Ensemble (MQE, beta=4): the random matrices of this ensemble are formed by: sampling two random complex standard guassian matrices (X1 and X2), both of size m times n1. Another two random complex standard guassian matrices (Y1 and Y2), both of size m times n2, are sampled. They are stacked forming matrices X and Y: X = [X1 X2; -conj(X2) conj(X1)] Y = [Y1 Y2; -conj(Y2) conj(Y1)] Finally, matrix A = (X * X’) / (X * X’ + Y * Y’) generates a matrix of the Manova Quaternion Ensemble of size m times m.

matrix

instance of the ManovaReal, ManovaComplex or ManovaQuaternion random ensembles. If it is an instance of ManovaReal or ManovaComplex, the random matrix is of size m times m. If it is a ManovaQuaternion, the random matrix is of size 2m times 2m.

Type:: numpy array

beta

descriptive integer of the Manova ensemble type. For Real beta=1, for Complex beta=2, for Quaternion beta=4.

Type:: int

m

number of rows of the random guassian matrices that generates the matrix of the corresponding ensemble.

Type:: int

n1

number of columns of the first random guassian matrix that generates the matrix of the corresponding ensemble.

Type:: int

n2

number of columns of the second random guassian matrix that generates the matrix of the corresponding ensemble.

Type:: int

References

Erdos, L. and Farrell, B.
“Local Eigenvalue Density for General MANOVA Matrices”. Journal of Statistical Physics. 152.6 (2013): 1003-1032.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

eigvals(normalize: bool = False) → ndarray[source]

Computes the random matrix eigenvalues.

Calculates the random matrix eigenvalues using numpy standard procedure. If the matrix ensemble is symmetric, a faster algorithm is used.

Returns:: numpy array with the calculated eigenvalues.

joint_eigval_pdf(eigvals: ndarray = None) → float[source]

Computes joint eigenvalue pdf.

Calculates joint eigenvalue probability density function given an array of eigenvalues. If the array of eigenvalues is not provided, the current random matrix sample (so its eigenvalues) is used. This function depends on beta, i.e., in the sub-Manova ensemble.

Parameters:: eigvals (np.ndarray, default=None) – numpy array with the values (eigenvalues) to evaluate the joint pdf in.
Returns:: real number. Value of the joint pdf of the eigenvalues.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_eigval_hist(bins: int | Sequence = 100, interval: Tuple = (0, 1), density: bool = False, normalize: bool = False, savefig_path: str = None) → None[source]

Computes and plots the histogram of the matrix eigenvalues

Calculates and plots the histogram of the current sampled matrix eigenvalues.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=(0,1)) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are not normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

References

Erdos, L. and Farrell, B.
“Local Eigenvalue Density for General MANOVA Matrices”. Journal of Statistical Physics. 152.6 (2013): 1003-1032.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

resample(random_state: int = None) → ndarray[source]

Re-samples new Manova Ensemble random matrix.

It re-samples a new random matrix from the Manova ensemble. This is an alias for method sample.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample(random_state: int = None) → ndarray[source]

Samples new Manova Ensemble random matrix.

The sampling algorithm depends on the specification of beta parameter. If beta=1, Manova Real is sampled; if beta=2 Manova Complex is sampled and if beta=4 Manova Quaternion is sampled.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

class skrmt.ensemble.ManovaSpectrumDistribution(ratio_a: float, ratio_b: float, beta: int = 1)[source]

Bases: rv_continuous

Manova Spectrum Distribution class.

The spectrum of the random matrices of the Manova Ensemble converge to a well-defined function implemented in this class. The class provides methods to sample values following the Manova spectrum distribution, computing the PDF, computing the CDF and simple methods to plot the former two.

a

first random matrix size ratio. This is the ratio between the number of degrees of freedom ‘p’ and the first sample size ‘n1’. The value of a = p/n1. Remember a Manova randon matrix is considered a double-Wishart matrix, that’s why there are two sample sizes ‘n1’ and ‘n2’ (see below).

Type:: float

b

second random matrix size ratio. This is the ratio between the number of degrees of freedom ‘p’ and the second sample size ‘n2’. The value of b = p/n2. Remember a Manova randon matrix is considered a double-Wishart matrix, that’s why there are two sample sizes ‘n1’ and ‘n2’.

Type:: float

beta

descriptive integer of the Manova ensemble type. For MRE beta=1, for WME beta=2, for MQE beta=4.

Type:: int, default=1

sigma

scale of the distribution. This value also corresponds to the standard deviation of the random entries of the sampled matrix.

Type:: float

lambda_minus

lower bound of the support of the Manova spectrum distribution. It depends on beta, on the scale (sigma) and on the ratio.

Type:: float

lambda_plus

upper bound of the support of the Manova spectrum distribution. It depends on beta, on the scale (sigma) and on the ratio.

Type:: float

References

Erdos, L. and Farrell, B.
“Local Eigenvalue Density for General MANOVA Matrices”. Journal of Statistical Physics. 152.6 (2013): 1003-1032.

plot_cdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the CDF of the Manova Spectrum distribution.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, a, and b.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

plot_empirical_pdf(sample_size: int = 1000, bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, plot_law_pdf: bool = False, savefig_path: str = None, random_state: int = None) → None[source]

Computes and plots Manova spectrum empirical pdf.

Calculates and plots the Manova spectrum empirical distribution by sampling random values from the Manova spectrum PDF equation. Remember that ratio_a and ratio_b will determine the shape of the distribution.

Parameters:

sample_size (int, default=1000) – number of random samples that can be interpreted as random eigenvalues of a Wigner matrix. This is the sample size.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored. If one of the bounds of the specified interval is outside of the minimum default interval, this will be adjusted to show the distribution bulk properly.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
plot_law_pdf (bool, default=False) – If True, the theoretical law is plotted. If set to False, just the empirical histogram is shown. This parameter is only considered when the argument ‘density’ is set also to True.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown are the end of the routine.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

References

Laszlo, L. and Farrel, B.
“Local Eigenvalue Density for General MANOVA Matrices”. Journal of Statistical Physics. 152.6 (2013): 1003-1032.
Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_pdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the PDF of the Manova Spectrum distribution.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, a, and b.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

class skrmt.ensemble.MarchenkoPasturDistribution(ratio: float, beta: int = 1, sigma: float = 1.0)[source]

Bases: rv_continuous

Marchenko-Pastur Distribution class.

The Marchenko-Pastur Law describes the spectrum of the Wishart random matrices. Therefore the spectrum of the random matrices of this ensemble converge to the Marchenko-Pastur Law when the matrix size goes to infinity. This class provides methods to sample eigenvalues following Marchenko-Pastur distribution, computing the PDF, computing the CDF and simple methods to plot the former two.

ratio

random matrix size ratio. This is the ratio between the number of degrees of freedom ‘p’ and the sample size ‘n’. The value of ratio = p/n.

Type:: float

beta

descriptive integer of the Wishart ensemble type. For WRE beta=1, for WCE beta=2, for WQE beta=4.

Type:: int

sigma

scale of the distribution. This value also corresponds to the standard deviation of the random entries of the sampled matrix.

Type:: float

lambda_minus

lower bound of the support of the Marchenko-Pastur Law. It depends on beta, on the scale (sigma) and on the ratio.

Type:: float

lambda_plus

upper bound of the support of the Marchenko-Pastur Law. It depends on beta, on the scale (sigma) and on the ratio.

Type:: float

References

Bar, Z.D. and Silverstain, J.W.
“Spectral Analysis of Large Dimensional Random Matrices”. 2nd edition. Springer. (2010).

ARCTAN_OF_INFTY = 1.5707963267948966

plot_cdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the CDF of the Marchenko-Pastur Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, ratio, and scale.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

plot_empirical_pdf(sample_size: int = 1000, bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, plot_law_pdf: bool = False, savefig_path: str = None, random_state: int = None) → None[source]

Computes and plots Marchenko-Pastur empirical PDF.

Calculates and plots Marchenko-Pastur law by generating samples from the known Marchenko-Pastur PDF. Remember that the ratio specified when instantiating the class will determine the shape of the distribution.

Parameters:

sample_size (int, default=1000) – number of random samples that can be interpreted as random eigenvalues of a Wigner matrix. This is the sample size.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored. If one of the bounds of the specified interval is outside of the minimum default interval, this will be adjusted to show the distribution bulk properly.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
plot_law_pdf (bool, default=False) – If True, the theoretical law is plotted. If set to False, just the empirical histogram is shown. This parameter is only considered when the argument ‘density’ is set also to True.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown are the end of the routine.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_pdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the PDF of the Marchenko-Pastur Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, ratio, and scale.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

class skrmt.ensemble.TracyWidomDistribution(beta: int = 1)[source]

Bases: rv_continuous

Tracy-Widom Distribution class.

The Tracy-Widom Law describes the behaviour of the largest eigenvalue of the Wigner random matrices. In particular, random matrices of the Gaussian Ensemble are Wigner matrices, and therefore the largest eigenvalues of the spectrum of the random matrices of this ensemble converge to the Tracy-Widom Law when the matrix size and the sample size (number of times a Wigner matrix is generated to compute the largest eigenvalue) goes to infinity. This class provides methods to sample eigenvalues following Tracy-Widom distribution, computing the PDF, computing the CDF and simple methods to plot the former two.

beta

descriptive integer of the Gaussian ensemble type. For GOE beta=1, for GUE beta=2, for GSE beta=4.

Type:: int

References

Bauman, S.
“The Tracy-Widom Distribution and its Application to Statistical Physics”. http://web.mit.edu/8.334/www/grades/projects/projects17/SamBauman.pdf MIT Department of Physics. (2017).
Tracy, C.A. and Widom, H.
“On orthogonal and symplectic matrix ensembles”. Communications in Mathematical Physics. 177.3. (1996).
Bejan, A.
“Largest eigenvalues and sample covariance matrices”. Tracy-Widom and Painleve II: Computational aspects and realization in S-Plus with applications, M.Sc. dissertation, Department of Statistics, The University of Warwick. (2005).
Borot, G. and Nadal, C.
“Right tail expansion of Tracy-Widom beta laws”. Random Matrices: Theory and Applications. 01.03. (2012).

plot_cdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the PDF of the Tracy-Widom Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

plot_empirical_pdf(sample_size: int = 1000, bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, plot_law_pdf: bool = False, savefig_path: str = None, random_state: int = None) → None[source]

Computes and plots Tracy-Widom empirical law.

Calculates and plots Tracy-Widom law by generating samples from the Tracy-Widom PDF.

Parameters:

sample_size (int, default=1000) – number of random samples that can be interpreted as random eigenvalues of a Wigner matrix. This is the sample size.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored. If one of the bounds of the specified interval is outside of the minimum default interval, this will be adjusted to show the distribution bulk properly.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
plot_law_pdf (bool, default=False) – If True, the theoretical law is plotted. If set to False, just the empirical histogram is shown. This parameter is only considered when the argument ‘density’ is set also to True.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown are the end of the routine.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_ensemble_max_eigvals(ensemble: BaseEnsemble, n_eigvals: int = 1, bins: int | Sequence = 100, random_state: int = None, savefig_path: str = None) → None[source]

Plots the histogram of the maximum eigenvalues of a random ensemble with the Tracy-Widom PDF.

It computes samples of normalized maximum eigenvalues of the specified random matrix ensemble and plots their histogram alongside the Tracy-Widom PDF. Note that only random matrices from the Gaussian ensemble are Wigner matrices, so only the largest eigenvalue of these type of random matrices follow Tracy-Widom distribution. This library provides this method to compare Tracy-Widom law with the distribution of the largest eigenvalue of any type of random ensemble.

Parameters:

ensemble (BaseEnsemble) – a random matrix ensemble instance.
n_eigvals (int, default=1) – number of maximum eigenvalues to compute. This is the number of times the random matrix is re-sampled in order to get several samples of the maximum eigenvalue.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

plot_pdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the PDF of the Tracy-Widom Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

class skrmt.ensemble.WignerSemicircleDistribution(beta: int = 1, center: float = 0.0, sigma: float = 1.0)[source]

Bases: object

Wigner Semicircle Distribution class.

The Wigner Semicircle Law describes the spectrum of the Wigner random matrices. In particular, random matrices of the Gaussian Ensemble are Wigner matrices, and therefore the spectrum of the random matrices of this ensemble converge to the Wigner Semicircle Law when the matrix size goes to infinity. This class provides methods to sample eigenvalues following Wigner Semicircle distribution, computing the PDF, computing the CDF and simple methods to plot the former two.

beta

descriptive integer of the Gaussian ensemble type. For GOE beta=1, for GUE beta=2, for GSE beta=4.

Type:: int

center

center of the distribution. Since the distribution has the shape of a semicircle, the center corresponds to its center.

Type:: float

sigma

scale of the distribution. This value also corresponds to the standard deviation of the random entries of the sampled matrix.

Type:: float

radius

radius of the semicircle of the Wigner law. This depends on the scale (sigma) and on beta.

Type:: float

References

Wigner, E.
“Characteristic Vectors of Bordered Matrices With Infinite Dimensions”. Annals of Mathematics. 62.3. (1955).
Wigner, E.
“On the Distribution of the Roots of Certain Symmetric Matrices”. Annals of Mathematics. 67.2. (1958).

cdf(x: float | ndarray) → float | ndarray[source]

Computes CDF of the Wigner Semicircle Law.

Parameters:: x (float or ndarray) – value or (numpy) array of values in which compute the CDF.
Returns:: float or numpy array with the computed CDF in the given value(s).

pdf(x: float | ndarray) → float | ndarray[source]

Computes PDF of the Wigner Semicircle Law.

Parameters:: x (float or ndarray) – value or (numpy) array of values in which compute the PDF.
Returns:: float or numpy array with the computed PDF in the given value(s).

plot_cdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the CDF of the Wigner Semicircle Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, center, radius and scale.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

plot_empirical_pdf(sample_size: int = 10000, bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, plot_law_pdf: bool = False, savefig_path: str = None, random_state: int = None) → None[source]

Computes and plots Wigner’s semicircle empirical law.

Calculates and plots Wigner’s semicircle empirical law using random samples generated using the relationship between the Wigner Semicircle law and the Beta distribution: the Wigner’s Semicircle distribution it is a scaled Beta distribution with parameters \({\alpha} = {\beta} = 3/2\).

Parameters:

sample_size (int, default=1000) – number of random samples that can be interpreted as random eigenvalues of a Wigner matrix. This is the sample size.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored. If one of the bounds of the specified interval is outside of the minimum default interval, this will be adjusted to show the distribution bulk properly.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
plot_law_pdf (bool, default=False) – If True, the theoretical law is plotted. If set to False, just the empirical histogram is shown. This parameter is only considered when the argument ‘density’ is set also to True.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown are the end of the routine.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_pdf(interval: Tuple = None, num_x_vals: int = 1000, savefig_path: str = None) → None[source]

Plots the PDF of the Wigner Semicircle Law.

Parameters:

interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. If not provided, the used interval is calculated depending on beta, center, radius and scale.
num_x_vals (int, default=1000) – It defines the number of evenly spaced x values within the given interval or range in which the function (callable) is evaluated.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

rvs(size: int | Tuple[int] = None, random_state: int = None) → ndarray[source]

Samples ranfom variates following this distribution. This uses the relationship between Wigner Semicircle law and Beta distribution.

Parameters:

size (int or tuple of ints, default=None) – sample size. If None, a single value is returned.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

Returns:

numpy array with the generated samples.

class skrmt.ensemble.WishartEnsemble(beta: int, p: int, n: int, tridiagonal_form: bool = False, sigma: float = 1.0, random_state: int = None)[source]

Bases: BaseEnsemble

General Wishart Ensemble class.

This class contains common attributes and methods for all the Wishart ensembles. Wishart Ensembles are divided in: - Wishart Real Ensemble (WRE, beta=1): the random matrices of this ensemble are formed by multiplying a random real standard gaussian matrix of size p times n by its transpose. - Wishart Complex Ensemble (WCE, beta=2): the random matrices of this ensemble are formed by multiplying a random complex standard gaussian matrix of size p times n by its transpose. - Wishart Quaternion Ensemble (WQE, beta=4): the random matrices of this ensemble are formed by: sampling two random complex standard guassian matrices (X and Y), stacking them to create matrix A = [X Y; -conj(Y) conj(X)]. Finally matrix A is multiplied by its transpose in order to generate a matrix of the Wishart Quaternion Ensemble.

matrix

instance of the WishartReal, WishartComplex or WishartQuaternion random ensembles. If it is an instance of WishartReal or WishartComplex, the random matrix is of size p times p. If it is a WishartQuaternion, the random matrix is of size 2p times 2p.

Type:: numpy array

beta

descriptive integer of the Wishart ensemble type. For Real beta=1, for Complex beta=2, for Quaternion beta=4.

Type:: int

p

number of rows of the guassian matrix that generates the matrix of the corresponding ensemble.

Type:: int

n

number of columns of the guassian matrix that generates the matrix of the corresponding ensemble.

Type:: int

tridiagonal_form

if set to True, Gaussian Ensemble matrices are sampled in its tridiagonal form, which has the same eigenvalues than its standard form. Otherwise, it is sampled using its standard form.

Type:: bool

sigma

scale (standard deviation) of the random entries of the sampled matrix.

Type:: float

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.
Bar, Z.D. and Silverstain, J.W.
Spectral Analysis of Large Dimensional Random Matrices. 2nd edition. Springer. (2010).

eigval_hist(bins: int | Sequence, interval: Tuple = None, density: bool = False, normalize: bool = False, avoid_img: bool = False) → Tuple[ndarray, ndarray][source]

Calculates the histogram of the matrix eigenvalues.

Calculates the histogram of the current sampled matrix eigenvalues. Some ensembles like Gaussian (Hermite) ensemble or Wishart (Laguerre) ensemble might have improved routines to avoid calculating the eigenvalues, so instead the histogram is built using certain techniques to boost efficiency. It is important to underline that this function works with real eigenvalues, if the matrix eigenvalues are complex, they are casted to its real part.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
avoid_img (bool, default=False) – If True, eigenvalue imaginary part is ignored. This should be used when the eigenvalue compatation is expected to generate complex eigenvalues with really small imaginary part because of computing rounding errors. E.g.: MANOVA Ensemble eigenvalues.

Returns:

(tuple) tuple containing – observed (array): List of eigenvalues frequencies per bin. If density is True these values are the relative frequencies in order to get an area under the histogram equal to 1. Otherwise, this list contains the absolute frequencies of the eigenvalues. bin_edges (array): The edges of the bins. Length nbins + 1 (nbins left edges and right edge of last bin)

Raises:

ValueError if interval is not a tuple. –

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

eigvals(normalize: bool = False) → ndarray[source]

Computes the random matrix eigenvalues.

Calculates the random matrix eigenvalues using numpy standard procedure. If the matrix ensemble is symmetric, a faster algorithm is used.

Returns:: numpy array with the calculated eigenvalues.

joint_eigval_pdf(eigvals: ndarray = None) → float[source]

Computes joint eigenvalue pdf.

Calculates joint eigenvalue probability density function given an array of eigenvalues. If the array of eigenvalues is not provided, the current random matrix sample (so its eigenvalues) is used. This function depends on beta, i.e., in the sub-Wishart ensemble.

Parameters:: eigvals (np.ndarray, default=None) – numpy array with the values (eigenvalues) to evaluate the joint pdf in.
Returns:: real number. Value of the joint pdf of the eigenvalues.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

plot_eigval_hist(bins: int | Sequence = 100, interval: Tuple = None, density: bool = False, normalize: bool = False, savefig_path: str = None) → None[source]

Computes and plots the histogram of the matrix eigenvalues.

Calculates and plots the histogram of the current sampled matrix eigenvalues. Gaussian (Hermite) ensemble and Wishart (Laguerre) ensemble have improved routines to avoid calculating the eigenvalues, so the histogram is built using certain techniques to boost efficiency.

Parameters:

bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
interval (tuple, default=None) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.
normalize (bool, default=False) – Whether to normalize the computed eigenvalues by the default normalization constant (see references). Defaults to False, i.e., the eigenvalues are not normalized. Normalization makes the eigenvalues to be in the same support independently of the sample size.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A.
“Matrix Models for Beta Ensembles”. Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

resample(tridiagonal_form: bool = None, random_state: int = None) → ndarray[source]

Re-samples a random matrix from the Wishart ensemble with the specified form.

It re-samples a random matrix from the Wishart ensemble with the specified form. If the specified form is different than the original form (tridiagonal vs standard) the property self.tridiagonal_form is updated and the random matrix is sampled with the updated form. If tridiagonal_form is not specified, this methods returns a re-sampled random matrix of the initialized form by calling the method sample.

Parameters:

tridiagonal_form (bool, default=None) – form to generate the new random matrix sample. If set to True, a random matrix in tridiagonal form is returned. Otherwise, the random matrix is sampled in standard form.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

Returns:

(ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample(random_state: int = None) → ndarray[source]

Samples new Wishart Ensemble random matrix.

The sampling algorithm depends on the specification of tridiagonal_form parameter. If tridiagonal_form is set to True, a Wishart Ensemble random matrix in its tridiagonal form is sampled. Otherwise, it is sampled using the standard form.

Parameters:: random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.
Returns:: (ndarray) numpy array containing new matrix sampled.

References

Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

sample_tridiagonal() → ndarray[source]

Samples a Wishart Ensemble random matrix in its tridiagonal form.

Samples a random matrix of the specified Wishart Ensemble (remember, beta=1 is Real, beta=2 is Complex and beta=4 is Quaternion) in its tridiagonal form.

Returns:: numpy array containing new matrix sampled.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

skrmt.ensemble.householder_reduction(mtx: ndarray, ret_iterations: bool = False) → Tuple[ndarray, ndarray, ndarray][source]

Householder reduction method for tridiagonalization.

Computes Householder reduction method for tridiagonalization. It transforms a given symmetric matrix in its tridiagonal form, keeping the same eigenvalues as the original.

Parameters:

mtx (numpy array) – symmetric matrix to be tridiagonalized.
ret_iterations (bool, default=False) – If set to True, it returns rotation matrices used to perform the tridiagonalization.

Returns:

(tuple) tuple containing – mtx (nparray): tridiagonalized matrix. mtx_list (nparray): list of matrices representing the evolution of the given matrix

after each rotation. Only returned if ret_iterations is set to True.

rot_list (nparray): list of applied rotation matrices. Only returned if ret_iterations is set to True.

References

1. Hildebrand. “Householder numerically with mathematica.” 2007.
http://buzzard.ups.edu/courses/2007spring/projects/hildebrand-paper-revised.pdf

skrmt.ensemble.plot_spectral_hist_and_law(ensemble: BaseEnsemble, bins: int | Sequence = 100, savefig_path: str = None) → None[source]

Plots the spectrum histogram of a random matrix ensemble alongside the PDF of the corresponding spectral law.

It illustrates the histogram of the spectrum of a given random matrix ensemble alongside the PDF of the corresponding spectral law, i.e.: - If ensemble is GaussianEnsemble then is plotted Wigner’s Semicircle law PDF. - If ensemble is WishartEnsemble then is plotted Marchenko-Pastur law PDF. - If ensemble is ManovaEnsemble then is plotted the PDF of the Manova ensemble formulated by Wachter.

Parameters:

ensemble (BaseEnsemble) – a random matrix ensemble instance. The only supported types are GaussianEnsemble, WishartEnsemble and ManovaEnsemble.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.

skrmt.ensemble.standard_vs_tridiag_hist(ensemble: GaussianEnsemble | WishartEnsemble, bins: int | Sequence = 100, savefig_path: str = None, random_state: int = None) → None[source]

Plots and compares the spectral histogram of a random matrix using its standard form vs using the corresponding tridiagonal form.

This function simulates the histogramming of a given random matrix ensemble in its standard form and it compares the former with the equivalent histogram computed using the tridiagonal matrix form. This is useful to illustrate both types of matrix have the same spectral distribution.

Parameters:

ensemble (BaseEnsemble) – a random matrix ensemble instance. The only supported types are GaussianEnsemble and WishartEnsemble, since spectral optimizations based on their tridiagonal forms are known.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
savefig_path (string, default=None) – path to save the created figure. If it is not provided, the plot is shown at the end of the routine.
random_state (int, default=None) – random seed to initialize the pseudo-random number generator of numpy. This has to be any integer between 0 and 2**32 - 1 (inclusive), or None (default). If None, the seed is obtained from the clock.

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.

skrmt.ensemble.tridiag_eigval_hist(tridiag_mtx: ndarray, interval: Tuple, bins: int | Sequence = 100, density: bool = False) → Tuple[ndarray, ndarray][source]

Computes efficiently eigenvalue histogram.

Calculates the eigenvalue histogram of the given matrix, using the specified bins between the introduced interval. The given matrix has to be tridiagonal, so this function builds the histogram efficiently using Sturm sequences, avoiding to calculate eigenvalues.

Parameters:

tridiag_mtx (numpy array) – tridiagonal matrix
interval (tuple) – Delimiters (xmin, xmax) of the histogram. The lower and upper range of the bins. Lower and upper outliers are ignored.
bins (int or sequence, default=100) – If bins is an integer, it defines the number of equal-width bins in the range. If bins is a sequence, it defines the bin edges, including the left edge of the first bin and the right edge of the last bin; in this case, bins may be unequally spaced.
density (bool, default=False) – If True, draw and return a probability density: each bin will display the bin’s raw count divided by the total number of counts and the bin width, so that the area under the histogram integrates to 1. If set to False, the absolute frequencies of the eigenvalues are returned.

Returns:

(tuple) tuple containing – observed (array): List of eigenvalues frequencies per bin. If density is True these values are the relative frequencies in order to get an area under the histogram equal to 1. Otherwise, this list contains the absolute frequencies of the eigenvalues. bin_delimiters (array): The edges of the bins. Length nbins + 1 (nbins left edges and right edge of last bin).

References

Albrecht, J. and Chan, C.P. and Edelman, A.
“Sturm sequences and random eigenvalue distributions”. Foundations of Computational Mathematics. 9.4 (2008): 461-483.
Dumitriu, I. and Edelman, A. “Matrix Models for Beta Ensembles”.
Journal of Mathematical Physics. 43.11 (2002): 5830-5847.