Developer Reference for Intel® oneAPI Math Kernel Library for C
?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 ( intmatrix_layout , charjob , charhowmny , const lapack_logical*select , lapack_intn , const float*a , lapack_intlda , const float*b , lapack_intldb , const float*vl , lapack_intldvl , const float*vr , lapack_intldvr , float*s , float*dif , lapack_intmm , lapack_int*m );
lapack_int LAPACKE_dtgsna ( intmatrix_layout , charjob , charhowmny , const lapack_logical*select , lapack_intn , const double*a , lapack_intlda , const double*b , lapack_intldb , const double*vl , lapack_intldvl , const double*vr , lapack_intldvr , double*s , double*dif , lapack_intmm , lapack_int*m );
lapack_int LAPACKE_ctgsna ( intmatrix_layout , charjob , charhowmny , const lapack_logical*select , lapack_intn , const lapack_complex_float*a , lapack_intlda , const lapack_complex_float*b , lapack_intldb , const lapack_complex_float*vl , lapack_intldvl , const lapack_complex_float*vr , lapack_intldvr , float*s , float*dif , lapack_intmm , lapack_int*m );
lapack_int LAPACKE_ztgsna ( intmatrix_layout , charjob , charhowmny , const lapack_logical*select , lapack_intn , const lapack_complex_double*a , lapack_intlda , const lapack_complex_double*b , lapack_intldb , const lapack_complex_double*vl , lapack_intldvl , const lapack_complex_double*vr , lapack_intldvr , double*s , double*dif , lapack_intmm , lapack_int*m );
Include Files
mkl.h
Description
stgsna dtgsna ctgsna ztgsna tgsna
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:code:`T` , Q*B*Z:code:`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 , work
-
REAL for stgsna DOUBLE PRECISION for dtgsna COMPLEX for ctgsna DOUBLE COMPLEX for ztgsna . 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 ).
The second dimension of a must be at least max(1, n ).
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.
work is a workspace array, its dimension max(1, lwork) . If job = 'E' , work 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 ).
lwork
The dimension of the array work .
lwork≥ max(1, n) . If job = 'V' or ‘B’ , lwork≥ 2*n*(n+2)+16 for real flavors, and lwork≥ max(1, 2*n*n) for complex flavors. If lwork = -1 , then a workspace query is assumed; the routine only calculates the optimal size of the work array, returns this value as the first entry of the work array, and no error message related to lwork is issued by xerbla . See Application Notes for details.
iwork
Workspace array, size at least ( n +6) for real flavors, and at least ( n +2) for complex flavors.
If job = 'E' , iwork is not referenced.
Output Parameters
- s
-
REAL for single-precision flavors DOUBLE PRECISION for double-precision flavors.
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
-
REAL for single-precision flavors DOUBLE PRECISION for double-precision flavors.
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 .
- work(1)
-
work(1) If job is not ‘E’ and info = 0 , on exit, work(1) contains the minimum value of lwork required for optimum performance. Use this lwork for subsequent runs.
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.
LAPACK 95 Interface Notes
There exist FORTRAN 77 and FORTRAN 95 interfaces for this routine. See the Intel® oneMKL Fortran Developer Reference for details.
Application Notes
If it is not clear how much workspace to supply, use a generous value of lwork for the first run, or set lwork = -1 .
In first case the routine completes the task, though probably not so fast as with a recommended workspace, and provides the recommended workspace in the first element of the corresponding array work on exit. Use this value ( work(1) ) for subsequent runs.
If lwork = -1 , then the routine returns immediately and provides the recommended workspace in the first element of the corresponding array ( work ). This operation is called a workspace query.
Note that if lwork is less than the minimal required value and is not equal to -1, then the routine returns immediately with an error exit and does not provide any information on the recommended workspace.