# NAG Library Routine Document

## 1Purpose

f08ytf (ztgexc) reorders the generalized Schur factorization of a complex matrix pair in generalized Schur form.

## 2Specification

Fortran Interface
 Subroutine f08ytf ( n, a, lda, b, ldb, q, ldq, z, ldz, ifst, ilst, info)
 Integer, Intent (In) :: n, lda, ldb, ldq, ldz, ifst Integer, Intent (Inout) :: ilst Integer, Intent (Out) :: info Complex (Kind=nag_wp), Intent (Inout) :: a(lda,*), b(ldb,*), q(ldq,*), z(ldz,*) Logical, Intent (In) :: wantq, wantz
C Header Interface
#include nagmk26.h
 void f08ytf_ ( const logical *wantq, const logical *wantz, const Integer *n, Complex a[], const Integer *lda, Complex b[], const Integer *ldb, Complex q[], const Integer *ldq, Complex z[], const Integer *ldz, const Integer *ifst, Integer *ilst, Integer *info)
The routine may be called by its LAPACK name ztgexc.

## 3Description

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}$.
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

## 5Arguments

1:     $\mathbf{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:     $\mathbf{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:     $\mathbf{n}$ – IntegerInput
On entry: $n$, the order of the matrices $S$ and $T$.
Constraint: ${\mathbf{n}}\ge 0$.
4:     $\mathbf{a}\left({\mathbf{lda}},*\right)$ – 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:     $\mathbf{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:     $\mathbf{b}\left({\mathbf{ldb}},*\right)$ – 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:     $\mathbf{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:     $\mathbf{q}\left({\mathbf{ldq}},*\right)$ – 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:     $\mathbf{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:   $\mathbf{z}\left({\mathbf{ldz}},*\right)$ – 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:   $\mathbf{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:   $\mathbf{ifst}$ – IntegerInput
13:   $\mathbf{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:   $\mathbf{info}$ – IntegerOutput
On exit: ${\mathbf{info}}=0$ unless the routine detects an error (see Section 6).

## 6Error Indicators and Warnings

${\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 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.

## 7Accuracy

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.

## 8Parallelism and Performance

f08ytf (ztgexc) is not threaded in any implementation.

## 9Further Comments

The real analogue of this routine is f08yff (dtgexc).

## 10Example

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 .$

### 10.1Program Text

Program Text (f08ytfe.f90)

### 10.2Program Data

Program Data (f08ytfe.d)

### 10.3Program Results

Program Results (f08ytfe.r)

© The Numerical Algorithms Group Ltd, Oxford, UK. 2017