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_dtgexc (f08yf)

## Purpose

nag_lapack_dtgexc (f08yf) reorders the generalized Schur factorization of a matrix pair in real generalized Schur form.

## Syntax

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

## Description

nag_lapack_dtgexc (f08yf) reorders the generalized real $n$ by $n$ matrix pair $\left(S,T\right)$ in real generalized Schur form, so that the diagonal element or block of $\left(S,T\right)$ with row index ${i}_{1}$ is moved to row ${i}_{2}$, using an orthogonal equivalence transformation. That is, $S$ and $T$ are factorized as
 $S = Q^ S^ Z^T , T= Q^ T^ Z^T ,$
where $\left(\stackrel{^}{S},\stackrel{^}{T}\right)$ are also in real generalized Schur form.
The pair $\left(S,T\right)$ are in real generalized Schur form if $S$ is block upper triangular with $1$ by $1$ and $2$ by $2$ diagonal blocks and $T$ is upper triangular as returned, for example, by nag_lapack_dgges (f08xa), or nag_lapack_dhgeqz (f08xe) 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 = QSZT , B= QTZT$
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)$ – double 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)$ – double 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)$ – double 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 orthogonal matrix $Q$.
6:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – double 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 orthogonal 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 blocks of $\left(S,T\right)$. The block with row index ifst is moved to row ilst, by a sequence of swapping between adjacent blocks.
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)$ – double 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)$ – double 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)$ – double 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)$ – double 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{ifst}$int64int32nag_int scalar
6:     $\mathrm{ilst}$int64int32nag_int scalar
If ifst pointed on entry to the second row of a $2$ by $2$ block, it is changed to point to the first row; ilst always points to the first row of the block in its final position (which may differ from its input value by $+1$ or $-1$).
7:     $\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: work, 15: lwork, 16: 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 complex analogue of this function is nag_lapack_ztgexc (f08yt).

## Example

This example exchanges blocks $2$ and $1$ of the matrix pair $\left(S,T\right)$, where
 $S = 4.0 1.0 1.0 2.0 0.0 3.0 4.0 1.0 0.0 1.0 3.0 1.0 0.0 0.0 0.0 6.0 and T= 2.0 1.0 1.0 3.0 0.0 1.0 2.0 1.0 0.0 0.0 1.0 1.0 0.0 0.0 0.0 2.0 .$
```function f08yf_example

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

% Generalized Schur form matrix pair
n = 4;
S = [4, 1, 1, 2;
0, 3, 4, 1;
0, 1, 3, 1;
0, 0, 0, 6];
T = [2, 1, 1, 3;
0, 1, 2, 1;
0, 0, 1, 1;
0, 0, 0, 2];

% Move block with row index 2 to row 1
ifst = int64(2);
ilst = int64(1);

% Do not update Q and Z
wantq = false;
wantz = false;
q = zeros(n,1);
z = q;

[S, T, ~, ~, ifst, ilst, info] = ...
f08yf( ...
wantq, wantz, S, T, q, z, ifst, ilst);

% Normalize: first nonzero element of each row of S is positive

for i = 1:n
j = max(i-1,1);
while (S(i,j)==0 && j<n)
j = j + 1;
end
if S(i,j)<0
S(i,j:n) = -S(i,j:n);
T(i,i:n) = -T(i,i:n);
end
end
disp('Reordered Schur matrix S');
disp(S);
disp('Reordered Schur matrix T');
disp(T);

```
```f08yf example results

Reordered Schur matrix S
4.1926    1.2591    2.5578    0.4520
0.8712   -0.8627   -2.7912   -1.1383
0         0    4.2426    2.1213
0         0         0    6.0000

Reordered Schur matrix T
1.7439         0    0.7533    0.0661
0   -0.5406   -1.8972   -1.7308
0         0    2.1213    2.8284
0         0         0    2.0000

```