NAG Toolbox: nag_lapack_zgees (f08pn)

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_zgees (f08pn) may be called with the string 'f08pnz'.

An eigenvalue $\mathbf{w}\left(j\right)$ is selected if $\mathbf{select}\left(\mathbf{w}\left(j\right)\right)$ is true.

[result] = select(w)

Input Parameters

1:     $\mathrm{w}$ – complex 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{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 $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)$ – 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)$.

a stores its 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 for which select is true.

3:     $\mathrm{w}\left(:\right)$ – complex array

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

Contains the computed eigenvalues, in the same order that they appear on the diagonal of the output Schur form $T$.

4:     $\mathrm{vs}\left(\mathit{ldvs},:\right)$ – complex 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 unitary matrix $Z$ of Schur vectors.

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

5:     $\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: n, 5: a, 6: lda, 7: sdim, 8: w, 9: vs, 10: ldvs, 11: work, 12: lwork, 13: rwork, 14: bwork, 15: 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: f08pn_example

function f08pn_example


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

% Complex matrix A
a = [-3.97 - 5.04i, -4.11 + 3.70i, -0.34 + 1.01i,  1.29 - 0.86i;
      0.34 - 1.50i,  1.52 - 0.43i,  1.88 - 5.38i,  3.36 + 0.65i;
      3.31 - 3.85i,  2.50 + 3.45i,  0.88 - 1.08i,  0.64 - 1.48i;
     -1.10 + 0.82i,  1.81 - 1.59i,  3.25 + 1.33i,  1.57 - 3.44i];

% Schur vectors of A, selecting all eigenvalues
jobvs = 'Vectors (Schur)';
sortp = 'No sort';
[~, sdim, w, ~, info] = f08pn( ...
                               jobvs, sortp, @select, a);

disp('Eigenvalues');
disp(w);

f08pn example results

Eigenvalues
  -6.0004 - 6.9998i
  -5.0000 + 2.0060i
   7.9982 - 0.9964i
   3.0023 - 3.9998i