Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 3/31/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

?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., ldqn.

ldz

INTEGER. The leading dimension of the array z. ldz 1.

If wantz = .TRUE., ldzn.

j1

INTEGER.

The index to the first block (A11, B11). 1 ≤ j1n.

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.

lworkmax(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.