NAG Toolbox: nag_lapack_zgges (f08xn)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

If $\mathbf{jobvsl}=\text{'N'}$, do not compute the left Schur vectors.

If $\mathbf{jobvsl}=\text{'V'}$, compute the left Schur vectors.

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

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

If $\mathbf{jobvsr}=\text{'N'}$, do not compute the right Schur vectors.

If $\mathbf{jobvsr}=\text{'V'}$, compute the right Schur vectors.

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

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

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

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

Eigenvalues are not ordered.

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

Eigenvalues are ordered (see selctg).

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

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

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

If $\mathbf{sort}=\text{'N'}$, selctg is not referenced by nag_lapack_zgges (f08xn), and may be called with the string 'f08xnz'.

[result] = selctg(a, b)

Input Parameters

1:     $\mathrm{a}$ – complex scalar

2:     $\mathrm{b}$ – complex scalar

An eigenvalue $\mathbf{a}\left(j\right)/\mathbf{b}\left(j\right)$ is selected if $\mathbf{selctg}\left(\mathbf{a}\left(j\right),\mathbf{b}\left(j\right)\right)$ is true.

Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy $\mathbf{selctg}\left(\mathbf{a}\left(j\right),\mathbf{b}\left(j\right)\right)=\mathit{true}$ after ordering. $\mathbf{info}=\mathbf{n}+\mathbf{2}$ in this case.

Output Parameters

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

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

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 first of the pair of matrices, $A$.

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 second of the pair of matrices, $B$.

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.

$n$, the order of the matrices $A$ and $B$.

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 generalized Schur form $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)$.

b stores its generalized Schur form $T$.

3:     $\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 selctg is true.

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

See the description of beta.

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

$\mathbf{alpha}\left(\mathit{j}\right)/\mathbf{beta}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{n}$, will be the generalized eigenvalues. $\mathbf{alpha}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{n}$ and $\mathbf{beta}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{n}$, are the diagonals of the complex Schur form $\left(A,B\right)$ output by nag_lapack_zgges (f08xn). The $\mathbf{beta}\left(j\right)$ will be non-negative real.

Note:  the quotients $\mathbf{alpha}\left(j\right)/\mathbf{beta}\left(j\right)$ may easily overflow or underflow, and $\mathbf{beta}\left(j\right)$ may even be zero. Thus, you should avoid naively computing the ratio $\alpha /\beta$. However, alpha will always be less than and usually comparable with $‖\mathbf{a}‖$ in magnitude, and beta will always be less than and usually comparable with $‖\mathbf{b}‖$.

6:     $\mathrm{vsl}\left(\mathit{ldvsl},:\right)$ – complex array

The first dimension, $\mathit{ldvsl}$, of the array vsl will be

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

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

If $\mathbf{jobvsl}=\text{'V'}$, vsl will contain the left Schur vectors, $Q$.

If $\mathbf{jobvsl}=\text{'N'}$, vsl is not referenced.

7:     $\mathrm{vsr}\left(\mathit{ldvsr},:\right)$ – complex array

The first dimension, $\mathit{ldvsr}$, of the array vsr will be

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

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

If $\mathbf{jobvsr}=\text{'V'}$, vsr will contain the right Schur vectors, $Z$.

If $\mathbf{jobvsr}=\text{'N'}$, vsr 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: jobvsl, 2: jobvsr, 3: sort, 4: selctg, 5: n, 6: a, 7: lda, 8: b, 9: ldb, 10: sdim, 11: alpha, 12: beta, 13: vsl, 14: ldvsl, 15: vsr, 16: ldvsr, 17: work, 18: lwork, 19: rwork, 20: bwork, 21: 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.

W  $\mathbf{info}=1\hspace{0.17em}\text{to}\hspace{0.17em}\mathbf{n}$

The $QZ$ iteration failed. $\left(A,B\right)$ are not in Schur form, but $\mathbf{alpha}\left(j\right)$ and $\mathbf{beta}\left(j\right)$ should be correct for $j=\mathbf{info}+1,\dots ,\mathbf{n}$.

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

Unexpected error returned from nag_lapack_zhgeqz (f08xs).

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

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

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

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

Accuracy

Further Comments

Example

Open in the MATLAB editor: f08xn_example

function f08xn_example


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

% Matrix pair (A,B)
A = [ -21.10 - 22.50i,  53.5 - 50.5i,  -34.5 + 127.5i,   7.5 +  0.5i;
       -0.46 -  7.78i,  -3.5 - 37.5i,  -15.5 +  58.5i, -10.5 -  1.5i;
        4.30 -  5.50i,  39.7 - 17.1i,  -68.5 +  12.5i,  -7.5 -  3.5i;
        5.50 +  4.40i,  14.4 + 43.3i,  -32.5 -  46i,   -19.0 - 32.5i];
B = [ 1   - 5i,    1.6 + 1.2i, -3 + 0i,  0   - 1i;
      0.8 - 0.6i,  3.0 - 5.0i, -4 + 3i, -2.4 - 3.2i;
      1   + 0i,    2.4 + 1.8i, -4 - 5i,  0   - 3i;
      0   + 1i,   -1.8 + 2.4i,  0 - 4i,  4   - 5i];

% Generalized Schur form (S,T) of (A,B), generalized eigenvalues
% and Schur vectors Q and Z with no sorting
jobvsl = 'Vectors (left)';
jobvsr = 'Vectors (right)';
sortp = 'No sort';

[S, T, sdim, alpha, beta, VSL, VSR, info] = ...
  f08xn( ...
         jobvsl, jobvsr, sortp, @selctg, A, B);

% Display eigenvalues in order of magnitude
disp('Generalized eigenvalues')
eigs = alpha./beta;
disp(sort(eigs));

f08xn example results

Generalized eigenvalues
   3.0000 - 1.0000i
   2.0000 - 5.0000i
   4.0000 - 5.0000i
   3.0000 - 9.0000i