NAG Toolbox: nag_lapack_dtgsen (f08yg)

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 a real eigenvalue ${\lambda }_j$, $\mathbf{select}\left(j\right)$ must be set to true.

To select a complex conjugate pair of eigenvalues ${\lambda }_j$ and ${\lambda }_{j+1}$, corresponding to a $2$ by $2$ diagonal block, either $\mathbf{select}\left(j\right)$ or $\mathbf{select}\left(j+1\right)$ or both must be set to true; a complex conjugate pair of eigenvalues must be either both included in the cluster or both excluded.

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

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

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

8:     $\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 $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)$ – 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{alphar}\left(\mathbf{n}\right)$ – double array

See the description of beta.

4:     $\mathrm{alphai}\left(\mathbf{n}\right)$ – double array

See the description of beta.

5:     $\mathrm{beta}\left(\mathbf{n}\right)$ – double array

$\mathbf{alphar}\left(\mathit{j}\right)/\mathbf{beta}\left(\mathit{j}\right)$ and $\mathbf{alphai}\left(\mathit{j}\right)/\mathbf{beta}\left(\mathit{j}\right)$ are the real and imaginary parts respectively of the $\mathit{j}$th eigenvalue, for $\mathit{j}=1,2,\dots ,\mathbf{n}$.

If $\mathbf{alphai}\left(j\right)$ is zero, then the $j$th eigenvalue is real; if positive then $\mathbf{alphai}\left(j+1\right)$ is negative, and the $j$th and $\left(j+1\right)$st eigenvalues are a complex conjugate pair.

Conjugate pairs of eigenvalues correspond to the $2$ by $2$ diagonal blocks of $\hat{S}$. These $2$ by $2$ blocks can be reduced by applying complex unitary transformations to $\left(\hat{S},\hat{T}\right)$ to obtain the complex Schur form $\left(\tilde{S},\tilde{T}\right)$, where $\tilde{S}$ is triangular (and complex). In this form $\mathbf{alphar}+i\mathbf{alphai}$ and beta are the diagonals of $\tilde{S}$ and $\tilde{T}$ respectively.

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

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

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

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

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

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

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

12:   $\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: alphar, 11: alphai, 12: beta, 13: q, 14: ldq, 15: z, 16: ldz, 17: m, 18: pl, 19: pr, 20: dif, 21: work, 22: lwork, 23: iwork, 24: liwork, 25: 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: f08yg_example

function f08yg_example


fprintf('f08yg 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];

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

% reorder 1st and 4th eigenvalues, and
% get projection norms and upper bound estimates
select = [true;     false;     false;     true];
ijob = int64(4);

% Reorder the Schur factors a and b and update the matrices q and z
[S, T, alphar, alphai, beta, Q, Z, m, pl, pr, dif, info] = ...
f08yg( ...
       ijob, wantq, wantz, select, S, T, Q, Z);

fprintf('Number of selected eigenvalues  = %4d\n\n', m);
eigs = alphar./beta + i*alphai./beta;
disp('Selected Generalized Eigenvalues')
disp(eigs(1:m));
fprintf('%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));

f08yg example results

Number of selected eigenvalues  =    2

Selected Generalized Eigenvalues
    2.0000
    3.0000

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

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

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

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