NAG Toolbox: nag_lapack_dgeesx (f08pb)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{jobvs}$ – string (length ≥ 1)

If $\mathbf{jobvs}=\text{'N'}$, Schur vectors are not computed.

If $\mathbf{jobvs}=\text{'V'}$, Schur vectors are computed.

Constraint: $\mathbf{jobvs}=\text{'N'}$ or $\text{'V'}$.

2:     $\mathrm{sort}$ – string (length ≥ 1)

Specifies whether or not to order the eigenvalues on the diagonal of the Schur form.

$\mathbf{sort}=\text{'N'}$

Eigenvalues are not ordered.

$\mathbf{sort}=\text{'S'}$

Eigenvalues are ordered (see select).

Constraint: $\mathbf{sort}=\text{'N'}$ or $\text{'S'}$.

3:     $\mathrm{select}$ – function handle or string containing name of m-file

If $\mathbf{sort}=\text{'S'}$, select is used to select eigenvalues to sort to the top left of the Schur form.

If $\mathbf{sort}=\text{'N'}$, select is not referenced and nag_lapack_dgeesx (f08pb) may be called with the string 'f08paz'.

An eigenvalue $\mathbf{wr}\left(j\right)+\sqrt{-1}\times \mathbf{wi}\left(j\right)$ is selected if $\mathbf{select}\left(\mathbf{wr}\left(j\right),\mathbf{wi}\left(j\right)\right)$ is true. If either one of a complex conjugate pair of eigenvalues is selected, then both are. Note that a selected complex eigenvalue may no longer satisfy $\mathbf{select}\left(\mathbf{wr}\left(j\right),\mathbf{wi}\left(j\right)\right)=\mathit{true}$ after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case info is set to $\mathbf{n}+2$ (see info below).

[result] = select(wr, wi)

Input Parameters

1:     $\mathrm{wr}$ – double scalar

2:     $\mathrm{wi}$ – double scalar

The real and imaginary parts of the eigenvalue.

Output Parameters

1:     $\mathrm{result}$ – logical scalar

$\mathbf{result}=\mathit{true}$ for selected eigenvalues.

4:     $\mathrm{sense}$ – string (length ≥ 1)

Determines which reciprocal condition numbers are computed.

$\mathbf{sense}=\text{'N'}$

None are computed.

$\mathbf{sense}=\text{'E'}$

Computed for average of selected eigenvalues only.

$\mathbf{sense}=\text{'V'}$

Computed for selected right invariant subspace only.

$\mathbf{sense}=\text{'B'}$

Computed for both.

If $\mathbf{sense}=\text{'E'}$, $\text{'V'}$ or $\text{'B'}$, $\mathbf{sort}=\text{'S'}$.

Constraint: $\mathbf{sense}=\text{'N'}$, $\text{'E'}$, $\text{'V'}$ or $\text{'B'}$.

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 $n$ by $n$ matrix $A$.

Optional Input Parameters

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

Default: the first dimension of the array a and the second dimension of the array a. (An error is raised if these dimensions are not equal.)

$n$, the order of the matrix $A$.

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)$.

a stores its real Schur form $T$.

2:     $\mathrm{sdim}$ – int64int32nag_int scalar

If $\mathbf{sort}=\text{'N'}$, $\mathbf{sdim}=0$.

If $\mathbf{sort}=\text{'S'}$, $\mathbf{sdim}=$ number of eigenvalues (after sorting) for which select is true. (Complex conjugate pairs for which select is true for either eigenvalue count as $2$.)

3:     $\mathrm{wr}\left(:\right)$ – double array

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

See the description of wi.

4:     $\mathrm{wi}\left(:\right)$ – double array

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

wr and wi contain the real and imaginary parts, respectively, of the computed eigenvalues in the same order that they appear on the diagonal of the output Schur form $T$. Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first.

5:     $\mathrm{vs}\left(\mathit{ldvs},:\right)$ – double array

The first dimension, $\mathit{ldvs}$, of the array vs will be

• if $\mathbf{jobvs}=\text{'V'}$, $\mathit{ldvs}=\max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldvs}=1$.

