NAG Toolbox: nag_lapack_ztgsen (f08yu)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{ijob}$ – int64int32nag_int scalar

Specifies whether condition numbers are required for the cluster of eigenvalues ($p$ and $q$) or the deflating subspaces (${\mathrm{Dif}}_u$ and ${\mathrm{Dif}}_l$).

$\mathbf{ijob}=0$

Only reorder with respect to select. No extras.

$\mathbf{ijob}=1$

Reciprocal of norms of ‘projections’ onto left and right eigenspaces with respect to the selected cluster ($p$ and $q$).

$\mathbf{ijob}=2$

The upper bounds on ${\mathrm{Dif}}_u$ and ${\mathrm{Dif}}_l$. $F$-norm-based estimate ($\mathbf{dif}\left(1:2\right)$).

$\mathbf{ijob}=3$

Estimate of ${\mathrm{Dif}}_u$ and ${\mathrm{Dif}}_l$. $1$-norm-based estimate ($\mathbf{dif}\left(1:2\right)$). About five times as expensive as $\mathbf{ijob}=2$.

$\mathbf{ijob}=4$

Compute pl, pr and dif as in $\mathbf{ijob}=0$, $1$ and $2$. Economic version to get it all.

$\mathbf{ijob}=5$

Compute pl, pr and dif as in $\mathbf{ijob}=0$, $1$ and $3$.

Constraint: $0\le \mathbf{ijob}\le 5$.

2:     $\mathrm{wantq}$ – logical scalar

If $\mathbf{wantq}=\mathit{true}$, update the left transformation matrix $Q$.

If $\mathbf{wantq}=\mathit{false}$, do not update $Q$.

3:     $\mathrm{wantz}$ – logical scalar

If $\mathbf{wantz}=\mathit{true}$, update the right transformation matrix $Z$.

If $\mathbf{wantz}=\mathit{false}$, do not update $Z$.

4:     $\mathrm{select}\left(\mathbf{n}\right)$ – logical array

Specifies the eigenvalues in the selected cluster. To select an eigenvalue ${\lambda }_j$, $\mathbf{select}\left(j\right)$ must be set to true.

5:     $\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)$.

6:     $\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)$.

7:     $\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 $n$ by $n$ matrix $Q$.

8:     $\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 $n$ by $n$ matrix $Z$.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the dimension of the array select and 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{alpha}\left(\mathbf{n}\right)$ – complex array

4:     $\mathrm{beta}\left(\mathbf{n}\right)$ – complex array

alpha and beta contain diagonal elements of $\hat{S}$ and $\hat{T}$, respectively, when the pair $\left(S,T\right)$ has been reduced to generalized Schur form. $\mathbf{alpha}\left(\mathit{i}\right)/\mathbf{beta}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$, are the eigenvalues.

5:     $\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.

6:     $\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.

7:     $\mathrm{m}$ – int64int32nag_int scalar

The dimension of the specified pair of left and right eigenspaces (deflating subspaces).

8:     $\mathrm{pl}$ – double scalar

9:     $\mathrm{pr}$ – double scalar

If $\mathbf{ijob}=1$, $4$ or $5$, pl and pr are lower bounds on the reciprocal of the norm of ‘projections’ $p$ and $q$ onto left and right eigenspace with respect to the selected cluster. $0<\mathbf{pl}$, $\mathbf{pr}\le 1$.

If $\mathbf{m}=0$ or $\mathbf{m}=\mathbf{n}$, $\mathbf{pl}=\mathbf{pr}=1$.

If $\mathbf{ijob}=0$, $2$ or $3$, pl and pr are not referenced.

10:   $\mathrm{dif}\left(:\right)$ – double array

The dimension of the array dif will be $2$

If $\mathbf{ijob}\ge 2$, $\mathbf{dif}\left(1:2\right)$ store the estimates of ${\mathrm{Dif}}_u$ and ${\mathrm{Dif}}_l$.

If $\mathbf{ijob}=2$ or $4$, $\mathbf{dif}\left(1:2\right)$ are $F$-norm-based upper bounds on ${\mathrm{Dif}}_u$ and ${\mathrm{Dif}}_l$.

