Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

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

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.