?latms

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 11/07/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-92FC66BD-D5B3-4D87-AC52-994CFE93132D

View Details

?latms

Generates a general m-by-n matrix with specific singular values.

Syntax

lapack_int LAPACKE_slatms (int matrix_layout, lapack_int m, lapack_int n, char dist, lapack_int * iseed, char sym, float * d, lapack_int mode, float cond, float dmax, lapack_int kl, lapack_int ku, char pack, float * a, lapack_int lda);

lapack_int LAPACKE_dlatms (int matrix_layout, lapack_int m, lapack_int n, char dist, lapack_int * iseed, char sym, double * d, lapack_int mode, double cond, double dmax, lapack_int kl, lapack_int ku, char pack, double * a, lapack_int lda);

lapack_int LAPACKE_clatms (int matrix_layout, lapack_int m, lapack_int n, char dist, lapack_int * iseed, char sym, float * d, lapack_int mode, float cond, float dmax, lapack_int kl, lapack_int ku, char pack, lapack_complex_float * a, lapack_int lda);

lapack_int LAPACKE_zlatms (int matrix_layout, lapack_int m, lapack_int n, char dist, lapack_int * iseed, char sym, double * d, lapack_int mode, double cond, double dmax, lapack_int kl, lapack_int ku, char pack, lapack_complex_double * a, lapack_int lda);

Include Files

mkl.h

Description

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:

'U': uniform distribution (0, 1)
'S': symmetric uniform distribution (-1, 1)
'N': normal distribution (0, 1)

iseed

Array with size 4.

Specifies the seed of the random number generator. Values should lie between 0 and 4095 inclusive, and 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

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

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: use d as input
mode = 1: set d[0] = 1 and d[1:n - 1] = 1.0/cond
mode = 2: set d[0:n - 2] = 1 and d[n - 1] = 1.0/cond
mode = 3: set d[i] = cond^{-i/(n - 1)}
mode = 4: set d[i] = 1 - i/(n - 1)*(1 - 1/cond)
mode = 5: set elements of d to random numbers in the range (1/cond , 1) such that their logarithms are uniformly distributed.
mode = 6: set elements of 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 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

Used in setting d as described for the mode parameter. If used, cond≥ 1.

dmax

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-1])); thus, the maximum absolute eigenvalue or singular value (the norm) is abs(dmax).

NOTE:

dmax need not be positive: if dmax is negative (or zero), d will be scaled by a negative number (or zero).

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:

'N': no packing
'U': zero out all subdiagonal entries (if symmetric or Hermitian)
'L': zero out all superdiagonal entries (if symmetric or Hermitian)
'B': store the lower triangle in band storage scheme (only if matrix symmetric, Hermitian, or lower triangular)
'Q': store the upper triangle in band storage scheme (only if matrix symmetric, Hermitian, or upper triangular)
'Z': store the entire matrix in band storage scheme (pivoting can be provided for by using this option to store A in the trailing rows of the allocated storage)

Using these options, the various LAPACK packed and banded storage schemes can be obtained:

	'Z'	'B'	'Q'	'C'	'R'
GB: general band	x
PB: symmetric positive definite band		x	x
SB: symmetric band		x	x
HB: Hermitian band		x	x
TB: triangular band		x	x
PP: symmetric positive definite packed				x	x
SP: symmetric packed				x	x
HP: Hermitian packed				x	x
TP: triangular packed				x	x

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.

NOTE:

The array d is not modified if mode = 0.

a

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.

Return Values

This function returns a value info.

If info = 0, the execution is successful.

If info < 0, the i-th parameter had an illegal value.

If info = -1011, memory allocation error occurred.

If info = 2, cannot scale to dmax (maximum singular value is 0).

If info = 3, error return from lagge, ?laghe, or lagsy.

Parent topic: LAPACK Test Functions and Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

?latms

Syntax

Include Files

Description

Input Parameters

Output Parameters

Return Values