nag_dtrsna (f08qlc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_dtrsna (f08qlc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_dtrsna (f08qlc) estimates condition numbers for specified eigenvalues and/or right eigenvectors of a real upper quasi-triangular matrix.

2  Specification

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

3  Description

nag_dtrsna (f08qlc) estimates condition numbers for specified eigenvalues and/or right eigenvectors of a real upper quasi-triangular matrix T in canonical Schur form. These are the same as the condition numbers of the eigenvalues and right eigenvectors of an original matrix A=ZTZT (with orthogonal Z), from which T may have been derived.
nag_dtrsna (f08qlc) computes the reciprocal of the condition number of an eigenvalue λi as
si = vHu uEvE ,
where u and v are the right and left eigenvectors of T, respectively, corresponding to λi. This reciprocal condition number always lies between zero (i.e., ill-conditioned) and one (i.e., well-conditioned).
An approximate error estimate for a computed eigenvalue λi is then given by
εT si ,
where ε is the machine precision.
To estimate the reciprocal of the condition number of the right eigenvector corresponding to λi, the function first calls nag_dtrexc (f08qfc) to reorder the eigenvalues so that λi is in the leading position:
T =Q λi cT 0 T22 QT.
The reciprocal condition number of the eigenvector is then estimated as sepi, the smallest singular value of the matrix T22-λiI. This number ranges from zero (i.e., ill-conditioned) to very large (i.e., well-conditioned).
An approximate error estimate for a computed right eigenvector u corresponding to λi is then given by
εT sepi .

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:     jobNag_JobTypeInput
On entry: indicates whether condition numbers are required for eigenvalues and/or eigenvectors.
job=Nag_EigVals
Condition numbers for eigenvalues only are computed.
job=Nag_EigVecs
Condition numbers for eigenvectors only are computed.
job=Nag_DoBoth
Condition numbers for both eigenvalues and eigenvectors are computed.
Constraint: job=Nag_EigVals, Nag_EigVecs or Nag_DoBoth.
3:     how_manyNag_HowManyTypeInput
On entry: indicates how many condition numbers are to be computed.
how_many=Nag_ComputeAll
Condition numbers for all eigenpairs are computed.
how_many=Nag_ComputeSelected
Condition numbers for selected eigenpairs (as specified by select) are computed.
Constraint: how_many=Nag_ComputeAll or Nag_ComputeSelected.
4:     select[dim]const Nag_BooleanInput
Note: the dimension, dim, of the array select must be at least
  • max1,n when how_many=Nag_ComputeSelected;
  • 1 otherwise.
On entry: specifies the eigenpairs for which condition numbers are to be computed if how_many=Nag_ComputeSelected. To select condition numbers for the eigenpair corresponding to the real eigenvalue λj, select[j-1] must be set Nag_TRUE. To select condition numbers corresponding to a complex conjugate pair of eigenvalues λj and λj+1, select[j-1] and/or select[j] must be set to Nag_TRUE.
If how_many=Nag_ComputeAll, 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]const doubleInput
Note: the dimension, dim, of the array vl must be at least
  • max1,pdvl×mm when job=Nag_EigVals or Nag_DoBoth and order=Nag_ColMajor;
  • max1,n×pdvl when job=Nag_EigVals or Nag_DoBoth and order=Nag_RowMajor;
  • 1 when job=Nag_EigVecs.
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 job=Nag_EigVals or Nag_DoBoth, vl must contain the left eigenvectors of T (or of any matrix QTQT with Q orthogonal) corresponding to the eigenpairs specified by how_many and select. The eigenvectors must be stored in consecutive rows or columns of vl, as returned by nag_dhsein (f08pkc) or nag_dtrevc (f08qkc).
If job=Nag_EigVecs, 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 job=Nag_EigVals or Nag_DoBoth, pdvl max1,n ;
    • if job=Nag_EigVecs, pdvl1;
  • if order=Nag_RowMajor,
    • if job=Nag_EigVals or Nag_DoBoth, pdvlmax1,mm;
    • if job=Nag_EigVecs, pdvl1.
10:   vr[dim]const doubleInput
Note: the dimension, dim, of the array vr must be at least
  • max1,pdvr×mm when job=Nag_EigVals or Nag_DoBoth and order=Nag_ColMajor;
  • max1,n×pdvr when job=Nag_EigVals or Nag_DoBoth and order=Nag_RowMajor;
  • 1 when job=Nag_EigVecs.
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 job=Nag_EigVals or Nag_DoBoth, vr must contain the right eigenvectors of T (or of any matrix QTQT with Q orthogonal) corresponding to the eigenpairs specified by how_many and select. The eigenvectors must be stored in consecutive rows or columns of vr, as returned by nag_dhsein (f08pkc) or nag_dtrevc (f08qkc).
If job=Nag_EigVecs, 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 job=Nag_EigVals or Nag_DoBoth, pdvr max1,n ;
    • if job=Nag_EigVecs, pdvr1;
  • if order=Nag_RowMajor,
    • if job=Nag_EigVals or Nag_DoBoth, pdvrmax1,mm;
    • if job=Nag_EigVecs, pdvr1.
12:   s[dim]doubleOutput
Note: the dimension, dim, of the array s must be at least
  • max1,mm when job=Nag_EigVals or Nag_DoBoth;
  • 1 when job=Nag_EigVecs.
On exit: the reciprocal condition numbers of the selected eigenvalues if job=Nag_EigVals or Nag_DoBoth, stored in consecutive elements of the array. Thus s[j-1], sep[j-1] and the jth rows or columns of vl and vr all correspond to the same eigenpair (but not in general the jth eigenpair unless all eigenpairs have been selected). For a complex conjugate pair of eigenvalues, two consecutive elements of s are set to the same value.
s is not referenced if job=Nag_EigVecs.
13:   sep[dim]doubleOutput
Note: the dimension, dim, of the array sep must be at least
  • max1,mm when job=Nag_EigVecs or Nag_DoBoth;
  • 1 when job=Nag_EigVals.
On exit: the estimated reciprocal condition numbers of the selected right eigenvectors if job=Nag_EigVecs or Nag_DoBoth, stored in consecutive elements of the array. For a complex eigenvector, two consecutive elements of sep are set to the same value. If the eigenvalues cannot be reordered to compute sep[j-1], then sep[j-1] is set to zero; this can only occur when the true value would be very small anyway.
If job=Nag_EigVals, sep is not referenced.
14:   mmIntegerInput
On entry: the number of elements in the arrays s and sep, and the number of rows or columns (depending on the value of order) in the arrays vl and vr (if used). The precise number required, m, is n if how_many=Nag_ComputeAll; if how_many=Nag_ComputeSelected, m is obtained by counting 1 for each selected real eigenvalue, and 2 for each selected complex conjugate pair of eigenvalues (see select), in which case 0mn.
Constraint: mmm.
15:   mInteger *Output
On exit: m, the number of elements of s and/or sep actually used to store the estimated condition numbers. If how_many=Nag_ComputeAll, m is set to n.
16:   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, job=value, pdvl=value, mm=value.
Constraint: if job=Nag_EigVals or Nag_DoBoth, pdvlmax1,mm;
if job=Nag_EigVecs, pdvl1.
On entry, job=value, pdvl=value and n=value.
Constraint: if job=Nag_EigVals or Nag_DoBoth, pdvl max1,n ;
if job=Nag_EigVecs, pdvl1.
On entry, job=value, pdvr=value, mm=value.
Constraint: if job=Nag_EigVals or Nag_DoBoth, pdvrmax1,mm;
if job=Nag_EigVecs, pdvr1.
On entry, job=value, pdvr=value and n=value.
Constraint: if job=Nag_EigVals or Nag_DoBoth, pdvr max1,n ;
if job=Nag_EigVecs, pdvr1.
NE_INT
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, mm=value and m=value.
Constraint: mmm.
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

The computed values sepi may over estimate the true value, but seldom by a factor of more than 3.

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_ztrsna (f08qyc).

9  Example

This example computes approximate error estimates for all the eigenvalues and right eigenvectors of the matrix T, where
T = 0.7995 -0.1144 0.0060 0.0336 0.0000 -0.0994 0.2478 0.3474 0.0000 -0.6483 -0.0994 0.2026 0.0000 0.0000 0.0000 -0.1007 .

9.1  Program Text

Program Text (f08qlce.c)

9.2  Program Data

Program Data (f08qlce.d)

9.3  Program Results

Program Results (f08qlce.r)


nag_dtrsna (f08qlc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

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