?latmr

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

Download PDF

ID 766686

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-B80D0F26-C8F1-4D7B-806A-9D68D33FA201

View Details

?latmr

Generates random matrices of various types.

Syntax

call slatmr (m, n, dist, iseed, sym, d, mode, cond, dmax, rsign, grade, dl, model, condl, dr, moder, condr, pivtng, ipivot, kl, ku, sparse, anorm, pack, a, lda, iwork, info)

call dlatmr (m, n, dist, iseed, sym, d, mode, cond, dmax, rsign, grade, dl, model, condl, dr, moder, condr, pivtng, ipivot, kl, ku, sparse, anorm, pack, a, lda, iwork, info)

call clatmr (m, n, dist, iseed, sym, d, mode, cond, dmax, rsign, grade, dl, model, condl, dr, moder, condr, pivtng, ipivot, kl, ku, sparse, anorm, pack, a, lda, iwork, info)

call zlatmr (m, n, dist, iseed, sym, d, mode, cond, dmax, rsign, grade, dl, model, condl, dr, moder, condr, pivtng, ipivot, kl, ku, sparse, anorm, pack, a, lda, iwork, info)

Description

The ?latmr routine operates by applying the following sequence of operations:

Generate a matrix A with random entries of distribution dist:

If sym = 'S', the matrix is symmetric,

If sym = 'H', the matrix is Hermitian,

If sym = 'N', the matrix is nonsymmetric.
Set the diagonal to D, where D may be input or computed according to mode, cond, dmax and rsign as described below.
Grade the matrix, if desired, from the left or right as specified by grade. The inputs dl, model, condl, dr, moder and condr also determine the grading as described below.
Permute, if desired, the rows and/or columns as specified by pivtng and ipivot.
Set random entries to zero, if desired, to get a random sparse matrix as specified by sparse.
Make A a band matrix, if desired, by zeroing out the matrix outside a band of lower bandwidth kl and upper bandwidth ku.
Scale A, if desired, to have maximum entry anorm.
Pack the matrix if desired. See options specified by the pack parameter.

NOTE:

If two calls to ?latmr differ only in the pack parameter, they generate mathematically equivalent matrices. If two calls to ?latmr both have full bandwidth (kl = m-1 and ku = n-1), and differ only in the pivtng and pack parameters, then the matrices generated differ only in the order of the rows and columns, and otherwise contain the same data. This consistency cannot be and is not maintained with less than full bandwidth.

Input Parameters

m

INTEGER. Number of rows of A.

n

INTEGER. Number of columns of A.

dist

CHARACTER. On entry, dist specifies the type of distribution to be used to generate a random matrix .

If dist = 'U', real and imaginary parts are independent uniform( 0, 1 ).

If dist = 'S', real and imaginary parts are independent uniform( -1, 1 ).

If dist = 'N', real and imaginary parts are independent normal( 0, 1 ).

If dist = 'D', distribution is uniform on interior of unit disk.

iseed

INTEGER. Array, size 4.

On entry, iseed specifies the seed of the random number generator. They 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.

sym

CHARACTER. If sym = 'S', generated matrix is symmetric.

If sym = 'H', generated matrix is Hermitian.

If sym = 'N', generated matrix is nonsymmetric.

d

REAL for slatmr,

DOUBLE PRECISION for dlatmr,

COMPLEX for clatmr,

DOUBLE COMPLEX for zlatmr,

On entry this array specifies the diagonal entries of the diagonal of A. d may either be specified on entry, or set according to mode and cond as described below. If the matrix is Hermitian, the real part of d is taken. May be changed on exit if mode is nonzero.

mode

INTEGER. On entry describes how d is to be used:

mode = 0 means use d as input.

mode = 1 sets d(1)=1 and d(2:n)=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 slatmr,

DOUBLE PRECISION for dlatmr,

REAL for clatmr,

DOUBLE PRECISION for zlatmr,

On entry, used as described under mode above. If used, cond must be ≥ 1.

dmax

REAL for slatmr,

DOUBLE PRECISION for dlatmr,

COMPLEX for clatmr,

DOUBLE COMPLEX for zlatmr,

If mode is not -6, 0, or 6, the diagonal is scaled by dmax / max(abs(d(i))), so that maximum absolute entry of diagonal is abs(dmax). If dmax is complex (or zero), the diagonal is scaled by a complex number (or zero).

rsign

CHARACTER. If mode is not -6, 0, or 6, specifies the sign of the diagonal as follows:

For slatmr and dlatmr, if rsign = 'T', diagonal entries are multiplied 1 or -1 with a probability of 0.5.

For clatmr and zlatmr, if rsign = 'T', diagonal entries are multiplied by a random complex number uniformly distributed with absolute value 1.

If rsign = 'F', diagonal entries are unchanged.

grade

CHARACTER. Specifies grading of matrix as follows:

If grade = 'N', there is no grading

If grade = 'L', matrix is premultiplied by diag( dl) (only if matrix is nonsymmetric)

