hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_lapack_zgges (f08xn)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

Purpose

nag_lapack_zgges (f08xn) computes the generalized eigenvalues, the generalized Schur form S,T  and, optionally, the left and/or right generalized Schur vectors for a pair of n by n complex nonsymmetric matrices A,B .

Syntax

[a, b, sdim, alpha, beta, vsl, vsr, info] = f08xn(jobvsl, jobvsr, sort, selctg, a, b, 'n', n)
[a, b, sdim, alpha, beta, vsl, vsr, info] = nag_lapack_zgges(jobvsl, jobvsr, sort, selctg, a, b, 'n', n)

Description

The generalized Schur factorization for a pair of complex matrices A,B  is given by
A = QSZH ,   B = QTZH ,  
where Q and Z are unitary, T and S are upper triangular. The generalized eigenvalues, λ , of A,B  are computed from the diagonals of T and S and satisfy
Az = λBz ,  
where z is the corresponding generalized eigenvector. λ  is actually returned as the pair α,β  such that
λ = α/β  
since β , or even both α  and β  can be zero. The columns of Q and Z are the left and right generalized Schur vectors of A,B .
Optionally, nag_lapack_zgges (f08xn) can order the generalized eigenvalues on the diagonals of S,T  so that selected eigenvalues are at the top left. The leading columns of Q and Z then form an orthonormal basis for the corresponding eigenspaces, the deflating subspaces.
nag_lapack_zgges (f08xn) computes T to have real non-negative diagonal entries. The generalized Schur factorization, before reordering, is computed by the QZ algorithm.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Parameters

Compulsory Input Parameters

1:     jobvsl – string (length ≥ 1)
If jobvsl='N', do not compute the left Schur vectors.
If jobvsl='V', compute the left Schur vectors.
Constraint: jobvsl='N' or 'V'.
2:     jobvsr – string (length ≥ 1)
If jobvsr='N', do not compute the right Schur vectors.
If jobvsr='V', compute the right Schur vectors.
Constraint: jobvsr='N' or 'V'.
3:     sort – string (length ≥ 1)
Specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.
sort='N'
Eigenvalues are not ordered.
sort='S'
Eigenvalues are ordered (see selctg).
Constraint: sort='N' or 'S'.
4:     selctg – function handle or string containing name of m-file
If sort='S', selctg is used to select generalized eigenvalues to the top left of the generalized Schur form.
If sort='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:     a – complex scalar
2:     b – complex scalar
An eigenvalue aj / bj  is selected if selctg aj,bj  is true.
Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy selctg aj,bj=true  after ordering. info=n+2 in this case.

Output Parameters

1:     result – logical scalar
result=true for selected eigenvalues.
5:     alda: – complex array
The first dimension of the array a must be at least max1,n.
The second dimension of the array a must be at least max1,n.
The first of the pair of matrices, A.
6:     bldb: – complex array
The first dimension of the array b must be at least max1,n.
The second dimension of the array b must be at least max1,n.
The second of the pair of matrices, B.

Optional Input Parameters

1:     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: n0.

Output Parameters

1:     alda: – complex array
The first dimension of the array a will be max1,n.
The second dimension of the array a will be max1,n.
a stores its generalized Schur form S.
2:     bldb: – complex array
The first dimension of the array b will be max1,n.
The second dimension of the array b will be max1,n.
b stores its generalized Schur form T.
3:     sdim int64int32nag_int scalar
If sort='N', sdim=0.
If sort='S', sdim= number of eigenvalues (after sorting) for which selctg is true.
4:     alphan – complex array
See the description of beta.
5:     betan – complex array
alphaj/betaj, for j=1,2,,n, will be the generalized eigenvalues. alphaj, for j=1,2,,n and betaj, for j=1,2,,n, are the diagonals of the complex Schur form A,B output by nag_lapack_zgges (f08xn). The betaj will be non-negative real.
Note:  the quotients alphaj/betaj may easily overflow or underflow, and betaj may even be zero. Thus, you should avoid naively computing the ratio α/β. However, alpha will always be less than and usually comparable with a in magnitude, and beta will always be less than and usually comparable with b.
6:     vslldvsl: – complex array
The first dimension, ldvsl, of the array vsl will be
  • if jobvsl='V', ldvsl= max1,n ;
  • otherwise ldvsl=1.
The second dimension of the array vsl will be max1,n if jobvsl='V' and 1 otherwise.
If jobvsl='V', vsl will contain the left Schur vectors, Q.
If jobvsl='N', vsl is not referenced.
7:     vsrldvsr: – complex array
The first dimension, ldvsr, of the array vsr will be
  • if jobvsr='V', ldvsr= max1,n ;
  • otherwise ldvsr=1.
The second dimension of the array vsr will be max1,n if jobvsr='V' and 1 otherwise.
If jobvsr='V', vsr will contain the right Schur vectors, Z.
If jobvsr='N', vsr is not referenced.
8:     info int64int32nag_int scalar
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.

   info=-i
If 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  info=1ton
The QZ iteration failed. A,B are not in Schur form, but alphaj and betaj should be correct for j=info+1,,n.
   info=n+1
Unexpected error returned from nag_lapack_zhgeqz (f08xs).
W  info=n+2
After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy selctg=true. This could also be caused by underflow due to scaling.
W  info=n+3
The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

Accuracy

The computed generalized Schur factorization satisfies
A+E = QS ZH ,   B+F = QT ZH ,  
where
E,F F = Oε A,B F  
and ε is the machine precision. See Section 4.11 of Anderson et al. (1999) for further details.

Further Comments

The total number of floating-point operations is proportional to n3.
The real analogue of this function is nag_lapack_dgges (f08xa).

Example

This example finds the generalized Schur factorization of the matrix pair A,B, where
A = -21.10-22.50i 53.50-50.50i -34.50+127.50i 7.50+00.50i -0.46-07.78i -3.50-37.50i -15.50+058.50i -10.50-01.50i 4.30-05.50i 39.70-17.10i -68.50+012.50i -7.50-03.50i 5.50+04.40i 14.40+43.30i -32.50-046.00i -19.00-32.50i  
and
B = 1.00-5.00i 1.60+1.20i -3.00+0.00i 0.00-1.00i 0.80-0.60i 3.00-5.00i -4.00+3.00i -2.40-3.20i 1.00+0.00i 2.40+1.80i -4.00-5.00i 0.00-3.00i 0.00+1.00i -1.80+2.40i 0.00-4.00i 4.00-5.00i .  
Note that the block size (NB) of 64 assumed in this example is not realistic for such a small problem, but should be suitable for large problems.
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


PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015