nag_zgges (f08xnc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_zgges (f08xnc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_zgges (f08xnc) 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 .

2  Specification

#include <nag.h>
#include <nagf08.h>
void  nag_zgges (Nag_OrderType order, Nag_LeftVecsType jobvsl, Nag_RightVecsType jobvsr, Nag_SortEigValsType sort,
Nag_Boolean (*selctg)(Complex a, Complex b),
Integer n, Complex a[], Integer pda, Complex b[], Integer pdb, Integer *sdim, Complex alpha[], Complex beta[], Complex vsl[], Integer pdvsl, Complex vsr[], Integer pdvsr, NagError *fail)

3  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_zgges (f08xnc) 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_zgges (f08xnc) computes T to have real non-negative diagonal entries. The generalized Schur factorization, before reordering, is computed by the QZ algorithm.

4  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

5  Arguments

1:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by order=Nag_RowMajor. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: order=Nag_RowMajor or Nag_ColMajor.
2:     jobvslNag_LeftVecsTypeInput
On entry: if jobvsl=Nag_NotLeftVecs, do not compute the left Schur vectors.
If jobvsl=Nag_LeftVecs, compute the left Schur vectors.
Constraint: jobvsl=Nag_NotLeftVecs or Nag_LeftVecs.
3:     jobvsrNag_RightVecsTypeInput
On entry: if jobvsr=Nag_NotRightVecs, do not compute the right Schur vectors.
If jobvsr=Nag_RightVecs, compute the right Schur vectors.
Constraint: jobvsr=Nag_NotRightVecs or Nag_RightVecs.
4:     sortNag_SortEigValsTypeInput
On entry: specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.
sort=Nag_NoSortEigVals
Eigenvalues are not ordered.
sort=Nag_SortEigVals
Eigenvalues are ordered (see selctg).
Constraint: sort=Nag_NoSortEigVals or Nag_SortEigVals.
5:     selctgfunction, supplied by the userExternal Function
If sort=Nag_SortEigVals, selctg is used to select generalized eigenvalues to the top left of the generalized Schur form.
If sort=Nag_NoSortEigVals, selctg is not referenced by nag_zgges (f08xnc), and may be specified as NULLFN.
The specification of selctg is:
Nag_Boolean  selctg (Complex a, Complex b)
1:     aComplexInput
2:     bComplexInput
On entry: an eigenvalue a[j-1] / b[j-1]  is selected if selctg a[j-1],b[j-1]  is Nag_TRUE.
Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy selctg a[j-1],b[j-1]=Nag_TRUE  after ordering. fail.code= NE_SCHUR_REORDER_SELECT in this case.
6:     nIntegerInput
On entry: n, the order of the matrices A and B.
Constraint: n0.
7:     a[dim]ComplexInput/Output
Note: the dimension, dim, of the array a must be at least max1,pda×n.
The i,jth element of the matrix A is stored in
  • a[j-1×pda+i-1] when order=Nag_ColMajor;
  • a[i-1×pda+j-1] when order=Nag_RowMajor.
On entry: the first of the pair of matrices, A.
On exit: a has been overwritten by its generalized Schur form S.
8:     pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraint: pdamax1,n.
9:     b[dim]ComplexInput/Output
Note: the dimension, dim, of the array b must be at least max1,pdb×n.
The i,jth element of the matrix B is stored in
  • b[j-1×pdb+i-1] when order=Nag_ColMajor;
  • b[i-1×pdb+j-1] when order=Nag_RowMajor.
On entry: the second of the pair of matrices, B.
On exit: b has been overwritten by its generalized Schur form T.
10:   pdbIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array b.
Constraint: pdbmax1,n.
11:   sdimInteger *Output
On exit: if sort=Nag_NoSortEigVals, sdim=0.
If sort=Nag_SortEigVals, sdim= number of eigenvalues (after sorting) for which selctg is Nag_TRUE.
12:   alpha[n]ComplexOutput
On exit: see the description of beta.
13:   beta[n]ComplexOutput
On exit: alpha[j-1]/beta[j-1], for j=1,2,,n, will be the generalized eigenvalues. alpha[j-1], for j=1,2,,n and beta[j-1], for j=1,2,,n, are the diagonals of the complex Schur form A,B output by nag_zgges (f08xnc). The beta[j-1] will be non-negative real.
Note:  the quotients alpha[j-1]/beta[j-1] may easily overflow or underflow, and beta[j-1] 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.
14:   vsl[dim]ComplexOutput
Note: the dimension, dim, of the array vsl must be at least
  • max1,pdvsl×n when jobvsl=Nag_LeftVecs;
  • 1 otherwise.
The i,jth element of the matrix is stored in
  • vsl[j-1×pdvsl+i-1] when order=Nag_ColMajor;
  • vsl[i-1×pdvsl+j-1] when order=Nag_RowMajor.
On exit: if jobvsl=Nag_LeftVecs, vsl will contain the left Schur vectors, Q.
If jobvsl=Nag_NotLeftVecs, vsl is not referenced.
15:   pdvslIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array vsl.
Constraints:
  • if jobvsl=Nag_LeftVecs, pdvsl max1,n ;
  • otherwise pdvsl1.
16:   vsr[dim]ComplexOutput
Note: the dimension, dim, of the array vsr must be at least
  • max1,pdvsr×n when jobvsr=Nag_RightVecs;
  • 1 otherwise.
The i,jth element of the matrix is stored in
  • vsr[j-1×pdvsr+i-1] when order=Nag_ColMajor;
  • vsr[i-1×pdvsr+j-1] when order=Nag_RowMajor.
On exit: if jobvsr=Nag_RightVecs, vsr will contain the right Schur vectors, Z.
If jobvsr=Nag_NotRightVecs, vsr is not referenced.
17:   pdvsrIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array vsr.
Constraints:
  • if jobvsr=Nag_RightVecs, pdvsr max1,n ;
  • otherwise pdvsr1.
18:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_ENUM_INT_2
On entry, jobvsl=value, pdvsl=value and n=value.
Constraint: if jobvsl=Nag_LeftVecs, pdvsl max1,n ;
otherwise pdvsl1.
On entry, jobvsr=value, pdvsr=value and n=value.
Constraint: if jobvsr=Nag_RightVecs, pdvsr max1,n ;
otherwise pdvsr1.
NE_INT
On entry, n=value.
Constraint: n0.
On entry, pda=value.
Constraint: pda>0.
On entry, pdb=value.
Constraint: pdb>0.
On entry, pdvsl=value.
Constraint: pdvsl>0.
On entry, pdvsr=value.
Constraint: pdvsr>0.
NE_INT_2
On entry, pda=value and n=value.
Constraint: pdamax1,n.
On entry, pdb=value and n=value.
Constraint: pdbmax1,n.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_ITERATION_QZ
The QZ iteration did not converge and the matrix pair A,B is not in the generalized Schur form. The computed αi and βi should be correct for i=value,,value.
The QZ iteration failed with an unexpected error, please contact NAG.
NE_SCHUR_REORDER
The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).
NE_SCHUR_REORDER_SELECT
After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy selctg=Nag_TRUE. This could also be caused by underflow due to scaling.

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

8  Further Comments

The total number of floating point operations is proportional to n3.
The real analogue of this function is nag_dgges (f08xac).

9  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 .

9.1  Program Text

Program Text (f08xnce.c)

9.2  Program Data

Program Data (f08xnce.d)

9.3  Program Results

Program Results (f08xnce.r)


nag_zgges (f08xnc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2012