Developer Reference for Intel® oneAPI Math Kernel Library for C
?latme
Generates random non-symmetric square matrices with specified eigenvalues.
Syntax
void slatme ( lapack_int*n , char*dist , lapack_int*iseed , float*d , lapack_int*mode , float*cond , float*dmax , char*ei , char*rsign , char*upper , char*sim , float*ds , lapack_int*modes , float*conds , lapack_int*kl , lapack_int*ku , float*anorm , float*a , lapack_int*lda , float*work , lapack_int*info );
void dlatme ( lapack_int*n , char*dist , lapack_int*iseed , double*d , lapack_int*mode , double*cond , double*dmax , char*ei , char*rsign , char*upper , char*sim , double*ds , lapack_int*modes , double*conds , lapack_int*kl , lapack_int*ku , double*anorm , double*a , lapack_int*lda , double*work , lapack_int*info );
void clatme ( lapack_int*n , char*dist , lapack_int*iseed , lapack_complex_float*d , lapack_int*mode , float*cond , lapack_complex_float*dmax , char*ei , char*rsign , char*upper , char*sim , float*ds , lapack_int*modes , float*conds , lapack_int*kl , lapack_int*ku , float*anorm , lapack_complex_float*a , lapack_int*lda , lapack_complex_float*work , lapack_int*info );
void zlatme ( lapack_int*n , char*dist , lapack_int*iseed , lapack_complex_double*d , lapack_int*mode , double*cond , lapack_complex_double*dmax , char*ei , char*rsign , char*upper , char*sim , double*ds , lapack_int*modes , double*conds , lapack_int*kl , lapack_int*ku , double*anorm , lapack_complex_double*a , lapack_int*lda , lapack_complex_double*work , lapack_int*info );
Include Files
mkl.h
Description
slatme dlatme clatme zlatme
The ?latme routine generates random non-symmetric square matrices with specified eigenvalues. ?latme operates by applying the following sequence of operations:
Set the diagonal to d , where d may be input or computed according to mode , cond , dmax , and rsign as described below.
If upper = 'T' , the upper triangle of a is set to random values out of distribution dist .
If sim='T' , a is multiplied on the left by a random matrix X , whose singular values are specified by ds , modes , and conds , and on the right by X inverse.
If kl < n-1 , the lower bandwidth is reduced to kl using Householder transformations. If ku < n-1 , the upper bandwidth is reduced to ku .
If anorm is not negative, the matrix is scaled to have maximum-element-norm anorm .
Input Parameters
n
The number of columns (or rows) of A .
dist
On entry, dist specifies the type of distribution to be used to generate the random eigen-/singular values, and on the upper triangle (see upper ).
If dist = 'U' : uniform( 0, 1 ) If dist = 'S' : uniform( -1, 1 ) If dist = 'N' : normal( 0, 1 ) If dist = 'D' : uniform on the complex disc | z | < 1.
iseed
Array, size 4.
On entry iseed specifies the seed of the random number generator. The elements should lie between 0 and 4095 inclusive, and iseed(4)[3] should be odd. The random number generator uses a linear congruential sequence limited to small integers, and so should produce machine independent random numbers.
- d
-
REAL for slatme , DOUBLE PRECISION for dlatme , COMPLEX for clatme , DOUBLE COMPLEX for zlatme , Array, size ( n ). This array is used to specify the eigenvalues of A . If mode = 0 , then d is assumed to contain the eigenvalues. Otherwise they are computed according to mode , cond , dmax , and rsign and placed in d .
mode
On entry mode describes how the eigenvalues are to be specified:
mode = 0 means use d (with ei for slatme and dlatme ) as input. mode = 1 sets d(1)[0]= 1 and d[1:n - 1](2:n]=1.0/cond . mode = 2 sets d(1:n-1)[0:n - 2]= 1 and d(n)[n - 1]=1.0/cond . mode = 3 sets d(i)[i - 1]= cond**(-(i-1)/(n-1)) . mode = 4 sets d(i)[i - 1]= 1 - (i-1)/(n-1)*(1 - 1/cond) . mode = 5 sets d to random numbers in the range ( 1/cond , 1 ) such that their logarithms are uniformly distributed. mode = 6 sets d to random numbers from same distribution as the rest of the matrix. mode < 0 has the same meaning as abs(mode) , except that the order of the elements of d is reversed. Thus if mode is between 1 and 4, d has entries ranging from 1 to 1/ cond , if between -1 and -4, d has entries ranging from 1/ cond to 1.
- cond
-
REAL for slatme , DOUBLE PRECISION for dlatme , REAL for clatme , DOUBLE PRECISION for zlatme , On entry, this is used as described under mode above. If used, it must be ≥ 1.
- dmax
-
REAL for slatme , DOUBLE PRECISION for dlatme , COMPLEX for clatme , DOUBLE COMPLEX for zlatme , If mode is not -6, 0 or 6, the contents of d as computed according to mode and cond are scaled by dmax / max(abs(d(i)[i - 1])) . Note that dmax needs not be positive or real: if dmax is negative or complex (or zero), d will be scaled by a negative or complex number (or zero). If rsign='F' then the largest (absolute) eigenvalue will be equal to dmax .
ei
Used by slatme and dlatme only.
Array, size ( n ). If mode = 0 , and ei(1)[0] is not ‘ ‘ (space character), this array specifies which elements of d (on input) are real eigenvalues and which are the real and imaginary parts of a complex conjugate pair of eigenvalues. The elements of ei may then only have the values ‘R’ and ‘I’ . If ei(j)[j - 1]= 'R' and ei(j + 1)[j]= 'I' , then the j -th eigenvalue is cmplx( d(j)[j - 1] , d(j + 1)[j] ), and the ( j +1)-th is the complex conjugate thereof. If ei(j)[j - 1]= ei(j + 1)[j]='R' , then the j -th eigenvalue is d(j)[j - 1] (i.e., real). ei(1)[0] may not be ‘I’ , nor may two adjacent elements of ei both have the value ‘I’ . If mode is not 0, then ei is ignored. If mode is 0 and ei(1)[0] = ' ' , then the eigenvalues will all be real.
rsign
If mode is not 0, 6, or -6, and rsign = 'T' , then the elements of d , as computed according to mode and cond , are multiplied by a random sign (+1 or -1) for slatme and dlatme or by a complex number from the unit circle | z | = 1 for clatme and zlatme .
If rsign = 'F' , the elements of d are not multiplied. rsign may only have the values ‘T’ or ‘F’ .
upper
If upper = 'T' , then the elements of a above the diagonal will be set to random numbers out of dist .
If upper = 'F' , they will not. upper may only have the values ‘T’ or ‘F’ .
sim
If sim = 'T' , then a will be operated on by a “similarity transform”, i.e., multiplied on the left by a matrix X and on the right by X inverse. X = USV , where U and V are random unitary matrices and S is a (diagonal) matrix of singular values specified by ds , modes , and conds .
If sim = 'F' , then a will not be transformed.
- ds
-
REAL for slatme , DOUBLE PRECISION for dlatme , REAL for clatme , DOUBLE PRECISION for zlatme , This array is used to specify the singular values of X , in the same way that d specifies the eigenvalues of a . If mode = 0 , the ds contains the singular values, which may not be zero.
modes
Similar to mode , but for specifying the diagonal of S . modes = -6 and +6 are not allowed (since they would result in randomly ill-conditioned eigenvalues.)
- conds
-
REAL for slatme , DOUBLE PRECISION for dlatme , REAL for clatme , DOUBLE PRECISION for zlatme , Similar to cond , but for specifying the diagonal of S .
kl
This specifies the lower bandwidth of the matrix. kl = 1 specifies upper Hessenberg form. If kl is at least n -1, then A will have full lower bandwidth.
ku
This specifies the upper bandwidth of the matrix. ku = 1 specifies lower Hessenberg form.
If ku is at least n -1, then a will have full upper bandwidth. If ku and ku are both at least n -1, then a will be dense. Only one of ku and kl may be less than n -1.
- anorm
-
REAL for slatme , DOUBLE PRECISION for dlatme , REAL for clatme , DOUBLE PRECISION for zlatme , If anorm is not negative, then a is scaled by a non-negative real number to make the maximum-element-norm of a to be anorm .
lda
Number of rows of matrix A .
- work
-
REAL for slatme , DOUBLE PRECISION for dlatme , COMPLEX for clatme , DOUBLE COMPLEX for zlatme , Array, size (3*n). Workspace.
Output Parameters
- iseed
-
INTEGER . On exit, the seed is updated.
- d
-
Modified if mode is nonzero.
- ds
-
Modified if mode is nonzero.
- a
-
REAL for slatme , DOUBLE PRECISION for dlatme , COMPLEX for clatme , DOUBLE COMPLEX for zlatme ,
Array, size (lda, n)lda * n . On exit, a is the desired test matrix.
info
INTEGER .
If info = 0 , execution is successful.
If info = -1 , n is negative .
If info = -2 , dist is an illegal string.
If info = -5 , mode is not in range -6 to 6.
If info = -6 , cond is less than 1.0, and mode is not -6, 0, or 6 .
If info = -9 , rsign is not ‘T’ or ‘F’ .
If info = -10 , upper is not ‘T’ or ‘F’ .
If info = -11 , sim is not ‘T’ or ‘F’ .
If info = -12 , modes = 0 and ds has a zero singular value.
If info = -13 , modes is not in the range -5 to 5.
If info = -14 , modes is nonzero and conds is less than 1. .
If info = -15 , kl is less than 1.
If info = -16 , ku is less than 1, or kl and ku are both less than n -1.
If info = -19 , lda is less than m .
If info = 1 , error return from ?latm1 (computing d ) .
If info = 2 , cannot scale to dmax (max. eigenvalue is 0) .
If info = 3 , error return from slatm1 (for slatme and clatme ), dlatm1 (for dlatme and zlatme ) .
If info = 4 , error return from ?large .
If info = 5 , zero singular value from slatm1 (for slatme and clatme ), dlatm1 (for dlatme and zlatme ).