Developer Reference

  • 0.10
  • 10/21/2020
  • Public Content
Contents

?latme

Generates random non-symmetric square matrices with specified eigenvalues.

Syntax

void slatme
(
lapack_int
*n
,
char
*dist
,
lapack_int
*iseed
,
float
*d
,
lapack_int
*mode
,
float
*cond
,
float
*dmax
,
char
*ei
,
char
*rsign
,
char
*upper
,
char
*sim
,
float
*ds
,
lapack_int
*modes
,
float
*conds
,
lapack_int
*kl
,
lapack_int
*ku
,
float
*anorm
,
float
*a
,
lapack_int
*lda
,
float
*work
,
lapack_int
*info
);
void dlatme
(
lapack_int
*n
,
char
*dist
,
lapack_int
*iseed
,
double
*d
,
lapack_int
*mode
,
double
*cond
,
double
*dmax
,
char
*ei
,
char
*rsign
,
char
*upper
,
char
*sim
,
double
*ds
,
lapack_int
*modes
,
double
*conds
,
lapack_int
*kl
,
lapack_int
*ku
,
double
*anorm
,
double
*a
,
lapack_int
*lda
,
double
*work
,
lapack_int
*info
);
void clatme
(
lapack_int
*n
,
char
*dist
,
lapack_int
*iseed
,
lapack_complex_float
*d
,
lapack_int
*mode
,
float
*cond
,
lapack_complex_float
*dmax
,
char
*ei
,
char
*rsign
,
char
*upper
,
char
*sim
,
float
*ds
,
lapack_int
*modes
,
float
*conds
,
lapack_int
*kl
,
lapack_int
*ku
,
float
*anorm
,
lapack_complex_float
*a
,
lapack_int
*lda
,
lapack_complex_float
*work
,
lapack_int
*info
);
void zlatme
(
lapack_int
*n
,
char
*dist
,
lapack_int
*iseed
,
lapack_complex_double
*d
,
lapack_int
*mode
,
double
*cond
,
lapack_complex_double
*dmax
,
char
*ei
,
char
*rsign
,
char
*upper
,
char
*sim
,
double
*ds
,
lapack_int
*modes
,
double
*conds
,
lapack_int
*kl
,
lapack_int
*ku
,
double
*anorm
,
lapack_complex_double
*a
,
lapack_int
*lda
,
lapack_complex_double
*work
,
lapack_int
*info
);
Include Files
  • mkl.h
Description
The
?latme
routine generates random non-symmetric square matrices with specified eigenvalues.
?latme
operates by applying the following sequence of operations:
  1. Set the diagonal to
    d
    , where
    d
    may be input or computed according to
    mode
    ,
    cond
    ,
    dmax
    , and
    rsign
    as described below.
  2. If
    upper
    =
    'T
    '
    , the upper triangle of
    a
    is set to random values out of distribution
    dist
    .
  3. 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.
  4. 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
    .
  5. If
    anorm
    is not negative, the matrix is scaled to have maximum-element-norm
    anorm
    .
Since the matrix cannot be reduced beyond Hessenberg form, no packing options are available.
Input Parameters
n
The number of columns (or rows) of
A
.
dist
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
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
[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.
d
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
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
[0]
= 1
and
d
(2:
n
]
=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, this is used as described under
mode
above. If used, it must be
1.
dmax
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
- 1]
))
. 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
Used by
slatme
and
dlatme
only.
Array, size (
n
).
If
mode
= 0
, and
ei
[0]
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
- 1]
=
'R'
and
ei
[
j
]
=
'I'
, then the
j
-th eigenvalue is cmplx(
d
[
j
- 1]
,
d
[
j
]
), and the (
j
+1)-th is the complex conjugate thereof.
If
ei
[
j
- 1]
=
ei
[
j
]
=
'R'
, then the
j
-th eigenvalue is
d
[
j
- 1]
(i.e., real).
ei
[0]
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
[0]
=
' '
, then the eigenvalues will all be real.
rsign
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
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
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
=
U
S
V
, 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
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
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
Similar to
cond
, but for specifying the diagonal of
S
.
kl
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
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
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
Number of rows of matrix
A
.
work
Array, size
(3*
n
).
Workspace.
Output Parameters
iseed
On exit, the seed is updated.
d
Modified if
mode
is nonzero.
ds
Modified if
mode
is nonzero.
a