Developer Reference

Contents

?latms

Generates a general
m
-by-
n
matrix with specific singular values.

Syntax

lapack_int
LAPACKE_slatms
(
int
matrix_layout
,
lapack_int
m
,
lapack_int
n
,
char
dist
,
lapack_int
*
iseed
,
char
sym
,
float
*
d
,
lapack_int
mode
,
float
cond
,
float
dmax
,
lapack_int
kl
,
lapack_int
ku
,
char
pack
,
float
*
a
,
lapack_int
lda
);
lapack_int
LAPACKE_dlatms
(
int
matrix_layout
,
lapack_int
m
,
lapack_int
n
,
char
dist
,
lapack_int
*
iseed
,
char
sym
,
double
*
d
,
lapack_int
mode
,
double
cond
,
double
dmax
,
lapack_int
kl
,
lapack_int
ku
,
char
pack
,
double
*
a
,
lapack_int
lda
);
lapack_int
LAPACKE_clatms
(
int
matrix_layout
,
lapack_int
m
,
lapack_int
n
,
char
dist
,
lapack_int
*
iseed
,
char
sym
,
float
*
d
,
lapack_int
mode
,
float
cond
,
float
dmax
,
lapack_int
kl
,
lapack_int
ku
,
char
pack
,
lapack_complex_float
*
a
,
lapack_int
lda
);
lapack_int
LAPACKE_zlatms
(
int
matrix_layout
,
lapack_int
m
,
lapack_int
n
,
char
dist
,
lapack_int
*
iseed
,
char
sym
,
double
*
d
,
lapack_int
mode
,
double
cond
,
double
dmax
,
lapack_int
kl
,
lapack_int
ku
,
char
pack
,
lapack_complex_double
*
a
,
lapack_int
lda
);
Include Files
  • mkl.h
Description
The
?latms
routine generates random matrices with specified singular values, or symmetric/Hermitian matrices with specified eigenvalues for testing LAPACK programs.
It applies this sequence of operations:
  1. Set the diagonal to
    d
    , where
    d
    is input or computed according to
    mode
    ,
    cond
    ,
    dmax
    , and
    sym
    as described in Input Parameters.
  2. Generate a matrix with the appropriate band structure, by one of two methods:
    Method A
    1. Generate a dense
      m
      -by-
      n
      matrix by multiplying
      d
      on the left and the right by random unitary matrices, then:
    2. Reduce the bandwidth according to
      kl
      and
      ku
      , using Householder transformations.
    Method B:
    Convert the bandwidth-0 (i.e., diagonal) matrix to a bandwidth-1 matrix using Givens rotations, "chasing" out-of-band elements back, much as in QR; then convert the bandwidth-1 to a bandwidth-2 matrix, etc.
    Note that for reasonably small bandwidths (relative to
    m
    and
    n
    ) this requires less storage, as a dense matrix is not generated. Also, for symmetric or Hermitian matrices, only one triangle is generated.
Method A is chosen if the bandwidth is a large fraction of the order of the matrix, and
lda
is at least
m
(so a dense matrix can be stored.) Method B is chosen if the bandwidth is small (less than (1/2)*
n
for symmetric or Hermitian or less than .3*
n
+
m
for nonsymmetric), or
lda
is less than
m
and not less than the bandwidth.
Pack the matrix if desired, using one of the methods specified by the
pack
parameter.
If Method B is chosen and band format is specified, then the matrix is generated in the band format and no repacking is necessary.
Input Parameters
A
<datatype>
placeholder, if present, is used for the C interface data types in the C interface section above. See C Interface Conventions for the C interface principal conventions and type definitions.
matrix_layout
Specifies whether matrix storage layout is row major (
LAPACK_ROW_MAJOR
) or column major (
LAPACK_COL_MAJOR
).
m
The number of rows of the matrix
A
(
m
0
).
n
The number of columns of the matrix
A
(
n
0
).
dist
Specifies the type of distribution to be used to generate the random singular values or eigenvalues:
  • 'U': uniform distribution (0, 1)
  • 'S': symmetric uniform distribution (-1, 1)
  • 'N': normal distribution (0, 1)
