F08YTF (ZTGEXC) (PDF version)
F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual

# NAG Library Routine DocumentF08YTF (ZTGEXC)

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

## 1  Purpose

F08YTF (ZTGEXC) reorders the generalized Schur factorization of a complex matrix pair in generalized Schur form.

## 2  Specification

 SUBROUTINE F08YTF ( WANTQ, WANTZ, N, A, LDA, B, LDB, Q, LDQ, Z, LDZ, IFST, ILST, INFO)
 INTEGER N, LDA, LDB, LDQ, LDZ, IFST, ILST, INFO COMPLEX (KIND=nag_wp) A(LDA,*), B(LDB,*), Q(LDQ,*), Z(LDZ,*) LOGICAL WANTQ, WANTZ
The routine may be called by its LAPACK name ztgexc.

## 3  Description

F08YTF (ZTGEXC) reorders the generalized complex $n$ by $n$ matrix pair $\left(S,T\right)$ in generalized Schur form, so that the diagonal element of $\left(S,T\right)$ with row index ${i}_{1}$ is moved to row ${i}_{2}$, using a unitary equivalence transformation. That is, $S$ and $T$ are factorized as
 $S = Q^ S^ Z^H , T= Q^ T^ Z^H ,$
where $\left(\stackrel{^}{S},\stackrel{^}{T}\right)$ are also in generalized Schur form.
The pair $\left(S,T\right)$ are in generalized Schur form if $S$ and $T$ are upper triangular as returned, for example, by F08XNF (ZGGES), or F08XSF (ZHGEQZ) with ${\mathbf{JOB}}=\text{'S'}$.
If $S$ and $T$ are the result of a generalized Schur factorization of a matrix pair $\left(A,B\right)$
 $A = QSZH , B= QTZH$
then, optionally, the matrices $Q$ and $Z$ can be updated as $Q\stackrel{^}{Q}$ and $Z\stackrel{^}{Z}$.

## 4  References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug

## 5  Parameters

