Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_ztgexc (f08yt)

## Purpose

nag_lapack_ztgexc (f08yt) reorders the generalized Schur factorization of a complex matrix pair in generalized Schur form.

## Syntax

[a, b, q, z, ilst, info] = f08yt(wantq, wantz, a, b, q, z, ifst, ilst, 'n', n)
[a, b, q, z, ilst, info] = nag_lapack_ztgexc(wantq, wantz, a, b, q, z, ifst, ilst, 'n', n)

## Description

nag_lapack_ztgexc (f08yt) 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 nag_lapack_zgges (f08xn), or nag_lapack_zhgeqz (f08xs) 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}$.

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{wantq}$ – logical scalar
If ${\mathbf{wantq}}=\mathit{true}$, update the left transformation matrix $Q$.
If ${\mathbf{wantq}}=\mathit{false}$, do not update $Q$.
2:     $\mathrm{wantz}$ – logical scalar
If ${\mathbf{wantz}}=\mathit{true}$, update the right transformation matrix $Z$.
If ${\mathbf{wantz}}=\mathit{false}$, do not update $Z$.
3:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The matrix $S$ in the pair $\left(S,T\right)$.
4:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array
The first dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The matrix $T$, in the pair $\left(S,T\right)$.
5:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – complex array
The first dimension, $\mathit{ldq}$, of the array q must satisfy
• if ${\mathbf{wantq}}=\mathit{true}$, $\mathit{ldq}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldq}\ge 1$.
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}}=\mathit{true}$, and at least $1$ otherwise.
If ${\mathbf{wantq}}=\mathit{true}$, the unitary matrix $Q$.
6:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – complex array
The first dimension, $\mathit{ldz}$, of the array z must satisfy
• if ${\mathbf{wantz}}=\mathit{true}$, $\mathit{ldz}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldz}\ge 1$.
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}}=\mathit{true}$, and at least $1$ otherwise.
If ${\mathbf{wantz}}=\mathit{true}$, the unitary matrix $Z$.
7:     $\mathrm{ifst}$int64int32nag_int scalar
8:     $\mathrm{ilst}$int64int32nag_int scalar
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.
Constraint: $1\le {\mathbf{ifst}}\le {\mathbf{n}}$ and $1\le {\mathbf{ilst}}\le {\mathbf{n}}$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the arrays a, b and the second dimension of the arrays a, b. (An error is raised if these dimensions are not equal.)
$n$, the order of the matrices $S$ and $T$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The updated matrix $\stackrel{^}{S}$.
2:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array
The first dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The updated matrix $\stackrel{^}{T}$
3:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – complex array
The first dimension, $\mathit{ldq}$, of the array q will be
• if ${\mathbf{wantq}}=\mathit{true}$, $\mathit{ldq}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldq}=1$.
The second dimension of the array q will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{wantq}}=\mathit{true}$ and $1$ otherwise.
If ${\mathbf{wantq}}=\mathit{true}$, the updated matrix $Q\stackrel{^}{Q}$.
If ${\mathbf{wantq}}=\mathit{false}$, q is not referenced.
4:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – complex array
The first dimension, $\mathit{ldz}$, of the array z will be
• if ${\mathbf{wantz}}=\mathit{true}$, $\mathit{ldz}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldz}=1$.
The second dimension of the array z will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{wantz}}=\mathit{true}$ and $1$ otherwise.
If ${\mathbf{wantz}}=\mathit{true}$, the updated matrix $Z\stackrel{^}{Z}$.
If ${\mathbf{wantz}}=\mathit{false}$, z is not referenced.
5:     $\mathrm{ilst}$int64int32nag_int scalar
ilst points to the row in its final position.
6:     $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $i$ had an illegal value on entry. The parameters are numbered as follows:
1: wantq, 2: wantz, 3: n, 4: a, 5: lda, 6: b, 7: ldb, 8: q, 9: ldq, 10: z, 11: ldz, 12: ifst, 13: ilst, 14: info.
It is possible that info refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.
${\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.

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

The real analogue of this function is nag_lapack_dtgexc (f08yf).

## 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 .$
```function f08yt_example

fprintf('f08yt example results\n\n');

% exchanges rows 4 and 1 of the matrix pair S,T, where
s = [ 4 + 4i,  1 + 1i,  1 + 1i,  2 - 1i;
0 + 0i,  2 + 1i,  1 + 1i,  1 + 1i;
0 + 0i,  0 + 0i,  2 - 1i,  1 + 1i;
0 + 0i,  0 + 0i,  0 + 0i,  6 - 2i];
t = [ 2,       1 + 1i,  1 + 1i,  3 - 1i;
0 + 0i,  1 + 0i,  2 + 1i,  1 + 1i;
0 + 0i,  0 + 0i,  1 + 0i,  1 + 1i;
0 + 0i,  0 + 0i,  0 + 0i,  2 + 0i];

wantq = false;
wantz = false;
q = complex(zeros(1, 4));
z = complex(zeros(1, 4));
ifst = int64(1);
ilst = int64(4);
[s, t, q, z, ilst, info] = ...
f08yt( ...
wantq, wantz, s, t, q, z, ifst, ilst);

disp('Reordered Schur matrix S');
disp(s);
disp('Reordered Schur matrix T');
disp(t);

```
```f08yt example results

Reordered Schur matrix S
3.7081 + 3.7081i  -2.0834 - 0.5688i   2.6374 + 1.0772i   0.2845 + 0.7991i
0.0000 + 0.0000i   1.6097 + 1.5656i  -0.0634 + 1.9234i  -0.0301 + 0.9720i
0.0000 + 0.0000i   0.0000 + 0.0000i   4.7029 - 2.1187i   1.1379 - 3.1199i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   2.3085 - 1.8289i

Reordered Schur matrix T
2.2249 + 0.7416i  -1.1631 + 1.5347i   2.2608 + 2.0851i   1.1094 - 0.3205i
0.0000 + 0.0000i   0.3308 + 0.9482i   0.3919 + 1.8172i  -0.6305 + 1.6053i
0.0000 + 0.0000i   0.0000 + 0.0000i   1.6227 - 0.1653i   0.9966 - 0.9074i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.1199 - 1.0343i

```