Contents

?latmr

Generates random matrices of various types.

Syntax

void slatmr
(
lapack_int
*m
,
lapack_int
*n
,
char
*dist
,
lapack_int
*iseed
,
char
*sym
,
float
*d
,
lapack_int
*mode
,
float
*cond
,
float
*dmax
,
char
*rsign
,
char
*grade
,
float
*dl
,
lapack_int
*model
,
float
*condl
,
float
*dr
,
lapack_int
*moder
,
float
*condr
,
char
*pivtng
,
lapack_int
*ipivot
,
lapack_int
*kl
,
lapack_int
*ku
,
float
*sparse
,
float
*anorm
,
char
*pack
,
float
*a
,
lapack_int
*lda
,
lapack_int
*iwork
,
lapack_int
*info
);
void dlatmr
(
lapack_int
*m
,
lapack_int
*n
,
char
*dist
,
lapack_int
*iseed
,
char
*sym
,
double
*d
,
lapack_int
*mode
,
double
*cond
,
double
*dmax
,
char
*rsign
,
char
*grade
,
double
*dl
,
lapack_int
*model
,
double
*condl
,
double
*dr
,
lapack_int
*moder
,
double
*condr
,
char
*pivtng
,
lapack_int
*ipivot
,
lapack_int
*kl
,
lapack_int
*ku
,
double
*sparse
,
double
*anorm
,
char
*pack
,
double
*a
,
lapack_int
*lda
,
lapack_int
*iwork
,
lapack_int
*info
);
void clatmr
(
lapack_int
*m
,
lapack_int
*n
,
char
*dist
,
lapack_int
*iseed
,
char
*sym
,
lapack_complex
*d
,
lapack_int
*mode
,
float
*cond
,
lapack_complex
*dmax
,
char
*rsign
,
char
*grade
,
lapack_complex
*dl
,
lapack_int
*model
,
float
*condl
,
lapack_complex
*dr
,
lapack_int
*moder
,
float
*condr
,
char
*pivtng
,
lapack_int
*ipivot
,
lapack_int
*kl
,
lapack_int
*ku
,
float
*sparse
,
float
*anorm
,
char
*pack
,
float
*a
,
lapack_int
*lda
,
lapack_int
*iwork
,
lapack_int
*info
);
void zlatmr
(
lapack_int
*m
,
lapack_int
*n
,
char
*dist
,
lapack_int
*iseed
,
char
*sym
,
lapack_complex_double
*d
,
lapack_int
*mode
,
float
*cond
,
lapack_complex_double
*dmax
,
char
*rsign
,
char
*grade
,
lapack_complex_double
*dl
,
lapack_int
*model
,
float
*condl
,
lapack_complex_double
*dr
,
lapack_int
*moder
,
float
*condr
,
char
*pivtng
,
lapack_int
*ipivot
,
lapack_int
*kl
,
lapack_int
*ku
,
float
*sparse
,
float
*anorm
,
char
*pack
,
float
*a
,
lapack_int
*lda
,
lapack_int
*iwork
,
lapack_int
*info
);
Description
The
?latmr
routine operates by applying the following sequence of operations:
  1. 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.
  2. Set the diagonal to
    D
    , where
    D
    may be input or computed according to
    mode
    ,
    cond
    ,
    dmax
    and
    rsign
    as described below.
  3. 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.
  4. Permute, if desired, the rows and/or columns as specified by
    pivtng
    and
    ipivot
    .
  5. Set random entries to zero, if desired, to get a random sparse matrix as specified by
    sparse
    .
  6. Make
    A
    a band matrix, if desired, by zeroing out the matrix outside a band of lower bandwidth
    kl
    and upper bandwidth
    ku
    .
  7. Scale
    A
    , if desired, to have maximum entry
    anorm
    .
  8. Pack the matrix if desired. See options specified by the
    pack
    parameter.
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
Number of rows of
A
.
n
Number of columns of
A
.
dist
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
Array, size 4.
On entry,
iseed
specifies the seed of the random number generator. They 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.
sym
If
sym
=
'S'
, generated matrix is symmetric.
If
sym
=
'H'
, generated matrix is Hermitian.
If
sym
=
'N'
, generated matrix is nonsymmetric.
d
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
On entry describes how
d
is to be used:
mode
= 0
means use
d
as input.
mode
= 1
sets
d
[0]
=1
and
d
[1:
n
- 1]
=1.0/
cond
.
mode
= 2
sets
d
[0:
n
- 2]
=1 and
d
[
n
- 1]
=1.0/
cond
.
mode
= 3
sets
d
[
i
- 1]
=
cond
**(-(
i
-1)/(
n
-1))
.
mode
= 4
sets
d
[
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
On entry, used as described under
mode
above. If used,
cond
must be
1.
dmax
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
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
r
sign
=
'F'
, diagonal entries are unchanged.
grade
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)
if
grade
=
'E'
, then
m
must equal
n
.
dl
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
This specifies how the diagonal array
dl
is computed, just as
mode
specifies how
D
is computed.
condl
When
model
is not zero, this specifies the condition number of the computed
dl
.
dr
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
This specifies how the diagonal array
dr
is to be computed, just as mode specifies how
d
is to be computed.
condr
When
moder
is not zero, this specifies the condition number of the computed
dr
.
pivtng
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
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
- 1]
, then moves to the next-to-last row, interchanging rows
[
m
- 2]
and row
ipivot
[
m
- 2]
, and so on. In terms of "2-cycles", the permutation is
(1
ipivot
[0]) (2
ipivot
[1]) ... (
m
ipivot
[
m
- 1])
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
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
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
On entry, specifies the upper bandwidth of the matrix. For example,
ku
= 0
implies lower triangular,
ku
= 1
implies lower Hessenberg, and
ku
at least
n
-1 implies the matrix is not banded. Must equal
kl
if matrix is symmetric or Hermitian.
anorm
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
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
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
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
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
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