NAG Toolbox: nag_lapack_ztgexc (f08yt)

Purpose

Syntax

Description

References

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 $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array a must be at least $\max \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 $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array b must be at least $\max \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 \max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldq}\ge 1$.

The second dimension of the array q must be at least $\max \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 \max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldz}\ge 1$.

The second dimension of the array z must be at least $\max \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 $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array a will be $\max \left(1,\mathbf{n}\right)$.

The updated matrix $\hat{S}$.

2:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array

The first dimension of the array b will be $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array b will be $\max \left(1,\mathbf{n}\right)$.

The updated matrix $\hat{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}=\max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldq}=1$.

The second dimension of the array q will be $\max \left(1,\mathbf{n}\right)$ if $\mathbf{wantq}=\mathit{true}$ and $1$ otherwise.

If $\mathbf{wantq}=\mathit{true}$, the updated matrix $Q\hat{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}=\max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldz}=1$.

The second dimension of the array z will be $\max \left(1,\mathbf{n}\right)$ if $\mathbf{wantz}=\mathit{true}$ and $1$ otherwise.

If $\mathbf{wantz}=\mathit{true}$, the updated matrix $Z\hat{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(\hat{S},\hat{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

Further Comments

Example

Open in the MATLAB editor: f08yt_example

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