The second dimension of the array vs will be $\max \left(1,\mathbf{n}\right)$ if $\mathbf{jobvs}=\text{'V'}$ and $1$ otherwise.

If $\mathbf{jobvs}=\text{'V'}$, vs contains the orthogonal matrix $Z$ of Schur vectors.

If $\mathbf{jobvs}=\text{'N'}$, vs is not referenced.

6:     $\mathrm{rconde}$ – double scalar

If $\mathbf{sense}=\text{'E'}$ or $\text{'B'}$, contains the reciprocal condition number for the average of the selected eigenvalues.

If $\mathbf{sense}=\text{'N'}$ or $\text{'V'}$, rconde is not referenced.

7:     $\mathrm{rcondv}$ – double scalar

If $\mathbf{sense}=\text{'V'}$ or $\text{'B'}$, rcondv contains the reciprocal condition number for the selected right invariant subspace.

If $\mathbf{sense}=\text{'N'}$ or $\text{'E'}$, rcondv is not referenced.

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

$\mathbf{info}=0$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

   $\mathbf{info}=-i$

If $\mathbf{info}=-i$, parameter $i$ had an illegal value on entry. The parameters are numbered as follows:

1: jobvs, 2: sort, 3: select, 4: sense, 5: n, 6: a, 7: lda, 8: sdim, 9: wr, 10: wi, 11: vs, 12: ldvs, 13: rconde, 14: rcondv, 15: work, 16: lwork, 17: iwork, 18: liwork, 19: bwork, 20: 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\hspace{0.17em}\text{to}\hspace{0.17em}\mathbf{n}$

If $\mathbf{info}=i$ and $i\le \mathbf{n}$, the $QR$ algorithm failed to compute all the eigenvalues.

W  $\mathbf{info}=\mathbf{n}+1$

The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

W  $\mathbf{info}=\mathbf{n}+2$

After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy $\mathbf{select}=\mathit{true}$. This could also be caused by underflow due to scaling.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f08pb_example

function f08pb_example


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

% Matrix A
a = [ 0.35,  0.45, -0.14, -0.17;
      0.09,  0.07, -0.54,  0.35;
     -0.44, -0.33, -0.03,  0.17;
      0.25, -0.32, -0.13,  0.11];

% Schur vectors of A, selecting real positive eigenvalues
jobvs = 'Vectors (Schur)';
sortp = 'Sort';
select = @(wr, wi) (wr > 0 && wi == 0);
sense = 'Both reciprocal condition numbers';

[~, sdim, wr, wi, vs, rconde, rcondv, info] = ...
f08pb( ...
       jobvs, sortp, select, sense, a);

fprintf('Number of eigenvalues for which SELECT is true = %3d\n',sdim);
fprintf(' (dimension of invariant subspace)\n\n');
disp('Selected eigenvalues');
disp(wr(1:sdim) + i*wi(1:sdim));
fprintf('%s\n%61s = %9.1e\n\n', ...
        'Reciprocal of projection norm onto the invariant subspace', ...
        'rconde', rconde);
fprintf('%s\n%61s = %9.1e\n\n', ...
        'Reciprocal condition number for the invariant subspace', ...
        'rcondv', rcondv);

anorm = norm(a);
erbde = x02aj*anorm/rconde;
erbdv = x02aj*anorm/rcondv;

fprintf('%-61s = %9.1e\n', ...
        'Approximate asymptotic error bound for selected eigenvalues', erbde);
fprintf('%-61s = %9.1e\n', ...
        'Approximate asymptotic error bound for the invariant subspace', ...
        erbdv);

f08pb example results

Number of eigenvalues for which SELECT is true =   1
 (dimension of invariant subspace)

Selected eigenvalues
    0.7995

Reciprocal of projection norm onto the invariant subspace
                                                       rconde =   9.9e-01

Reciprocal condition number for the invariant subspace
                                                       rcondv =   8.2e-01

Approximate asymptotic error bound for selected eigenvalues   =   9.3e-17
Approximate asymptotic error bound for the invariant subspace =   1.1e-16