nag_zgees (f08pnc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_zgees (f08pnc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_zgees (f08pnc) computes the eigenvalues, the Schur form T, and, optionally, the matrix of Schur vectors Z for an n by n complex nonsymmetric matrix A.

2  Specification

#include <nag.h>
#include <nagf08.h>
void  nag_zgees (Nag_OrderType order, Nag_JobType jobvs, Nag_SortEigValsType sort,
Nag_Boolean (*select)(Complex w),
Integer n, Complex a[], Integer pda, Integer *sdim, Complex w[], Complex vs[], Integer pdvs, NagError *fail)

3  Description

The Schur factorization of A is given by
A = Z T ZH ,
where Z, the matrix of Schur vectors, is unitary and T is the Schur form. A complex matrix is in Schur form if it is upper triangular.
Optionally, nag_zgees (f08pnc) also orders the eigenvalues on the diagonal of the Schur form so that selected eigenvalues are at the top left. The leading columns of Z form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues.

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:     jobvsNag_JobTypeInput
On entry: if jobvs=Nag_DoNothing, Schur vectors are not computed.
If jobvs=Nag_Schur, Schur vectors are computed.
Constraint: jobvs=Nag_DoNothing or Nag_Schur.
3:     sortNag_SortEigValsTypeInput
On entry: specifies whether or not to order the eigenvalues on the diagonal of the Schur form.
sort=Nag_NoSortEigVals
Eigenvalues are not ordered.
sort=Nag_SortEigVals
Eigenvalues are ordered (see select).
Constraint: sort=Nag_NoSortEigVals or Nag_SortEigVals.
4:     selectfunction, supplied by the userExternal Function
If sort=Nag_SortEigVals, select is used to select eigenvalues to sort to the top left of the Schur form.
If sort=Nag_NoSortEigVals, select is not referenced and nag_zgees (f08pnc) may be specified as NULLFN.
An eigenvalue w[j-1] is selected if selectw[j-1] is Nag_TRUE.
The specification of select is:
Nag_Boolean  select (Complex w)
1:     wComplexInput
On entry: the real and imaginary parts of the eigenvalue.
5:     nIntegerInput
On entry: n, the order of the matrix A.
Constraint: n0.
6:     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 n by n matrix A.
On exit: a is overwritten by its Schur form T.
7:     pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraint: pdamax1,n.
8:     sdimInteger *Output
On exit: if sort=Nag_NoSortEigVals, sdim=0.
If sort=Nag_SortEigVals, sdim= number of eigenvalues for which select is Nag_TRUE.
9:     w[dim]ComplexOutput
Note: the dimension, dim, of the array w must be at least max1,n.
On exit: contains the computed eigenvalues, in the same order that they appear on the diagonal of the output Schur form T.
10:   vs[dim]ComplexOutput
Note: the dimension, dim, of the array vs must be at least
  • max1,pdvs×n when jobvs=Nag_Schur;
  • 1 otherwise.
The ith element of the jth vector is stored in
  • vs[j-1×pdvs+i-1] when order=Nag_ColMajor;
  • vs[i-1×pdvs+j-1] when order=Nag_RowMajor.
On exit: if jobvs=Nag_Schur, vs contains the unitary matrix Z of Schur vectors.
If jobvs=Nag_DoNothing, vs is not referenced.
11:   pdvsIntegerInput
On entry: the stride used in the array vs.
Constraints:
  • if jobvs=Nag_Schur, pdvs max1,n ;
  • otherwise pdvs1.
12:   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_CONVERGENCE
The QR algorithm failed to compute all the eigenvalues.
NE_ENUM_INT_2
On entry, jobvs=value, pdvs=value and n=value.
Constraint: if jobvs=Nag_Schur, pdvs max1,n ;
otherwise pdvs1.
NE_INT
On entry, n=value.
Constraint: n0.
On entry, pda=value.
Constraint: pda>0.
On entry, pdvs=value.
Constraint: pdvs>0.
NE_INT_2
On entry, pda=value and n=value.
Constraint: pdamax1,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_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 Schur form no longer satisfy select=Nag_TRUE. This could also be caused by underflow due to scaling.

7  Accuracy

The computed Schur factorization satisfies
A+E=ZT ZH ,
where
E2 = Oε A2 ,
and ε is the machine precision. See Section 4.8 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_dgees (f08pac).

9  Example

This example finds the Schur factorization of the matrix
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 .

9.1  Program Text

Program Text (f08pnce.c)

9.2  Program Data

Program Data (f08pnce.d)

9.3  Program Results

Program Results (f08pnce.r)


nag_zgees (f08pnc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

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