Developer Reference

  • 0.9
  • 09/09/2020
  • Public Content
Contents

?latm2

Returns an entry of a random matrix.

Syntax

float slatm2
(
lapack_int
*m
,
lapack_int
*n
,
lapack_int
*i
,
lapack_int
*j
,
lapack_int
*kl
,
lapack_int
*ku
,
lapack_int
*idist
,
lapack_int
*iseed
,
float
*d
,
lapack_int
*igrade
,
float
*dl
,
float
*dr
,
lapack_int
*ipvtng
,
lapack_int
*iwork
,
float
*sparse
);
double dlatm2
(
lapack_int
*m
,
lapack_int
*n
,
lapack_int
*i
,
lapack_int
*j
,
lapack_int
*kl
,
lapack_int
*ku
,
lapack_int
*idist
,
lapack_int
*iseed
,
double
*d
,
lapack_int
*igrade
,
double
*dl
,
double
*dr
,
lapack_int
*ipvtng
,
lapack_int
*iwork
,
double
*sparse
);
The data types for complex variations depend on whether or not the application links with Gnu Fortran (gfortran) libraries.
For non-gfortran (
libmkl_intel_*
) interface libraries:
void clatm2
(
lapack_complex_float
*res
,
lapack_int
*m
,
lapack_int
*n
,
lapack_int
*i
,
lapack_int
*j
,
lapack_int
*kl
,
lapack_int
*ku
,
lapack_int
*idist
,
lapack_int
*iseed
,
lapack_complex_float
*d
,
lapack_int
*igrade
,
lapack_complex_float
*dl
,
lapack_complex_float
*dr
,
lapack_int
*ipvtng
,
lapack_int
*iwork
,
float
*sparse
);
void zlatm2
(
lapack_complex_double
*res
,
lapack_int
*m
,
lapack_int
*n
,
lapack_int
*i
,
lapack_int
*j
,
lapack_int
*kl
,
lapack_int
*ku
,
lapack_int
*idist
,
lapack_int
*iseed
,
lapack_complex_double
*d
,
lapack_int
*igrade
,
lapack_complex_double
*dl
,
lapack_complex_double
*dr
,
lapack_int
*ipvtng
,
lapack_int
*iwork
,
double
*sparse
);
For gfortran (
libmkl_gf_*
) interface libraries:
lapack_complex_float clatm2
(
lapack_int
*m
,
lapack_int
*n
,
lapack_int
*i
,
lapack_int
*j
,
lapack_int
*kl
,
lapack_int
*ku
,
lapack_int
*idist
,
lapack_int
*iseed
,
lapack_complex_float
*d
,
lapack_int
*igrade
,
lapack_complex_float
*dl
,
lapack_complex_float
*dr
,
lapack_int
*ipvtng
,
lapack_int
*iwork
,
float
*sparse
);
lapack_complex_double zlatm2
(
lapack_int
*m
,
lapack_int
*n
,
lapack_int
*i
,
lapack_int
*j
,
lapack_int
*kl
,
lapack_int
*ku
,
lapack_int
*idist
,
lapack_int
*iseed
,
lapack_complex_double
*d
,
lapack_int
*igrade
,
lapack_complex_double
*dl
,
lapack_complex_double
*dr
,
lapack_int
*ipvtng
,
lapack_int
*iwork
,
double
*sparse
);
To understand the difference between the non-gfortran and gfortran interfaces and when to use each of them, see Dynamic Libraries in the lib/intel64 Directory in the
oneAPI Math Kernel Library Developer Guide
.
Include Files
  • mkl.h
Description
The
?latm2
routine returns entry (
i
,
j
) of a random matrix of dimension (
m
,
n
). It is called by the
?latmr
routine in order to build random test matrices. No error checking on parameters is done, because this routine is called in a tight loop by
?latmr
which has already checked the parameters.
Use of
?latm2
differs from
?latm3
in the order in which the random number generator is called to fill in random matrix entries. With
?latm2
, the generator is called to fill in the pivoted matrix columnwise. With
?latm2
, the generator is called to fill in the matrix columnwise, after which it is pivoted. Thus,
?latm3
can be used to construct random matrices which differ only in their order of rows and/or columns.
?latm2
is used to construct band matrices while avoiding calling the random number generator for entries outside the band (and therefore generating random numbers).
The matrix whose (
i
,
j
) entry is returned is constructed as follows (this routine only computes one entry):
  • If
    i
    is outside
    (1..
    m
    )
    or
    j
    is outside
    (1..n)
    , returns zero (this is convenient for generating matrices in band format).
  • Generate a matrix
    A
    with random entries of distribution
    idist
    .
  • Set the diagonal to
    D
    .
  • Grade the matrix, if desired, from the left (by
    dl
    ) and/or from the right (by
    dr
    or
    dl
    ) as specified by
    igrade
    .
  • Permute, if desired, the rows and/or columns as specified by
    ipvtng
    and
    iwork
    .
  • Band the matrix to have lower bandwidth
    kl
    and upper bandwidth
    ku
    .
  • Set random entries to zero as specified by
    sparse
    .
Input Parameters
m
Number of rows of the matrix.
n
Number of columns of the matrix.
i
Row of the entry to be returned.
j
Column of the entry to be returned.
kl
Lower bandwidth.
ku
Upper bandwidth.
idist
On entry,
idist
specifies the type of distribution to be used to generate a random matrix .
for
slatm2
and
dlatm2
:
= 1: uniform (0,1)
= 2: uniform (-1,1)
= 3: normal (0,1)
for
clatm2
and
zlatm2
:
= 1: real and imaginary parts each uniform (0,1)
= 2: real and imaginary parts each uniform (-1,1)
= 3: real and imaginary parts each normal (0,1)
= 4: complex number uniform in disk (0, 1)
iseed
Array, size 4.
Seed for the random number generator.
d
Array, size
(min(
i
,
j
)).
Diagonal entries of matrix.
igrade
Specifies grading of matrix as follows:
= 0: no grading
= 1: matrix premultiplied by diag(
dl
)
= 2: matrix postmultiplied by diag(
dr
)
= 3: matrix premultiplied by diag(
dl
) and postmultiplied by diag(
dr
)
= 4: matrix premultiplied by diag(
dl
) and postmultiplied by inv( diag(
dl
) )
For
slatm2
and
slatm2
:
= 5: matrix premultiplied by diag(
dl
) and postmultiplied by diag(
dl
)
For
clatm2
and
zlatm2
:
= 5: matrix premultiplied by diag(
dl
) and postmultiplied by diag( conjg(
dl
) )
= 6: matrix premultiplied by diag(
dl
) and postmultiplied by diag(
dl
)
dl
Array, size (
i
or
j
), as appropriate.
Left scale factors for grading matrix.
dr
Array, size (
i
or
j
), as appropriate.
Right scale factors for grading matrix.
ipvtng
On entry specifies pivoting permutations as follows:
= 0: none
= 1: row pivoting
= 2: column pivoting
= 3: full pivoting, i.e., on both sides
iwork
Array, size (
i
or
j
), as appropriate. This array specifies the permutation used. The row (or column) in position
k
was originally in position
iwork
[
k
- 1]
. This differs from
iwork
for
?latm3
.
sparse
Specifies the sparsity of the matrix. If sparse matrix is to be generated,
sparse
should lie between 0 and 1. 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 will be set to zero.
Output Parameters
iseed
On exit, the seed is updated.
Return Values
The function returns an entry of a random matrix
(for complex variations
libmkl_gf_*
interface layer/libraries return the result as the parameter
res
)
.

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