Developer Reference for Intel® oneAPI Math Kernel Library for C
?trexc
Reorders the Schur factorization of a general matrix.
Syntax
lapack_int LAPACKE_strexc ( intmatrix_layout , charcompq , lapack_intn , float*t , lapack_intldt , float*q , lapack_intldq , lapack_int*ifst , lapack_int*ilst );
lapack_int LAPACKE_dtrexc ( intmatrix_layout , charcompq , lapack_intn , double*t , lapack_intldt , double*q , lapack_intldq , lapack_int*ifst , lapack_int*ilst );
lapack_int LAPACKE_ctrexc ( intmatrix_layout , charcompq , lapack_intn , lapack_complex_float*t , lapack_intldt , lapack_complex_float*q , lapack_intldq , lapack_intifst , lapack_intilst );
lapack_int LAPACKE_ztrexc ( intmatrix_layout , charcompq , lapack_intn , lapack_complex_double*t , lapack_intldt , lapack_complex_double*q , lapack_intldq , lapack_intifst , lapack_intilst );
Include Files
mkl.h
Description
The routine reorders the Schur factorization of a general matrix A = Q*T*Q^{H} , so that the diagonal element or block of T with row index ifst is moved to row ilst .
The reordered Schur form S is computed by an unitary (or, for real flavors, orthogonal) similarity transformation: S = Z^{H}*T*Z . Optionally the updated matrix P of Schur vectors is computed as P = Q*Z , giving A = P*S*P^{H} .
Input Parameters
- matrix_layout
-
Specifies whether matrix storage layout is row major ( LAPACK_ROW_MAJOR ) or column major ( LAPACK_COL_MAJOR ).
compq
Must be ‘V’ or ‘N’ .
If compq = 'V' , then the Schur vectors ( Q ) are updated. If compq = 'N' , then no Schur vectors are updated.
n
The order of the matrix T ( n≥ 0 ).
- t , q
-
REAL for strexc DOUBLE PRECISION for dtrexc COMPLEX for ctrexc DOUBLE COMPLEX for ztrexc . Arrays:
t (size max(1, ldt * n )) contains the n -by- n matrix T .
The second dimension of t must be at least max(1, n ).
q (size max(1, ldq * n ))
If compq = 'V' , then q must contain Q (Schur vectors). If compq = 'N' , then q is not referenced. The second dimension of q must be at least max(1, n ) if compq = 'V' and at least 1 if compq = 'N' .
ldt
The leading dimension of t ; at least max(1, n ).
ldq
The leading dimension of q ;
If compq = 'N' , then ldq≥ 1 . If compq = 'V' , then ldq≥ max(1, n) .
ifst , ilst
1 ≤ifst≤n; 1 ≤ilst≤n .
Must specify the reordering of the diagonal elements (or blocks, which is possible for real flavors) of the matrix T . The element (or block) with row index ifst is moved to row ilst by a sequence of exchanges between adjacent elements (or blocks).
- work
-
REAL for strexc DOUBLE PRECISION for dtrexc . Array, size at least max (1, n ).
Output Parameters
- t
-
Overwritten by the updated matrix S .
- q
-
If compq = 'V' , q contains the updated matrix of Schur vectors.
- ifst , ilst
-
Overwritten for real flavors only. If ifst pointed to the second row of a 2 by 2 block on entry, it is changed to point to the first row; ilst always points to the first row of the block in its final position (which may differ from its input value by ± 1).
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
The computed matrix \(S\) is exactly similar to a matrix \(T+E\) , where \(||E||_{2} = O(\varepsilon) ||T||_{2}\) , and \(\varepsilon\) is the machine precision.
Note that if a 2 by 2 diagonal block is involved in the re-ordering, its off-diagonal elements are in general changed; the diagonal elements and the eigenvalues of the block are unchanged unless the block is sufficiently ill-conditioned, in which case they may be noticeably altered. It is possible for a 2 by 2 block to break into two 1 by 1 blocks, that is, for a pair of complex eigenvalues to become purely real.
The approximate number of floating-point operations is
for real flavors:
6n(ifst-ilst) if compq = 'N' ;
12n(ifst-ilst) if compq = 'V' ;
for complex flavors:
20n(ifst-ilst) if compq = 'N' ;
40n(ifst-ilst) if compq = 'V' .