Developer Reference for Intel® oneAPI Math Kernel Library for C
?latms
Generates a general m -by- n matrix with specific singular values.
Syntax
lapack_intLAPACKE_slatms ( intmatrix_layout , lapack_intm , lapack_intn , chardist , lapack_int*iseed , charsym , float*d , lapack_intmode , floatcond , floatdmax , lapack_intkl , lapack_intku , charpack , float*a , lapack_intlda );
lapack_intLAPACKE_dlatms ( intmatrix_layout , lapack_intm , lapack_intn , chardist , lapack_int*iseed , charsym , double*d , lapack_intmode , doublecond , doubledmax , lapack_intkl , lapack_intku , charpack , double*a , lapack_intlda );
lapack_intLAPACKE_clatms ( intmatrix_layout , lapack_intm , lapack_intn , chardist , lapack_int*iseed , charsym , float*d , lapack_intmode , floatcond , floatdmax , lapack_intkl , lapack_intku , charpack , lapack_complex_float*a , lapack_intlda );
lapack_intLAPACKE_zlatms ( intmatrix_layout , lapack_intm , lapack_intn , chardist , lapack_int*iseed , charsym , double*d , lapack_intmode , doublecond , doubledmax , lapack_intkl , lapack_intku , charpack , lapack_complex_double*a , lapack_intlda );
Include Files
mkl.h
Description
slatms dlatms clatms zlatms
The ?latms routine generates random matrices with specified singular values, or symmetric/Hermitian matrices with specified eigenvalues for testing LAPACK programs.
It applies this sequence of operations:
Set the diagonal to d , where d is input or computed according to mode , cond , dmax , and sym as described in Input Parameters.
Generate a matrix with the appropriate band structure, by one of two methods:
Method A
Generate a dense m -by- n matrix by multiplying d on the left and the right by random unitary matrices, then:
Reduce the bandwidth according to kl and ku , using Householder transformations.
Method B:
Convert the bandwidth-0 (i.e., diagonal) matrix to a bandwidth-1 matrix using Givens rotations, “chasing” out-of-band elements back, much as in QR; then convert the bandwidth-1 to a bandwidth-2 matrix, etc.
Note that for reasonably small bandwidths (relative to m and n ) this requires less storage, as a dense matrix is not generated. Also, for symmetric or Hermitian matrices, only one triangle is generated.
Method A is chosen if the bandwidth is a large fraction of the order of the matrix, and lda is at least m (so a dense matrix can be stored.) Method B is chosen if the bandwidth is small (less than (1/2)* n for symmetric or Hermitian or less than .3* n + m for nonsymmetric), or lda is less than m and not less than the bandwidth.
Pack the matrix if desired, using one of the methods specified by the pack parameter.
If Method B is chosen and band format is specified, then the matrix is generated in the band format and no repacking is necessary.
Input Parameters
A <datatype> placeholder, if present, is used for the C interface data types in the C interface section above. See C Interface Conventions for the C interface principal conventions and type definitions.
- matrix_layout
-
Specifies whether matrix storage layout is row major ( LAPACK_ROW_MAJOR ) or column major ( LAPACK_COL_MAJOR ).
m
The number of rows of the matrix A ( m≥ 0 ).
n
The number of columns of the matrix A ( n≥ 0 ).
dist
Specifies the type of distribution to be used to generate the random singular values or eigenvalues:
iseed
Array with size 4.
Specifies the seed of the random number generator. Values should lie between 0 and 4095 inclusive, and iseed(4)iseed[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. The values of the array are modified, and can be used in the next call to ?latms to continue the same random number sequence.
- sym
-
CHARACTER*1 . If sym =’S’ or ‘H’, the generated matrix is symmetric or Hermitian, with eigenvalues specified by d , cond , mode , and dmax ; they can be positive, negative, or zero. If sym =’P’, the generated matrix is symmetric or Hermitian, with eigenvalues (which are singular, non-negative values) specified by d , cond , mode , and dmax . If sym =’N’, the generated matrix is nonsymmetric, with singular, non-negative values specified by d , cond , mode , and dmax .
- d
-
REAL for slatms and clatms DOUBLE PRECISION for dlatms and zlatms Array, size (MIN( m , n )) This array is used to specify the singular values or eigenvalues of A (see the description of sym ). If mode =0, then d is assumed to contain the eigenvalues or singular values, otherwise elements of d are computed according to mode , cond , and dmax .
mode
Describes how the singular/eigenvalues are specified.
mode < 0 has the same meaning as ABS( mode ), except that the order of the elements of d is reversed. Thus, if mode is positive, d has entries ranging from 1 to 1/ cond , if negative, from 1/ cond to 1. If sym =’S’ or ‘H’, and mode is not 0, 6, nor -6, then the elements of d are also given a random sign (multiplied by +1 or -1).
- cond
-
REAL for slatms and clatms DOUBLE PRECISION for dlatms and zlatms Used in setting d as described for the mode parameter. If used, cond ≥ 1.
- dmax
-
REAL for slatms and clatms DOUBLE PRECISION for dlatms and zlatms If mode is not -6, 0 nor 6, the contents of d , as computed according to mode and cond , are scaled by dmax / max(abs(d(i)))dmax / max(abs(d[i-1])) ; thus, the maximum absolute eigenvalue or singular value (the norm) is abs(dmax) .
kl
Specifies the lower bandwidth of the matrix. For example, kl =0 implies upper triangular, kl =1 implies upper Hessenberg, and kl being at least m - 1 means that the matrix has full lower bandwidth. kl must equal ku if the matrix is symmetric or Hermitian.
ku
Specifies the upper bandwidth of the matrix. For example, ku =0 implies lower triangular, ku =1 implies lower Hessenberg, and ku being at least n - 1 means that the matrix has full upper bandwidth. kl must equal ku if the matrix is symmetric or Hermitian.
pack
Specifies packing of matrix:
Using these options, the various LAPACK packed and banded storage schemes can be obtained: If two calls to ?latms differ only in the pack parameter, they generate mathematically equivalent matrices.
lda
lda specifies the first dimension of a as declared in the calling program.
If pack =’N’, ‘U’, ‘L’, ‘C’, or ‘R’, then lda must be at least m for column major or at least n for row major .
If pack =’B’ or ‘Q’, then lda must be at least MIN(kl, m - 1) (which is equal to MIN( ku , n - 1)). If pack =’Z’, lda must be large enough to hold the packed array: MIN( ku, n - 1) + MIN( kl, m - 1) + 1 .
Output Parameters
- iseed
-
The array iseed contains the updated seed.
- d
-
The array d contains the updated seed.
- a
-
REAL for slatms DOUBLE PRECISION for dlatms COMPLEX for clatms DOUBLE COMPLEX for zlatms Array of size lda by n . The array a contains the generated m -by- n matrix A . a is first generated in full (unpacked) form, and then packed, if so specified by pack . Thus, the first m elements of the first n columns are always modified. If pack specifies a packed or banded storage scheme, all lda elements of the first n columns are modified; the elements of the array which do not correspond to elements of the generated matrix are set to zero.
- work
-
REAL for slatms DOUBLE PRECISION for dlatms COMPLEX for clatms DOUBLE COMPLEX for zlatms Array of size (3*MAX( n , m )) Workspace.
Return Values
This function returns a value info .