## Developer Reference

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

# ?latme

Generates random non-symmetric square matrices with specified eigenvalues.

## Syntax

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

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

= 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

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

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

=
' '
, 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