If $\mathbf{ijob}=3$ or $5$, $\mathbf{dif}\left(1:2\right)$ are $1$-norm-based estimates of ${\mathrm{Dif}}_u$ and ${\mathrm{Dif}}_l$.

If $\mathbf{m}=0$ or $n$, $\mathbf{dif}\left(1:2\right)$ $={‖\left(A,B\right)‖}_F$.

If $\mathbf{ijob}=0$ or $1$, dif is not referenced.

11:   $\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: ijob, 2: wantq, 3: wantz, 4: select, 5: n, 6: a, 7: lda, 8: b, 9: ldb, 10: alpha, 11: beta, 12: q, 13: ldq, 14: z, 15: ldz, 16: m, 17: pl, 18: pr, 19: dif, 20: work, 21: lwork, 22: iwork, 23: liwork, 24: 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$

Reordering of $\left(S,T\right)$ failed because the transformed matrix pair $\left(\hat{S},\hat{T}\right)$ would be too far from generalized Schur form; the problem is very ill-conditioned. $\left(S,T\right)$ may have been partially reordered. If requested, $0$ is returned in $\mathbf{dif}\left(1:2\right)$, pl and pr.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f08yu_example

function f08yu_example


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

% Generalized Schur form matrix pair
n = 4;
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];

% Want equivalence transformation matrices Q and Z
wantq = true;
wantz = true;
Q = complex(eye(n));
Z = Q;

% reorder 2nd and 3rd eigenvalues, and
% get projection norms and upper bound estimates
select = [false;     true;     true;     false];
ijob = int64(4);

% Reorder the Schur factors S and T and update the matrices Q and Z
[S, T, alpha, beta, Q, Z, m, pl, pr, dif, info] = ...
  f08yu( ...
         ijob, wantq, wantz, select, S, T, Q, Z);

fprintf('Number of selected eigenvalues  = %4d\n\n', m);
eigs = alpha./beta;
disp('Selected Generalized Eigenvalues')
disp(eigs(1:m));
mtitle = 'Basis of left deflating invariant subspace';
[ifail] = x04db( ...
                 'Gen', ' ', Q(:,1:m), 'B', ' ', mtitle, ...
                 'Int', 'Int', int64(80), int64(0));
fprintf('\n');
mtitle = 'Basis of right deflating invariant subspace';
[ifail] = x04db( ...
                 'Gen', ' ', Z(:,1:m), 'B', ' ', mtitle, ...
                 'Int', 'Int', int64(80), int64(0));
fprintf('\n%s%s\n%10.2e\n', ...
        'Norm estimate of projection onto  left eigenspace ', ...
        'for selected cluster', 1/pl);
fprintf('\n%s%s\n%10.2e\n', ...
        'Norm estimate of projection onto right eigenspace ', ...
        'for selected cluster', 1/pr);
fprintf('\nF-norm based upper bound on Difu\n%10.2e\n', dif(1));
fprintf('\nF-norm based upper bound on Difl\n%10.2e\n', dif(2));

f08yu example results

Number of selected eigenvalues  =    2

Selected Generalized Eigenvalues
   2.0000 + 1.0000i
   2.0000 - 1.0000i

 Basis of left deflating invariant subspace
                      1                   2
 1  (  0.9045,  0.3015) ( -0.0033, -0.2397)
 2  (  0.3015,  0.0000) (  0.2497,  0.7157)
 3  (  0.0000,  0.0000) (  0.0549,  0.6042)
 4  (  0.0000,  0.0000) (  0.0000,  0.0000)

 Basis of right deflating invariant subspace
                      1                   2
 1  (  0.7071,  0.0000) ( -0.5607,  0.0000)
 2  (  0.7071,  0.0000) (  0.5607,  0.0000)
 3  (  0.0000,  0.0000) (  0.0552,  0.6067)
 4  (  0.0000,  0.0000) (  0.0000,  0.0000)

Norm estimate of projection onto  left eigenspace for selected cluster
  8.90e+00

Norm estimate of projection onto right eigenspace for selected cluster
  7.02e+00

F-norm based upper bound on Difu
  2.18e-01

F-norm based upper bound on Difl
  2.62e-01