1:     WANTQ – LOGICALInput
On entry: if ${\mathbf{WANTQ}}=\mathrm{.TRUE.}$, update the left transformation matrix $Q$.
If ${\mathbf{WANTQ}}=\mathrm{.FALSE.}$, do not update $Q$.
2:     WANTZ – LOGICALInput
On entry: if ${\mathbf{WANTZ}}=\mathrm{.TRUE.}$, update the right transformation matrix $Z$.
If ${\mathbf{WANTZ}}=\mathrm{.FALSE.}$, do not update $Z$.
3:     N – INTEGERInput
On entry: $n$, the order of the matrices $S$ and $T$.
Constraint: ${\mathbf{N}}\ge 0$.
4:     A(LDA,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array A must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
On entry: the matrix $S$ in the pair $\left(S,T\right)$.
On exit: the updated matrix $\stackrel{^}{S}$.
5:     LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which F08YTF (ZTGEXC) is called.
Constraint: ${\mathbf{LDA}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
6:     B(LDB,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array B must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
On entry: the matrix $T$, in the pair $\left(S,T\right)$.
On exit: the updated matrix $\stackrel{^}{T}$
7:     LDB – INTEGERInput
On entry: the first dimension of the array B as declared in the (sub)program from which F08YTF (ZTGEXC) is called.
Constraint: ${\mathbf{LDB}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
8:     Q(LDQ,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array Q must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$ if ${\mathbf{WANTQ}}=\mathrm{.TRUE.}$, and at least $1$ otherwise.
On entry: if ${\mathbf{WANTQ}}=\mathrm{.TRUE.}$, the unitary matrix $Q$.
On exit: if ${\mathbf{WANTQ}}=\mathrm{.TRUE.}$, the updated matrix $Q\stackrel{^}{Q}$.
If ${\mathbf{WANTQ}}=\mathrm{.FALSE.}$, Q is not referenced.
9:     LDQ – INTEGERInput
On entry: the first dimension of the array Q as declared in the (sub)program from which F08YTF (ZTGEXC) is called.
Constraints:
• if ${\mathbf{WANTQ}}=\mathrm{.TRUE.}$, ${\mathbf{LDQ}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$;
• otherwise ${\mathbf{LDQ}}\ge 1$.
10:   Z(LDZ,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array Z must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$ if ${\mathbf{WANTZ}}=\mathrm{.TRUE.}$, and at least $1$ otherwise.
On entry: if ${\mathbf{WANTZ}}=\mathrm{.TRUE.}$, the unitary matrix $Z$.
On exit: if ${\mathbf{WANTZ}}=\mathrm{.TRUE.}$, the updated matrix $Z\stackrel{^}{Z}$.
If ${\mathbf{WANTZ}}=\mathrm{.FALSE.}$, Z is not referenced.
11:   LDZ – INTEGERInput
On entry: the first dimension of the array Z as declared in the (sub)program from which F08YTF (ZTGEXC) is called.
Constraints:
• if ${\mathbf{WANTZ}}=\mathrm{.TRUE.}$, ${\mathbf{LDZ}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$;
• otherwise ${\mathbf{LDZ}}\ge 1$.
12:   IFST – INTEGERInput
13:   ILST – INTEGERInput/Output
On entry: the indices ${i}_{1}$ and ${i}_{2}$ that specify the reordering of the diagonal elements of $\left(S,T\right)$. The element with row index IFST is moved to row ILST, by a sequence of swapping between adjacent diagonal elements.
On exit: ILST points to the row in its final position.
Constraint: $1\le {\mathbf{IFST}}\le {\mathbf{N}}$ and $1\le {\mathbf{ILST}}\le {\mathbf{N}}$.
14:   INFO – INTEGEROutput
On exit: ${\mathbf{INFO}}=0$ unless the routine detects an error (see Section 6).

## 6  Error Indicators and Warnings

Errors or warnings detected by the routine:
${\mathbf{INFO}}<0$
If ${\mathbf{INFO}}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.
${\mathbf{INFO}}=1$
The transformed matrix pair $\left(\stackrel{^}{S},\stackrel{^}{T}\right)$ would be too far from generalized Schur form; the problem is ill-conditioned. $\left(S,T\right)$ may have been partially reordered, and ILST points to the first row of the current position of the block being moved.

## 7  Accuracy

The computed generalized Schur form is nearly the exact generalized Schur form for nearby matrices $\left(S+E\right)$ and $\left(T+F\right)$, where
 $E2 = O⁡ε S2 and F2= O⁡ε T2 ,$
and $\epsilon$ is the machine precision. See Section 4.11 of Anderson et al. (1999) for further details of error bounds for the generalized nonsymmetric eigenproblem.

## 8  Further Comments

The real analogue of this routine is F08YFF (DTGEXC).

## 9  Example

This example exchanges rows 4 and 1 of the matrix pair $\left(S,T\right)$, where
 $S = 4.0+4.0i 1.0+1.0i 1.0+1.0i 2.0-1.0i 0.0i+0.0 2.0+1.0i 1.0+1.0i 1.0+1.0i 0.0i+0.0 0.0i+0.0 2.0-1.0i 1.0+1.0i 0.0i+0.0 0.0i+0.0 0.0i+0.0 6.0-2.0i$
and
 $T = 2.0 1.0+1.0i 1.0+1.0i 3.0-1.0i 0.0 1.0i+0.0 2.0+1.0i 1.0+1.0i 0.0 0.0i+0.0 1.0i+0.0 1.0+1.0i 0.0 0.0i+0.0 0.0i+0.0 2.0i+0.0 .$

### 9.1  Program Text

Program Text (f08ytfe.f90)

### 9.2  Program Data

Program Data (f08ytfe.d)

### 9.3  Program Results

Program Results (f08ytfe.r)

F08YTF (ZTGEXC) (PDF version)
F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual