f08wpc computes for a pair of complex nonsymmetric matrices the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the algorithm.
Optionally it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.
The function may be called by the names: f08wpc, nag_lapackeig_zggevx or nag_zggevx.
3Description
A generalized eigenvalue for a pair of matrices is a scalar or a ratio , such that is singular. It is usually represented as the pair , as there is a reasonable interpretation for , and even for both being zero.
The right generalized eigenvector corresponding to the generalized eigenvalue of satisfies
The left generalized eigenvector corresponding to the generalized eigenvalue of satisfies
where is the conjugate-transpose of .
All the eigenvalues and, if required, all the eigenvectors of the complex generalized eigenproblem , where and are complex, square matrices, are determined using the algorithm. The complex algorithm consists of three stages:
1. is reduced to upper Hessenberg form (with real, non-negative subdiagonal elements) and at the same time is reduced to upper triangular form.
2. is further reduced to triangular form while the triangular form of is maintained and the diagonal elements of are made real and non-negative. This is the generalized Schur form of the pair .
This function does not actually produce the eigenvalues , but instead returns and such that
The division by becomes your responsibility, since may be zero, indicating an infinite eigenvalue.
3.If the eigenvectors are required they are obtained from the triangular matrices and then transformed back into the original coordinate system.
For details of the balancing option, see Section 3 in f08wvc.
4References
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 https://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (2012) Matrix Computations (4th Edition) Johns Hopkins University Press, Baltimore
Wilkinson J H (1979) Kronecker's canonical form and the algorithm Linear Algebra Appl.28 285–303
5Arguments
1: – Nag_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 . See Section 3.1.3 in the Introduction to the NAG Library CL Interface for a more detailed explanation of the use of this argument.
Constraint:
or .
2: – Nag_BalanceTypeInput
On entry: specifies the balance option to be performed.
Do not diagonally scale or permute.
Permute only.
Scale only.
Both permute and scale.
Computed reciprocal condition numbers will be for the matrices after permuting and/or balancing. Permuting does not change condition numbers (in exact arithmetic), but balancing does. In the absence of other information, is recommended.
Constraint:
, , or .
3: – Nag_LeftVecsTypeInput
On entry: if , do not compute the left generalized eigenvectors.
If , compute the left generalized eigenvectors.
Constraint:
or .
4: – Nag_RightVecsTypeInput
On entry: if , do not compute the right generalized eigenvectors.
If , compute the right generalized eigenvectors.
Constraint:
or .
5: – Nag_RCondTypeInput
On entry: determines which reciprocal condition numbers are computed.
None are computed.
Computed for eigenvalues only.
Computed for eigenvectors only.
Computed for eigenvalues and eigenvectors.
Constraint:
, , or .
6: – IntegerInput
On entry: , the order of the matrices and .
Constraint:
.
7: – ComplexInput/Output
Note: the dimension, dim, of the array a
must be at least
.
where appears in this document, it refers to the array element
when ;
when .
On entry: the matrix in the pair .
On exit: a has been overwritten. If or or both, then contains the first part of the Schur form of the ‘balanced’ versions of the input and .
8: – IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraint:
.
9: – ComplexInput/Output
Note: the dimension, dim, of the array b
must be at least
.
where appears in this document, it refers to the array element
On exit: , for , will be the generalized eigenvalues.
Note: the quotients may easily overflow or underflow, and may even be zero. Thus, you should avoid naively computing the ratio . However, will always be less than and usually comparable with in magnitude, and will always be less than and usually comparable with .
13: – ComplexOutput
Note: the dimension, dim, of the array vl
must be at least
when
;
otherwise.
The th element of the matrix is stored in
when ;
when .
On exit: if , the left generalized eigenvectors are stored one after another in the columns of vl, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have .
On entry: the stride separating row or column elements (depending on the value of order) in the array vl.
Constraints:
if , ;
otherwise .
15: – ComplexOutput
Note: the dimension, dim, of the array vr
must be at least
when
;
otherwise.
The th element of the matrix is stored in
when ;
when .
On exit: if , the right generalized eigenvectors are stored one after another in the columns of vr, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have .
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).
6Error Indicators and Warnings
NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
NE_BAD_PARAM
On entry, argument had an illegal value.
NE_EIGENVECTORS
A failure occurred in f08yxc while computing generalized eigenvectors.
NE_ENUM_INT_2
On entry, , and .
Constraint: if , ;
otherwise .
On entry, , and .
Constraint: if , ;
otherwise .
NE_INT
On entry, .
Constraint: .
On entry, . Constraint: .
On entry, . Constraint: .
On entry, . Constraint: .
On entry, . Constraint: .
NE_INT_2
On entry, and .
Constraint: .
On entry, and .
Constraint: .
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.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_ITERATION_QZ
The iteration failed. No eigenvectors have been calculated but alpha and beta should be correct from element .
The iteration failed with an unexpected error, please contact NAG.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
7Accuracy
The computed eigenvalues and eigenvectors are exact for nearby matrices and , where
and is the machine precision.
An approximate error bound on the chordal distance between the th computed generalized eigenvalue and the corresponding exact eigenvalue is
An approximate error bound for the angle between the th computed eigenvector or is given by
Note: interpretation of results obtained with the algorithm often requires a clear understanding of the effects of small changes in the original data. These effects are reviewed in Wilkinson (1979), in relation to the significance of small values of and . It should be noted that if and are both small for any , it may be that no reliance can be placed on any of the computed eigenvalues . You are recommended to study Wilkinson (1979) and, if in difficulty, to seek expert advice on determining the sensitivity of the eigenvalues to perturbations in the data.
8Parallelism and Performance
Background information to multithreading can be found in the Multithreading documentation.
f08wpc is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
f08wpc makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.
9Further Comments
The total number of floating-point operations is proportional to .
This example finds all the eigenvalues and right eigenvectors of the matrix pair ,
where
and
together with estimates of the condition number and forward error bounds for each eigenvalue and eigenvector. The option to balance the matrix pair is used.