Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

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

?tgsna

Estimates reciprocal condition numbers for specified eigenvalues and/or eigenvectors of a pair of matrices in generalized real Schur canonical form.

Syntax

lapack_int LAPACKE_stgsna
(
int
matrix_layout
,
char
job
,
char
howmny
,
const lapack_logical*
select
,
lapack_int
n
,
const float*
a
,
lapack_int
lda
,
const float*
b
,
lapack_int
ldb
,
const float*
vl
,
lapack_int
ldvl
,
const float*
vr
,
lapack_int
ldvr
,
float*
s
,
float*
dif
,
lapack_int
mm
,
lapack_int*
m
);
lapack_int LAPACKE_dtgsna
(
int
matrix_layout
,
char
job
,
char
howmny
,
const lapack_logical*
select
,
lapack_int
n
,
const double*
a
,
lapack_int
lda
,
const double*
b
,
lapack_int
ldb
,
const double*
vl
,
lapack_int
ldvl
,
const double*
vr
,
lapack_int
ldvr
,
double*
s
,
double*
dif
,
lapack_int
mm
,
lapack_int*
m
);
lapack_int LAPACKE_ctgsna
(
int
matrix_layout
,
char
job
,
char
howmny
,
const lapack_logical*
select
,
lapack_int
n
,
const lapack_complex_float*
a
,
lapack_int
lda
,
const lapack_complex_float*
b
,
lapack_int
ldb
,
const lapack_complex_float*
vl
,
lapack_int
ldvl
,
const lapack_complex_float*
vr
,
lapack_int
ldvr
,
float*
s
,
float*
dif
,
lapack_int
mm
,
lapack_int*
m
);
lapack_int LAPACKE_ztgsna
(
int
matrix_layout
,
char
job
,
char
howmny
,
const lapack_logical*
select
,
lapack_int
n
,
const lapack_complex_double*
a
,
lapack_int
lda
,
const lapack_complex_double*
b
,
lapack_int
ldb
,
const lapack_complex_double*
vl
,
lapack_int
ldvl
,
const lapack_complex_double*
vr
,
lapack_int
ldvr
,
double*
s
,
double*
dif
,
lapack_int
mm
,
lapack_int*
m
);
Include Files
  • mkl.h
