NAG CL Interface
f08npc (zgeevx)
1
Purpose
f08npc computes the eigenvalues and, optionally, the left and/or right eigenvectors for an by complex nonsymmetric matrix .
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.
2
Specification
void |
f08npc (Nag_OrderType order,
Nag_BalanceType balanc,
Nag_LeftVecsType jobvl,
Nag_RightVecsType jobvr,
Nag_RCondType sense,
Integer n,
Complex a[],
Integer pda,
Complex w[],
Complex vl[],
Integer pdvl,
Complex vr[],
Integer pdvr,
Integer *ilo,
Integer *ihi,
double scale[],
double *abnrm,
double rconde[],
double rcondv[],
NagError *fail) |
|
The function may be called by the names: f08npc, nag_lapackeig_zgeevx or nag_zgeevx.
3
Description
The right eigenvector
of
satisfies
where
is the
th eigenvalue of
. The left eigenvector
of
satisfies
where
denotes the conjugate transpose of
.
Balancing a matrix means permuting the rows and columns to make it more nearly upper triangular, and applying a diagonal similarity transformation
, where
is a diagonal matrix, with the aim of making its rows and columns closer in norm and the condition numbers of its eigenvalues and eigenvectors smaller. The computed reciprocal condition numbers correspond to the balanced matrix. Permuting rows and columns will not change the condition numbers (in exact arithmetic) but diagonal scaling will. For further explanation of balancing, see Section 4.8.1.2 of
Anderson et al. (1999).
Following the optional balancing, the matrix is first reduced to upper Hessenberg form by means of unitary similarity transformations, and the algorithm is then used to further reduce the matrix to upper triangular Schur form, , from which the eigenvalues are computed. Optionally, the eigenvectors of are also computed and backtransformed to those of .
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
https://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:
– Nag_OrderType
Input
-
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_BalanceType
Input
-
On entry: indicates how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues.
- Do not diagonally scale or permute.
- Perform permutations to make the matrix more nearly upper triangular. Do not diagonally scale.
- Diagonally scale the matrix, i.e., replace by , where is a diagonal matrix chosen to make the rows and columns of more equal in norm. Do not permute.
- Both diagonally scale and permute .
Computed reciprocal condition numbers will be for the matrix after balancing and/or permuting. Permuting does not change condition numbers (in exact arithmetic), but balancing does.
Constraint:
, , or .
-
3:
– Nag_LeftVecsType
Input
-
On entry: if
, the left eigenvectors of
are not computed.
If , the left eigenvectors of are computed.
If
or
,
jobvl must be set to
.
Constraint:
or .
-
4:
– Nag_RightVecsType
Input
-
On entry: if
, the right eigenvectors of
are not computed.
If , the right eigenvectors of are computed.
If
or
,
jobvr must be set to
.
Constraint:
or .
-
5:
– Nag_RCondType
Input
-
On entry: determines which reciprocal condition numbers are computed.
- None are computed.
- Computed for eigenvalues only.
- Computed for right eigenvectors only.
- Computed for eigenvalues and right eigenvectors.
If or , both left and right eigenvectors must also be computed ( and ).
Constraint:
, , or .
-
6:
– Integer
Input
-
On entry: , the order of the matrix .
Constraint:
.
-
7:
– Complex
Input/Output
-
Note: the dimension,
dim, of the array
a
must be at least
.
The
th element of the matrix
is stored in
- when ;
- when .
On entry: the by matrix .
On exit:
a has been overwritten. If
or
,
contains the Schur form of the balanced version of the matrix
.
-
8:
– Integer
Input
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
a.
Constraint:
.
-
9:
– Complex
Output
-
Note: the dimension,
dim, of the array
w
must be at least
.
On exit: contains the computed eigenvalues.
-
10:
– Complex
Output
-
Note: the dimension,
dim, of the array
vl
must be at least
- when
;
- otherwise.
where
appears in this document, it refers to the array element
- when ;
- when .
On exit: if
, the left eigenvectors
are stored one after another in
vl, in the same order as their corresponding eigenvalues; that is
, for
.
If
,
vl is not referenced.
-
11:
– Integer
Input
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
vl.
Constraints:
- if , ;
- otherwise .
-
12:
– Complex
Output
-
Note: the dimension,
dim, of the array
vr
must be at least
- when
;
- otherwise.
where
appears in this document, it refers to the array element
- when ;
- when .
On exit: if
, the right eigenvectors
are stored one after another in
vr, in the same order as their corresponding eigenvalues; that is
, for
.
If
,
vr is not referenced.
-
13:
– Integer
Input
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
vr.
Constraints:
- if , ;
- otherwise .
-
14:
– Integer *
Output
-
15:
– Integer *
Output
-
On exit:
ilo and
ihi are integer values determined when
was balanced. The balanced
has
if
and
or
.
-
16:
– double
Output
-
Note: the dimension,
dim, of the array
scale
must be at least
.
On exit: details of the permutations and scaling factors applied when balancing
.
If
is the index of the row and column interchanged with row and column
, and
is the scaling factor applied to row and column
, then
- , for ;
- , for ;
- , for .
The order in which the interchanges are made is
n to
, then
to
.
-
17:
– double *
Output
-
On exit: the -norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column).
-
18:
– double
Output
-
Note: the dimension,
dim, of the array
rconde
must be at least
.
On exit: is the reciprocal condition number of the th eigenvalue.
-
19:
– double
Output
-
Note: the dimension,
dim, of the array
rcondv
must be at least
.
On exit: is the reciprocal condition number of the th right eigenvector.
-
20:
– NagError *
Input/Output
-
The NAG error argument (see
Section 7 in the Introduction to the NAG Library CL Interface).
6
Error 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_CONVERGENCE
-
The
algorithm failed to compute all the eigenvalues, and no eigenvectors or condition numbers have been computed; elements
to
and
to
n of
w contain eigenvalues which have converged.
- 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: .
- NE_INT_2
-
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_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.
7
Accuracy
The computed eigenvalues and eigenvectors are exact for a nearby matrix
, where
and
is the
machine precision. See Section 4.8 of
Anderson et al. (1999) for further details.
8
Parallelism and Performance
f08npc is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
f08npc 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.
Each eigenvector is normalized to have Euclidean norm equal to unity and the element of largest absolute value real.
The total number of floating-point operations is proportional to .
The real analogue of this function is
f08nbc.
10
Example
This example finds all the eigenvalues and right eigenvectors of the matrix
together with estimates of the condition number and forward error bounds for each eigenvalue and eigenvector. The option to balance the matrix is used. In order to compute the condition numbers of the eigenvalues, the left eigenvectors also have to be computed, but they are not printed out in this example.
10.1
Program Text
10.2
Program Data
10.3
Program Results