NAG Toolbox: nag_lapack_dtgexc (f08yf)

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)$ – double 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)$ – double 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)$ – double 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 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 \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 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 $\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)$ – double 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)$ – double 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)$ – double 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{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(\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: f08yf_example

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