Description
The real flavors
stgsna
/
dtgsna
 of this routine estimate reciprocal condition numbers for specified eigenvalues and/or eigenvectors of a matrix pair (
A
,
B
) in generalized real Schur canonical form (or of any matrix pair (
Q
*A*
Z
T
,
Q*
B*
Z
T
) with orthogonal matrices
Q
 and
Z
.
(
A
,
B
) must be in generalized real Schur form (as returned by gges/gges), that is,
A
 is block upper triangular with 1-by-1 and 2-by-2 diagonal blocks. B is upper triangular.
The complex flavors
ctgsna
/
ztgsna
 estimate reciprocal condition numbers for specified eigenvalues and/or eigenvectors of a matrix pair (
A
,
B
). (
A
,
B
) must be in generalized Schur canonical form, that is,
A
 and
B
 are both upper triangular.
Input Parameters
matrix_layout
Specifies whether matrix storage layout is row major (
LAPACK_ROW_MAJOR
) or column major (
LAPACK_COL_MAJOR
).
job
Specifies whether condition numbers are required for eigenvalues or eigenvectors. Must be
'E'
 or
'V'
 or
'B'
.
If
job
 =
'E'
, for eigenvalues only (compute
s
 ).
If
job
 =
'V'
, for eigenvectors only (compute
dif
 ).
If
job
 =
'B'
, for both eigenvalues and eigenvectors (compute both
s
 and
dif
).
howmny
Must be
'A'
 or
'S'
.
If
howmny
 =
'A'
, compute condition numbers for all eigenpairs.
If
howmny
 =
'S'
, compute condition numbers for selected eigenpairs specified by the logical array
select
.
select
Array, size at least max (1,
n
).
If
howmny
 =
'S'
,
select
 specifies the eigenpairs for which condition numbers are required.
If
howmny
 =
'A'
,
select
 is not referenced.
For real flavors
:
To select condition numbers for the eigenpair corresponding to a real eigenvalue
ω
j
,
select
[
j
 - 1]
 must be set to
1
; to select condition numbers corresponding to a complex conjugate pair of eigenvalues
ω
j
 and
ω
j
 + 1
, either
select
[
j
 - 1]
 or
select
[
j
]
 must be set to
1.
For complex flavors:
To select condition numbers for the corresponding
j
-th eigenvalue and/or eigenvector,
select
[
j
 - 1]
 must be set to
1
.
n
The order of the square matrix pair (
A
,
B
)
(
n
≥
 0).
a
,
b
,
vl
,
vr
Arrays:
a
(size max(1,
lda
*
n
))
 contains the upper quasi-triangular (for real flavors) or upper triangular (for complex flavors) matrix
A
 in the pair (
A
,
B
).
b
(size max(1,
ldb
*
n
))
 contains the upper triangular matrix
B
 in the pair (
A
,
B
).
If
job
 =
'E'
 or
'B'
,
vl
(size max(1,
ldvl
*
m
) for column major layout and max(1,
ldvl
*
n
) for row major layout)
 must contain left eigenvectors of (
A
,
B
), corresponding to the eigenpairs specified by
howmny
 and
select
. The eigenvectors must be stored in consecutive columns of
vl
, as returned by
?tgevc
.
If
job
 =
'V'
,
vl
 is not referenced.
If
job
 =
'E'
 or
'B'
,
vr
(size max(1,
ldvr
*
m
) for column major layout and max(1,
ldvr
*
n
) for row major layout)
 must contain right eigenvectors of (
A
,
B
), corresponding to the eigenpairs specified by
howmny
 and
select
. The eigenvectors must be stored in consecutive columns of
vr
, as returned by
?tgevc
.
If
job
 =
'V'
,
vr
 is not referenced.
lda
The leading dimension of
a
; at least max(1,
n
).
ldb
The leading dimension of
b
; at least max(1,
n
).
ldvl
The leading dimension of
vl
;
ldvl
≥
 1
.
If
job
 =
'E'
 or
'B'
, then
ldvl
≥
 max(1,
n
)
for column major layout and
ldvl
≥
 max(1,
m
) for row major layout
 .
ldvr
The leading dimension of
vr
;
ldvr
≥
 1
.
If
job
 =
'E'
 or
'B'
, then
ldvr
≥
 max(1,
n
)
for column major layout and
ldvr
≥
 max(1,
m
) for row major layout
.
mm
The number of elements in the arrays
s
 and
dif
 (
mm
≥
m
).
Output Parameters
s
Array,
size
mm
.
If
job
 =
'E'
 or
'B'
, contains the reciprocal condition numbers of the selected eigenvalues, stored in consecutive elements of the array.
If
job
 =
'V'
,
s
 is not referenced.
For real flavors
:
For a complex conjugate pair of eigenvalues two consecutive elements of
s
 are set to the same value. Thus,
s
[
j
 - 1]
,
dif
[
j
 - 1]
, and the
j
-th columns of
vl
 and
vr
 all correspond to the same eigenpair (but not in general the
j
-th eigenpair, unless all eigenpairs are selected).
dif
Array,
size
mm
.
If
job
 =
'V'
 or
'B'
, contains the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array.
If the eigenvalues cannot be reordered to compute
dif
[
j
]
,
dif
[
j
]
 is set to 0; this can only occur when the true value would be very small anyway.
If
job
 =
'E'
,
dif
 is not referenced.
For real flavors
:
For a complex eigenvector, two consecutive elements of
dif
 are set to the same value.
For complex flavors
:
For each eigenvalue/vector specified by
select
,
dif
 stores a Frobenius norm-based estimate of Difl.
m
The number of elements in the arrays
s
 and
dif
 used to store the specified condition numbers; for each selected eigenvalue one element is used.
If
howmny
 =
'A'
,
m
 is set to
n
.
Return Values
This function returns a value
info
.
If
info
=0
, the execution is successful.
If
info
 =
-i
, the
i
-th parameter had an illegal value.

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