nag_dtrevc (f08qkc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_dtrevc (f08qkc)

+ Contents

    1  Purpose
    7  Accuracy
    9  Example

1  Purpose

nag_dtrevc (f08qkc) computes selected left and/or right eigenvectors of a real upper quasi-triangular matrix.

2  Specification

#include <nag.h>
#include <nagf08.h>
void  nag_dtrevc (Nag_OrderType order, Nag_SideType side, Nag_HowManyType how_many, Nag_Boolean select[], Integer n, const double t[], Integer pdt, double vl[], Integer pdvl, double vr[], Integer pdvr, Integer mm, Integer *m, NagError *fail)

3  Description

nag_dtrevc (f08qkc) computes left and/or right eigenvectors of a real upper quasi-triangular matrix T in canonical Schur form. Such a matrix arises from the Schur factorization of a real general matrix, as computed by nag_dhseqr (f08pec), for example.
The right eigenvector x, and the left eigenvector y, corresponding to an eigenvalue λ, are defined by:
Tx = λx   and   yHT = λyH or ​ TTy = λ-y .
Note that even though T is real, λ, x and y may be complex. If x is an eigenvector corresponding to a complex eigenvalue λ, then the complex conjugate vector x- is the eigenvector corresponding to the complex conjugate eigenvalue λ-.
The function can compute the eigenvectors corresponding to selected eigenvalues, or it can compute all the eigenvectors. In the latter case the eigenvectors may optionally be pre-multiplied by an input matrix Q. Normally Q is an orthogonal matrix from the Schur factorization of a matrix A as A=QTQT; if x is a (left or right) eigenvector of T, then Qx is an eigenvector of A.
The eigenvectors are computed by forward or backward substitution. They are scaled so that, for a real eigenvector x, maxxi=1, and for a complex eigenvector, max Re xi + Im xi =1.

4  References

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:     sideNag_SideTypeInput
On entry: indicates whether left and/or right eigenvectors are to be computed.
side=Nag_RightSide
Only right eigenvectors are computed.
side=Nag_LeftSide
Only left eigenvectors are computed.
side=Nag_BothSides
Both left and right eigenvectors are computed.
Constraint: side=Nag_RightSide, Nag_LeftSide or Nag_BothSides.
3:     how_manyNag_HowManyTypeInput
On entry: indicates how many eigenvectors are to be computed.
how_many=Nag_ComputeAll
All eigenvectors (as specified by side) are computed.
how_many=Nag_BackTransform
All eigenvectors (as specified by side) are computed and then pre-multiplied by the matrix Q (which is overwritten).
how_many=Nag_ComputeSelected
Selected eigenvectors (as specified by side and select) are computed.
Constraint: how_many=Nag_ComputeAll, Nag_BackTransform or Nag_ComputeSelected.
4:     select[dim]Nag_BooleanInput/Output
Note: the dimension, dim, of the array select must be at least
  • max1,n when how_many=Nag_ComputeSelected;
  • 1 otherwise.
On entry: specifies which eigenvectors are to be computed if how_many=Nag_ComputeSelected. To obtain the real eigenvector corresponding to the real eigenvalue λj, select[j-1] must be set Nag_TRUE. To select the complex eigenvector corresponding to a complex conjugate pair of eigenvalues λj and λj+1, select[j-1] and/or select[j] must be set Nag_TRUE; the eigenvector corresponding to the first eigenvalue in the pair is computed.
On exit: if a complex eigenvector was selected as specified above, then select[j-1] is set to Nag_TRUE and select[j] to Nag_FALSE.
If how_many=Nag_ComputeAll or Nag_BackTransform, select is not referenced.
5:     nIntegerInput
On entry: n, the order of the matrix T.
Constraint: n0.
6:     t[dim]const doubleInput
Note: the dimension, dim, of the array t must be at least max1,pdt×n.
The i,jth element of the matrix T is stored in
  • t[j-1×pdt+i-1] when order=Nag_ColMajor;
  • t[i-1×pdt+j-1] when order=Nag_RowMajor.
On entry: the n by n upper quasi-triangular matrix T in canonical Schur form, as returned by nag_dhseqr (f08pec).
7:     pdtIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array t.
Constraint: pdt max1,n .
8:     vl[dim]doubleInput/Output
Note: the dimension, dim, of the array vl must be at least
  • max1,pdvl×mm when side=Nag_LeftSide or Nag_BothSides and order=Nag_ColMajor;
  • max1,n×pdvl when side=Nag_LeftSide or Nag_BothSides and order=Nag_RowMajor;
  • 1 when side=Nag_RightSide.
The i,jth element of the matrix is stored in
  • vl[j-1×pdvl+i-1] when order=Nag_ColMajor;
  • vl[i-1×pdvl+j-1] when order=Nag_RowMajor.
On entry: if how_many=Nag_BackTransform and side=Nag_LeftSide or Nag_BothSides, vl must contain an n by n matrix Q (usually the matrix of Schur vectors returned by nag_dhseqr (f08pec)).
If how_many=Nag_ComputeAll or Nag_ComputeSelected, vl need not be set.
On exit: if side=Nag_LeftSide or Nag_BothSides, vl contains the computed left eigenvectors (as specified by how_many and select). The eigenvectors are stored consecutively in the rows or columns of the array, in the same order as their eigenvalues. Corresponding to each real eigenvalue is a real eigenvector, occupying one row or column. Corresponding to each complex conjugate pair of eigenvalues, is a complex eigenvector occupying two rows or columns; the first row or column holds the real part and the second row or column holds the imaginary part.
If side=Nag_RightSide, vl is not referenced.
9:     pdvlIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array vl.
Constraints:
  • if order=Nag_ColMajor,
    • if side=Nag_LeftSide or Nag_BothSides, pdvl max1,n ;
    • if side=Nag_RightSide, pdvl1;
  • if order=Nag_RowMajor,
    • if side=Nag_LeftSide or Nag_BothSides, pdvlmax1,mm;
    • if side=Nag_RightSide, pdvl1.
10:   vr[dim]doubleInput/Output
Note: the dimension, dim, of the array vr must be at least
  • max1,pdvr×mm when side=Nag_RightSide or Nag_BothSides and order=Nag_ColMajor;
  • max1,n×pdvr when side=Nag_RightSide or Nag_BothSides and order=Nag_RowMajor;
  • 1 when side=Nag_LeftSide.
The i,jth element of the matrix is stored in
  • vr[j-1×pdvr+i-1] when order=Nag_ColMajor;
  • vr[i-1×pdvr+j-1] when order=Nag_RowMajor.
On entry: if how_many=Nag_BackTransform and side=Nag_RightSide or Nag_BothSides, vr must contain an n by n matrix Q (usually the matrix of Schur vectors returned by nag_dhseqr (f08pec)).
If how_many=Nag_ComputeAll or Nag_ComputeSelected, vr need not be set.
On exit: if side=Nag_RightSide or Nag_BothSides, vr contains the computed right eigenvectors (as specified by how_many and select). The eigenvectors are stored consecutively in the rows or columns of the array, in the same order as their eigenvalues. Corresponding to each real eigenvalue is a real eigenvector, occupying one row or column. Corresponding to each complex conjugate pair of eigenvalues, is a complex eigenvector occupying two rows or columns; the first row or column holds the real part and the second row or column holds the imaginary part.
If side=Nag_LeftSide, vr is not referenced.
11:   pdvrIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array vr.
Constraints:
  • if order=Nag_ColMajor,
    • if side=Nag_RightSide or Nag_BothSides, pdvr max1,n ;
    • if side=Nag_LeftSide, pdvr1;
  • if order=Nag_RowMajor,
    • if side=Nag_RightSide or Nag_BothSides, pdvrmax1,mm;
    • if side=Nag_LeftSide, pdvr1.
12:   mmIntegerInput
On entry: the number of rows or columns in the arrays vl and/or vr. The precise number of rows or columns required (depending on the value of order), required_rowcol, is n if how_many=Nag_ComputeAll or Nag_BackTransform; if how_many=Nag_ComputeSelected, required_rowcol is obtained by counting 1 for each selected real eigenvector and 2 for each selected complex eigenvector (see select), in which case 0required_rowcoln.
Constraint: mmrequired_rowcol.
13:   mInteger *Output
On exit: required_rowcol, the number of rows or columns of vl and/or vr actually used to store the computed eigenvectors. If how_many=Nag_ComputeAll or Nag_BackTransform, m is set to n.
14:   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, side=value, pdvl=value, mm=value.
Constraint: if side=Nag_LeftSide or Nag_BothSides, pdvlmax1,mm;
if side=Nag_RightSide, pdvl1.
On entry, side=value, pdvl=value and n=value.
Constraint: if side=Nag_LeftSide or Nag_BothSides, pdvl max1,n ;
if side=Nag_RightSide, pdvl1.
On entry, side=value, pdvr=value, mm=value.
Constraint: if side=Nag_RightSide or Nag_BothSides, pdvrmax1,mm;
if side=Nag_LeftSide, pdvr1.
On entry, side=value, pdvr=value and n=value.
Constraint: if side=Nag_RightSide or Nag_BothSides, pdvr max1,n ;
if side=Nag_LeftSide, pdvr1.
NE_INT
On entry, mm=value.
Constraint: mmrequired_rowcol, where required_rowcol is obtained by counting 1 for each selected real eigenvector and 2 for each selected complex eigenvector.
On entry, n=value.
Constraint: n0.
On entry, pdt=value.
Constraint: pdt>0.
On entry, pdvl=value.
Constraint: pdvl>0.
On entry, pdvr=value.
Constraint: pdvr>0.
NE_INT_2
On entry, pdt=value and n=value.
Constraint: pdt max1,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.

7  Accuracy

If xi is an exact right eigenvector, and x~i is the corresponding computed eigenvector, then the angle θx~i,xi between them is bounded as follows:
θ x~i,xi c n ε T2 sepi
where sepi is the reciprocal condition number of xi.
The condition number sepi may be computed by calling nag_dtrsna (f08qlc).

8  Further Comments

For a description of canonical Schur form, see the document for nag_dhseqr (f08pec).
The complex analogue of this function is nag_ztrevc (f08qxc).

9  Example

See Section 9 in nag_dgebal (f08nhc).

nag_dtrevc (f08qkc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

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