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
Array, size
lda
*
n
. On exit,
a
is the desired test matrix.
info
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
).

#### Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804