If grade = 'R', matrix is postmultiplied by diag( dr ) (only if matrix is nonsymmetric)

If grade = 'B', matrix is premultiplied by diag( dl ) and postmultiplied by diag( dr ) (only if matrix is nonsymmetric)

If grade = 'H', matrix is premultiplied by diag( dl ) and postmultiplied by diag( conjg(dl) ) (only if matrix is Hermitian or nonsymmetric)

If grade = 'S', matrix is premultiplied by diag(dl ) and postmultiplied by diag( dl ) (only if matrix is symmetric or nonsymmetric)

If grade = 'E', matrix is premultiplied by diag( dl ) and postmultiplied by inv( diag( dl ) ) (only if matrix is nonsymmetric)

NOTE:

if grade = 'E', then m must equal n.

dl

REAL for slatmr,

DOUBLE PRECISION for dlatmr,

COMPLEX for clatmr,

DOUBLE COMPLEX for zlatmr,

Array, size (m).

If model = 0, then on entry this array specifies the diagonal entries of a diagonal matrix used as described under grade above.

If model is not zero, then dl is set according to model and condl, analogous to the way D is set according to mode and cond (except there is no dmax parameter for dl).

If grade = 'E', then dl cannot have zero entries.

Not referenced if grade = 'N' or 'R'. Changed on exit.

model

INTEGER. This specifies how the diagonal array dl is computed, just as mode specifies how D is computed.

condl

REAL for slatmr,

DOUBLE PRECISION for dlatmr,

REAL for clatmr,

DOUBLE PRECISION for zlatmr,

When model is not zero, this specifies the condition number of the computed dl.

dr

REAL for slatmr,

DOUBLE PRECISION for dlatmr,

COMPLEX for clatmr,

DOUBLE COMPLEX for zlatmr,

If moder = 0, then on entry this array specifies the diagonal entries of a diagonal matrix used as described under grade above.

If moder is not zero, then dr is set according to moder and condr, analogous to the way d is set according to mode and cond (except there is no dmax parameter for dr).

Not referenced if grade = 'N', 'L', 'H''S' or 'E'.

moder

INTEGER. This specifies how the diagonal array dr is to be computed, just as mode specifies how d is to be computed.

condr

REAL for slatmr and clatmr,

DOUBLE PRECISION for dlatmr and zlatmr,

When moder is not zero, this specifies the condition number of the computed dr.

pivtng

CHARACTER. On entry specifies pivoting permutations as follows:

If pivtng = 'N' or ' ': no pivoting permutation.

If pivtng = 'L': left or row pivoting (matrix must be nonsymmetric).

If pivtng = 'R': right or column pivoting (matrix must be nonsymmetric).

If pivtng = 'B' or 'F': both or full pivoting, i.e., on both sides. In this case, m must equal n.

If two calls to ?latmr both have full bandwidth (kl = m - 1 and ku = n-1), and differ only in the pivtng and pack parameters, then the matrices generated differs only in the order of the rows and columns, and otherwise contain the same data. This consistency cannot be maintained with less than full bandwidth.

ipivot

INTEGER. Array, size (n or m) This array specifies the permutation used. After the basic matrix is generated, the rows, columns, or both are permuted.

If row pivoting is selected, ?latmr starts with the last row and interchanges row m and row ipivot(m), then moves to the next-to-last row, interchanging rows (m-1) and row ipivot(m-1), and so on. In terms of "2-cycles", the permutation is (1 ipivot(1)) (2 ipivot(2)) ... (mipivot(m)) where the rightmost cycle is applied first. This is the inverse of the effect of pivoting in LINPACK. The idea is that factoring (with pivoting) an identity matrix which has been inverse-pivoted in this way should result in a pivot vector identical to ipivot. Not referenced if pivtng = 'N'.

sparse

REAL for slatmr,

DOUBLE PRECISION for dlatmr,

REAL for clatmr,

DOUBLE PRECISION for zlatmr,

On entry, specifies the sparsity of the matrix if a sparse matrix is to be generated. sparse should lie between 0 and 1. To generate a sparse matrix, for each matrix entry a uniform ( 0, 1 ) random number x is generated and compared to sparse; if x is larger the matrix entry is unchanged and if x is smaller the entry is set to zero. Thus on the average a fraction sparse of the entries is set to zero.

kl

INTEGER. On entry, specifies the lower bandwidth of the matrix. For example, kl = 0 implies upper triangular, kl = 1 implies upper Hessenberg, and kl at least m-1 implies the matrix is not banded. Must equal ku if matrix is symmetric or Hermitian.

ku

INTEGER. On entry, specifies the upper bandwidth of the matrix. For example, ku = 0 implies lower triangular, ku = 1 implies lower Hessenberg, and kuat least n-1 implies the matrix is not banded. Must equal kl if matrix is symmetric or Hermitian.

anorm

REAL for slatmr,

DOUBLE PRECISION for dlatmr,

REAL for clatmr,

