nag_ztrsna (f08qyc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_ztrsna (f08qyc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_ztrsna (f08qyc) estimates condition numbers for specified eigenvalues and/or right eigenvectors of a complex upper triangular matrix.

2  Specification

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

3  Description

nag_ztrsna (f08qyc) estimates condition numbers for specified eigenvalues and/or right eigenvectors of a complex upper triangular matrix T. These are the same as the condition numbers of the eigenvalues and right eigenvectors of an original matrix A=ZTZH (with unitary Z), from which T may have been derived.
nag_ztrsna (f08qyc) 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_ztrexc (f08qtc) to reorder the eigenvalues so that λi is in the leading position:
T =Q λi cH 0 T22 QH.
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 eigenvalue λj, select[j-1] 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 ComplexInput
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 triangular matrix T, as returned by nag_zhseqr (f08psc).
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 ComplexInput
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 QTQH with Q unitary) corresponding to the eigenpairs specified by how_many and select. The eigenvectors must be stored in consecutive rows or columns (depending on the value of order) of vl, as returned by nag_zhsein (f08pxc) or nag_ztrevc (f08qxc).
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 ComplexInput
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 QTQH with Q unitary) corresponding to the eigenpairs specified by how_many and select. The eigenvectors must be stored in consecutive rows or columns (depending on the value of order) of vr, as returned by nag_zhsein (f08pxc) or nag_ztrevc (f08qxc).
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).
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.
If job=Nag_EigVals, sep is not referenced i.
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, required_rowcol, is n if how_many=Nag_ComputeAll; if how_many=Nag_ComputeSelected, required_rowcol is the number of selected eigenpairs (see select), in which case 0required_rowcoln.
Constraint: mmrequired_rowcol.
15:   mInteger *Output
On exit: required_rowcol, the number of selected eigenpairs. 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, mm=value.
Constraint: mmrequired_rowcol, where required_rowcol is the number of selected eigenpairs.
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

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

8  Further Comments

The real analogue of this function is nag_dtrsna (f08qlc).

9  Example

This example computes approximate error estimates for all the eigenvalues and right eigenvectors of the matrix T, where
T = -6.0004-6.9999i 0.3637-0.3656i -0.1880+0.4787i 0.8785-0.2539i 0.0000+0.0000i -5.0000+2.0060i -0.0307-0.7217i -0.2290+0.1313i 0.0000+0.0000i 0.0000+0.0000i 7.9982-0.9964i 0.9357+0.5359i 0.0000+0.0000i 0.0000+0.0000i 0.0000+0.0000i 3.0023-3.9998i .

9.1  Program Text

Program Text (f08qyce.c)

9.2  Program Data

Program Data (f08qyce.d)

9.3  Program Results

Program Results (f08qyce.r)


nag_ztrsna (f08qyc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

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