iseed
Array with size 4.
Specifies the seed of the random number generator. Values 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. The values of the array are modified, and can be used in the next call to
?latms
to continue the same random number sequence.
sym
If
sym
='S' or 'H', the generated matrix is symmetric or Hermitian, with eigenvalues specified by
d
,
cond
,
mode
, and
dmax
; they can be positive, negative, or zero.
If
sym
='P', the generated matrix is symmetric or Hermitian, with eigenvalues (which are singular, non-negative values) specified by
d
,
cond
,
mode
, and
dmax
.
If
sym
='N', the generated matrix is nonsymmetric, with singular, non-negative values specified by
d
,
cond
,
mode
, and
dmax
.
d
Array, size (MIN(
m
,
n
))
This array is used to specify the singular values or eigenvalues of
A
(see the description of
sym
). If
mode
=0, then
d
is assumed to contain the eigenvalues or singular values, otherwise elements of
d
are computed according to
mode
,
cond
, and
dmax
.
mode
Describes how the singular/eigenvalues are specified.
  • mode
    = 0: use
    d
    as input
  • mode
    = 1: set
    d
    [0] = 1
    and
    d
    [1:
    n
    - 1] = 1.0/
    cond
  • mode
    = 2: set
    d
    [0:
    n
    - 2] = 1
    and
    d
    [
    n
    - 1] = 1.0/
    cond
  • mode
    = 3: set
    d
    [
    i
    ] =
    cond
    -
    i
    /(
    n
    - 1)
  • mode
    = 4: set
    d
    [
    i
    ] = 1 -
    i
    /(
    n
    - 1)*(1 - 1/
    cond
    )
  • mode
    = 5: set elements of
    d
    to random numbers in the range (1/
    cond
    , 1) such that their logarithms are uniformly distributed.
  • mode
    = 6: set elements of
    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 positive,
d
has entries ranging from 1 to 1/
cond
, if negative, from 1/
cond
to 1.
If
sym
='S' or 'H', and
mode
is not 0, 6, nor -6, then the elements of
d
are also given a random sign (multiplied by +1 or -1).
cond
Used in setting
d
as described for the
mode
parameter. If used,
cond
1.
dmax
If
mode
is not -6, 0 nor 6, the contents of
d
, as computed according to
mode
and
cond
, are scaled by
dmax
/ max(abs(
d
[
i
-1]))
; thus, the maximum absolute eigenvalue or singular value (the norm) is
abs(
dmax
)
.
dmax
need not be positive: if
dmax
is negative (or zero),
d
will be scaled by a negative number (or zero).
kl
Specifies the lower bandwidth of the matrix. For example,
kl
=0 implies upper triangular,
kl
=1 implies upper Hessenberg, and
kl
being at least
m
- 1 means that the matrix has full lower bandwidth.
kl
must equal
ku
if the matrix is symmetric or Hermitian.
ku
Specifies the upper bandwidth of the matrix. For example,
ku
=0 implies lower triangular,
ku
=1 implies lower Hessenberg, and
ku
being at least
n
- 1 means that the matrix has full upper bandwidth.
kl
must equal
ku
if the matrix is symmetric or Hermitian.
pack
Specifies packing of matrix:
  • 'N': no packing
  • 'U': zero out all subdiagonal entries (if symmetric or Hermitian)
  • 'L': zero out all superdiagonal entries (if symmetric or Hermitian)
  • 'B': store the lower triangle in band storage scheme (only if matrix symmetric, Hermitian, or lower triangular)
  • 'Q': store the upper triangle in band storage scheme (only if matrix symmetric, Hermitian, or upper triangular)
  • '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:
'Z'
'B'
'Q'
'C'
'R'
GB: general band
x
PB: symmetric positive definite band
x
x
SB: symmetric band
x
x
HB: Hermitian band
x
x
TB: triangular band
x
x
PP: symmetric positive definite packed
x
x
SP: symmetric packed
x
x
HP: Hermitian packed
x
x
TP: triangular packed
x
x
If two calls to
?latms
differ only in the
pack
parameter, they generate mathematically equivalent matrices.
lda
lda
specifies the first dimension of
a
as declared in the calling program.
If
pack
='N', 'U', 'L', 'C', or 'R', then
lda
must be at least
m
for column major or at least
n
for row major
.
If
pack
='B' or 'Q', then
lda
must be at least
MIN(
kl
,
m
- 1)
(which is equal to MIN(
ku
,
n
- 1)).
If
pack
='Z',
lda
must be large enough to hold the packed array:
MIN(
ku
,
n
- 1) + MIN(
kl
,
m
- 1) + 1
.
Output Parameters
iseed
The array
iseed
contains the updated seed.
d
The array
d
contains the updated seed.
The array
d
is not modified if
mode
= 0.
a
Array of size
lda
by
n
.
The array
a
contains the generated
m
-by-
n
matrix
A
.
a
is first generated in full (unpacked) form, and then packed, if so specified by
pack
. Thus, the first
m
elements of the first
n
columns are always modified. If
pack
specifies a packed or banded storage scheme, all
lda
elements of the first
n
columns are modified; the elements of the array which do not correspond to elements of the generated matrix are set to zero.
Return Values
This function returns a value
info
.
If
info
= 0
, the execution is successful.
If
info
< 0
, the
i
-th parameter had an illegal value.
If
info
= -1011
, memory allocation error occurred.
If
info
= 2
, cannot scale to
dmax
(maximum singular value is 0).
If
info
= 3
, error return from lagge, ?laghe, or lagsy.

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