?latme

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

Download PDF

ID 766686

Date 3/31/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-7C50E16A-B5DF-4BEE-A0C4-B29CF566341A

View Details

?latme

Generates random non-symmetric square matrices with specified eigenvalues.

Syntax

call slatme( n, dist, iseed, d, mode, cond, dmax, ei, rsign, upper, sim, ds, modes, conds, kl, ku, anorm, a, lda, work, info )

call dlatme( n, dist, iseed, d, mode, cond, dmax, ei, rsign, upper, sim, ds, modes, conds, kl, ku, anorm, a, lda, work, info )

call clatme( n, dist, iseed, d, mode, cond, dmax, ei, rsign, upper, sim, ds, modes, conds, kl, ku, anorm, a, lda, work, info )

call zlatme( n, dist, iseed, d, mode, cond, dmax, ei, rsign, upper, sim, ds, modes, conds, kl, ku, anorm, a, lda, work, info )

Include Files

mkl.fi

Description

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.

NOTE:

Since the matrix cannot be reduced beyond Hessenberg form, no packing options are available.

Input Parameters

n

INTEGER. The number of columns (or rows) of A.

dist

CHARACTER*1. 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

INTEGER. 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) 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

INTEGER. 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) = 1 and d[1:n - 1]=1.0/cond.

mode = 2 sets d(1:n-1) = 1 and d(n)=1.0/cond.

mode = 3 sets d(i) = cond**(-(i-1)/(n-1)).

mode = 4 sets d(i) = 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))). 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

CHARACTER*1. Used by slatme and dlatme only.

Array, size (n).

If mode = 0, and ei(1)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) = 'R' and ei(j + 1) = 'I', then the j -th eigenvalue is cmplx( d(j) , d(j + 1) ), and the (j +1)-th is the complex conjugate thereof.

If ei(j) = ei(j + 1)='R', then the j-th eigenvalue is d(j) (i.e., real). ei(1) 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) = ' ', then the eigenvalues will all be real.

rsign

CHARACTER*1. 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

CHARACTER*1. 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

CHARACTER*1. 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

INTEGER.

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

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

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

INTEGER. 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). 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).

Parent topic: LAPACK Auxiliary 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 Fortran

?latme