# ?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 )

## 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:

`Q(in)*A(in)*Z(in)' = Q(out)*A(out)*Z(out)'`

`Q(in)*B(in)*Z(in)' = Q(out)*B(out)*Z(out)'`, where `Z'` is the transpose (conjugate transpose) of Z.

## 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 stgex2 DOUBLE PRECISION for dtgex2

  COMPLEX for ctgex2

  COMPLEX*16 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 stgex2 DOUBLE PRECISION for dtgex2

  COMPLEX for ctgex2

  COMPLEX*16 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.

Parent topic: Auxiliary Routines