NAG Toolbox: nag_lapack_dggesx (f08xb)

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_dggesx (f08xb), and may be called with the string 'f08xaz'.

[result] = selctg(ar, ai, b)

Input Parameters

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

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

3:     $\mathrm{b}$ – double scalar

An eigenvalue $\left(\mathbf{ar}\left(j\right)+\sqrt{-1}\times \mathbf{ai}\left(j\right)\right)/\mathbf{b}\left(j\right)$ is selected if $\mathbf{selctg}\left(\mathbf{ar}\left(j\right),\mathbf{ai}\left(j\right),\mathbf{b}\left(j\right)\right)$ is true. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy $\mathbf{selctg}\left(\mathbf{ar}\left(j\right),\mathbf{ai}\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{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 deflating subspaces 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'}$.

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

7:     $\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 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. (An error is raised if these dimensions are not equal.)

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

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

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. (Complex conjugate pairs for which selctg is true for either eigenvalue count as $2$.)

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

See the description of beta.

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

See the description of beta.

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

$\left(\mathbf{alphar}\left(\mathit{j}\right)+\mathbf{alphai}\left(\mathit{j}\right)\times i\right)/\mathbf{beta}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{n}$, will be the generalized eigenvalues. $\mathbf{alphar}\left(\mathit{j}\right)+\mathbf{alphai}\left(\mathit{j}\right)\times i$, and $\mathbf{beta}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{n}$, are the diagonals of the complex Schur form $\left(S,T\right)$ that would result if the $2$ by $2$ diagonal blocks of the real Schur form of $\left(A,B\right)$ were further reduced to triangular form using $2$ by $2$ complex unitary transformations.

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

Note:  the quotients $\mathbf{alphar}\left(j\right)/\mathbf{beta}\left(j\right)$ and $\mathbf{alphai}\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, alphar and alphai will always be less than and usually comparable with ${‖\mathbf{a}‖}_2$ in magnitude, and beta will always be less than and usually comparable with ${‖\mathbf{b}‖}_2$.

7:     $\mathrm{vsl}\left(\mathit{ldvsl},:\right)$ – double 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.

8:     $\mathrm{vsr}\left(\mathit{ldvsr},:\right)$ – double 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.

9:     $\mathrm{rconde}\left(2\right)$ – double array

If $\mathbf{sense}=\text{'E'}$ or $\text{'B'}$, $\mathbf{rconde}\left(1\right)$ and $\mathbf{rconde}\left(2\right)$ contain the reciprocal condition numbers for the average of the selected eigenvalues.

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

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

If $\mathbf{sense}=\text{'V'}$ or $\text{'B'}$, $\mathbf{rcondv}\left(1\right)$ and $\mathbf{rcondv}\left(2\right)$ contain the reciprocal condition numbers for the selected deflating subspaces.

if $\mathbf{sense}=\text{'N'}$ or $\text{'E'}$, rcondv 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

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: sense, 6: n, 7: a, 8: lda, 9: b, 10: ldb, 11: sdim, 12: alphar, 13: alphai, 14: beta, 15: vsl, 16: ldvsl, 17: vsr, 18: ldvsr, 19: rconde, 20: rcondv, 21: work, 22: lwork, 23: iwork, 24: liwork, 25: bwork, 26: 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{alphar}\left(j\right)$, $\mathbf{alphai}\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_dhgeqz (f08xe).

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: f08xb_example

function f08xb_example


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

% Matrix pair (A,B)
A = [3.9, 12.5, -34.5, -0.5;
     4.3, 21.5, -47.5,  7.5;
     4.3, 21.5, -43.5,  3.5;
     4.4, 26.0, -46.0,  6.0];
B = [1,    2,    -3,    1;
     1,    3,    -5,    4;
     1,    3,    -4,    3;
     1,    3,    -4,    4];


% Generalized Schur form (S,T) of (A,B), generalized eigenvalues
% and Schur vectors Q and Z with sorting and selecting only
% real eigenvalues
jobvsl = 'Vectors (left)';
jobvsr = 'Vectors (right)';
sortp = 'Sort';
selctg = @(ar, ai, b) (ai == 0) ;
sense = 'Both reciprocal condition numbers';

[S, T, sdim, alphar, alphai, beta, VSL, VSR, rconde, rcondv, info] = ...
  f08xb( ...
         jobvsl, jobvsr, sortp, selctg, sense, A, B);

fprintf('Number of selected eigenvalues = %4d\n\n', sdim);
disp('Selected generalized eigenvalues')
eigs = alphar./beta + i*alphai./beta;
disp(eigs(1:sdim));

fprintf('%s\n%s\n%s = %8.1e, %s = %8.1e\n\n', ...
        'Reciprocals of left and right projection norms onto', ...
        'the deflating subspaces for the selected eigenvalues', ...
        'rconde(1)', rconde(1), 'rconde(2)', rconde(2));
fprintf('%s\n%s\n%s = %8.1e, %s = %8.1e\n\n', ...
        'Reciprocals condition numbers for the left and right', ...
        'deflating subspaces', 'rcondv(1)', rcondv(1), ...
        'rcondv(2)', rcondv(2));

anorm = norm(A,2);
bnorm = norm(B,2);
abnorm = sqrt(anorm^2+bnorm^2);
fprintf('%s = %8.1e\n', ...
        'Approximate asymptotic error bound for selected eigenvalues   ', ...
        x02aj*abnorm/rconde(1));
fprintf('%s = %8.1e\n', ...
        'Approximate asymptotic error bound for the deflating subspaces', ...
        x02aj*abnorm/rcondv(2));

f08xb example results

Number of selected eigenvalues =    2

Selected generalized eigenvalues
    2.0000
    4.0000

Reciprocals of left and right projection norms onto
the deflating subspaces for the selected eigenvalues
rconde(1) =  1.9e-01, rconde(2) =  1.8e-02

Reciprocals condition numbers for the left and right
deflating subspaces
rcondv(1) =  5.4e-02, rcondv(2) =  9.0e-02

Approximate asymptotic error bound for selected eigenvalues    =  5.7e-14
Approximate asymptotic error bound for the deflating subspaces =  1.2e-13