DOUBLE PRECISION for zlatmr,

On entry, specifies maximum entry of output matrix (output matrix is multiplied by a constant so that its largest absolute entry equal anorm) if anorm is nonnegative. If anorm is negative no scaling is done.

pack

for slatmr,

for dlatmr,

for clatmr,

for zlatmr,

On entry, specifies packing of matrix as follows:

If pack = 'N': no packing

If pack = 'U': zero out all subdiagonal entries (if symmetric or Hermitian)

If pack = 'L': zero out all superdiagonal entries (if symmetric or Hermitian)

If pack = 'C': store the upper triangle columnwise (only if matrix symmetric or Hermitian or square upper triangular)

If pack = 'R': store the lower triangle columnwise (only if matrix symmetric or Hermitian or square lower triangular) (same as upper half rowwise if symmetric) (same as conjugate upper half rowwise if Hermitian)

If pack = 'B': store the lower triangle in band storage scheme (only if matrix symmetric or Hermitian)

If pack = 'Q': store the upper triangle in band storage scheme (only if matrix symmetric or Hermitian)

If pack = '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:

LAPACK storage scheme	Value of pack
GB	'Z'
PB, HB or TB	'B' or 'Q'
PP, HP or TP	'C' or 'R'

If two calls to ?latmr differ only in the pack parameter, they generate mathematically equivalent matrices.

lda

INTEGER. On entry, lda specifies the first dimension of a as declared in the calling program.

If pack = 'N', 'U' or 'L', lda must be at least max( 1, m ).

If pack = 'C' or 'R', lda must be at least 1.

If pack = 'B', or 'Q', lda must be min( ku + 1, n ).

If pack = 'Z', lda must be at least kuu + kll + 1, where kuu = min( ku, n-1 ) and kll = min( kl, n-1 ).

iwork

INTEGER. Array, size (n or m). Workspace. Not referenced if pivtng = 'N'. Changed on exit.

Output Parameters

iseed	On exit, the seed is changed.
d	May be changed on exit if mode is nonzero.
dl	On exit, array is changed.
dr	On exit, array is changed.
a	REAL for slatmr, DOUBLE PRECISION for dlatmr, COMPLEX for clatmr, DOUBLE COMPLEX for zlatmr, On exit, a is the desired test matrix. Only those entries of a which are significant on output is referenced (even if a is in packed or band storage format). The unoccupied corners of a in band format are zeroed out.
info	INTEGER. If `info = 0`, the execution is successful. If `info = -1`, m is negative or unequal to n and `sym = 'S' or 'H'`. If `info = -2`, n is negative . If `info = -3`, dist is an illegal string. If `info = -5`, sym is an illegal string.. If `info = -7`, mode is not in range -6 to 6. If `info = -8`, cond is less than 1.0, and mode is neither -6, 0 nor 6. If `info = -10`, mode is neither -6, 0 nor 6 and rsign is an illegal string. If `info = -11`, grade is an illegal string, or `grade = 'E'` and m is not equal to n, or `grade='L', 'R', 'B', 'S' or 'E'` and `sym = 'H', or grade = 'L', 'R', 'B', 'H' or 'E'` and `sym = 'S'` If `info = -12`,`grade = 'E'`and dl contains zero . If `info = -13`, model is not in range -6 to 6 and `grade = 'L', 'B', 'H', 'S' or 'E'` . If `info = -14`, condl is less than 1.0, `grade = 'L', 'B', 'H', 'S' or 'E'`, and model is neither -6, 0 nor 6. If `info = -16`, moder is not in range -6 to 6 and grade = 'R' or 'B' . If `info = -17`, condr is less than 1.0, `grade = 'R' or 'B'`, and moder is neither -6, 0 nor 6 . If `info = -18`, pivtng is an illegal string, or `pivtng = 'B' or 'F'` and m is not equal to n, or `pivtng = 'L' or 'R'` and `sym = 'S' or 'H'`. If `info = -19`, ipivot contains out of range number and pivtng is not equal to 'N' . If `info = -20`, kl is negative. If `info = -21`, ku is negative, or `sym = 'S' or 'H'` and ku not equal to kl . If `info = -22`, sparse is not in range 0 to 1. If `info = -24`, pack is an illegal string, or `pack = 'U', 'L', 'B' or 'Q'` and `sym = 'N'`, or `pack = 'C'` and `sym = 'N'` and either kl is not equal to 0 or n is not equal to m, or `pack = 'R'` and `sym = 'N'`, and either ku is not equal to 0 or n is not equal to m . If `info = -26`, lda is too small . If `info = 1`, error return from ?latm1 (computing `D` ) . If `info = 2`, cannot scale to dmax (max. entry is 0) . If `info = 3`, error return from ?latm1(computing dl) . If `info = 4`, error return from ?latm1(computing dr) . If `info = 5`, anorm is positive, but matrix constructed prior to attempting to scale it to have norm anorm, is zero .

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

?latmr

Syntax

Description

Input Parameters

Output Parameters