Developer Reference for Intel® oneAPI Math Kernel Library for Fortran
A newer version of this document is available. Customers should click here to go to the newest version.
?tgex2
Swaps adjacent diagonal blocks in an upper (quasi) triangular matrix pair by an orthogonal/unitary equivalence transformation.
Syntax
call stgex2( wantq, wantz, n, a, lda, b, ldb, q, ldq, z, ldz, j1, n1, n2, work, lwork, info )
call dtgex2( wantq, wantz, n, a, lda, b, ldb, q, ldq, z, ldz, j1, n1, n2, work, lwork, info )
call ctgex2( wantq, wantz, n, a, lda, b, ldb, q, ldq, z, ldz, j1, info )
call ztgex2( wantq, wantz, n, a, lda, b, ldb, q, ldq, z, ldz, j1, info )
Include Files
- mkl.fi
Description
The real routines stgex2/dtgex2 swap adjacent diagonal blocks (A11, B11) and (A22, B22) of size 1-by-1 or 2-by-2 in an upper (quasi) triangular matrix pair (A, B) by an orthogonal equivalence transformation. (A, B) must be in generalized real Schur canonical form (as returned by sgges/dgges), that is, A is block upper triangular with 1-by-1 and 2-by-2 diagonal blocks. B is upper triangular.
The complex routines ctgex2/ztgex2 swap adjacent diagonal 1-by-1 blocks (A11, B11) and (A22, B22) in an upper triangular matrix pair (A, B) by an unitary equivalence transformation.
(A, B) must be in generalized Schur canonical form, that is, A and B are both upper triangular.
All routines optionally update the matrices Q and Z of generalized Schur vectors:
For real flavors,
Q(in)*A(in)*Z(in)T = Q(out)*A(out)*Z(out)T
Q(in)*B(in)*Z(in)T = Q(out)*B(out)*Z(out)T.
For complex flavors,
Q(in)*A(in)*Z(in)H = Q(out)*A(out)*Z(out)H
Q(in)*B(in)*Z(in)H = Q(out)*B(out)*Z(out)H.
Input Parameters
- wantq
-
LOGICAL.
If wantq = .TRUE. : update the left transformation matrix Q;
If wantq = .FALSE. : do not update Q.
- wantz
-
LOGICAL.
If wantz = .TRUE. : update the right transformation matrix Z;
If wantz = .FALSE.: do not update Z.
- n
-
INTEGER. The order of the matrices A and B. n≥ 0.
- a, b
-
REAL for stgex2DOUBLE PRECISION for dtgex2
COMPLEX for ctgex2
DOUBLE COMPLEX for ztgex2.
Arrays, DIMENSION (lda, n) and (ldb, n), respectively.
On entry, the matrices A and B in the pair (A, B).
- lda
-
INTEGER. The leading dimension of the array a. lda≥ max(1,n).
- ldb
-
INTEGER. The leading dimension of the array b. ldb≥ max(1,n).
- q, z
-
REAL for stgex2DOUBLE PRECISION for dtgex2
COMPLEX for ctgex2
DOUBLE COMPLEX for ztgex2.
Arrays, DIMENSION (ldq, n) and (ldz, n), respectively.
On entry, if wantq = .TRUE., q contains the orthogonal/unitary matrix Q, and if wantz = .TRUE., z contains the orthogonal/unitary matrix Z.
- ldq
-
INTEGER. The leading dimension of the array q. ldq≥ 1.
If wantq = .TRUE., ldq≥n.
- ldz
-
INTEGER. The leading dimension of the array z. ldz≥ 1.
If wantz = .TRUE., ldz≥n.
- j1
-
INTEGER.
The index to the first block (A11, B11). 1 ≤ j1 ≤ n.
- n1
-
INTEGER. Used with real flavors only. The order of the first block (A11, B11). n1 = 0, 1 or 2.
- n2
-
INTEGER. Used with real flavors only. The order of the second block (A22, B22). n2 = 0, 1 or 2.
- work
-
REAL for stgex2
DOUBLE PRECISION for dtgex2.
Workspace array, DIMENSION(max(1,lwork)). Used with real flavors only.
- lwork
-
INTEGER. The dimension of the array work.
lwork≥max(n*(n2+n1), 2*(n2+n1)2)
Output Parameters
- a
-
On exit, the updated matrix A.
- B
-
On exit, the updated matrix B.
- Q
-
On exit, the updated matrix Q.
Not referenced if wantq = .FALSE..
- z
-
On exit, the updated matrix Z.
Not referenced if wantz = .FALSE..
- info
-
INTEGER.
=0: Successful exit For stgex2/dtgex2: If info = 1, the transformed matrix (A, B) would be too far from generalized Schur form; the blocks are not swapped and (A, B) and (Q, Z) are unchanged. The problem of swapping is too ill-conditioned. If info = -16: lwork is too small. Appropriate value for lwork is returned in work(1).
For ctgex2/ztgex2:
If info = 1, the transformed matrix pair (A, B) would be too far from generalized Schur form; the problem is ill-conditioned.