f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_dtrsna (f08qlc)

## 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 #include
 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=ZT{Z}^{\mathrm{T}}$ (with orthogonal $Z$), from which $T$ may have been derived.
nag_dtrsna (f08qlc) computes the reciprocal of the condition number of an eigenvalue ${\lambda }_{i}$ as
 $si = vHu uEvE ,$
where $u$ and $v$ are the right and left eigenvectors of $T$, respectively, corresponding to ${\lambda }_{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 ${\lambda }_{i}$ is then given by
 $εT si ,$
where $\epsilon$ is the machine precision.
To estimate the reciprocal of the condition number of the right eigenvector corresponding to ${\lambda }_{i}$, the function first calls nag_dtrexc (f08qfc) to reorder the eigenvalues so that ${\lambda }_{i}$ is in the leading position:
 $T =Q λi cT 0 T22 QT.$
The reciprocal condition number of the eigenvector is then estimated as ${\mathit{sep}}_{i}$, the smallest singular value of the matrix $\left({T}_{22}-{\lambda }_{i}I\right)$. 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 ${\lambda }_{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 ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or Nag_ColMajor.
2:     jobNag_JobTypeInput
On entry: indicates whether condition numbers are required for eigenvalues and/or eigenvectors.
${\mathbf{job}}=\mathrm{Nag_EigVals}$
Condition numbers for eigenvalues only are computed.
${\mathbf{job}}=\mathrm{Nag_EigVecs}$
Condition numbers for eigenvectors only are computed.
${\mathbf{job}}=\mathrm{Nag_DoBoth}$
Condition numbers for both eigenvalues and eigenvectors are computed.
Constraint: ${\mathbf{job}}=\mathrm{Nag_EigVals}$, $\mathrm{Nag_EigVecs}$ or $\mathrm{Nag_DoBoth}$.
3:     how_manyNag_HowManyTypeInput
On entry: indicates how many condition numbers are to be computed.
${\mathbf{how_many}}=\mathrm{Nag_ComputeAll}$
Condition numbers for all eigenpairs are computed.
${\mathbf{how_many}}=\mathrm{Nag_ComputeSelected}$
Condition numbers for selected eigenpairs (as specified by select) are computed.
Constraint: ${\mathbf{how_many}}=\mathrm{Nag_ComputeAll}$ or $\mathrm{Nag_ComputeSelected}$.
4:     select[$\mathit{dim}$]const Nag_BooleanInput
Note: the dimension, dim, of the array select must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ when ${\mathbf{how_many}}=\mathrm{Nag_ComputeSelected}$;
• $1$ otherwise.
On entry: specifies the eigenpairs for which condition numbers are to be computed if ${\mathbf{how_many}}=\mathrm{Nag_ComputeSelected}$. To select condition numbers for the eigenpair corresponding to the real eigenvalue ${\lambda }_{j}$, ${\mathbf{select}}\left[j-1\right]$ must be set Nag_TRUE. To select condition numbers corresponding to a complex conjugate pair of eigenvalues ${\lambda }_{j}$ and ${\lambda }_{j+1}$, ${\mathbf{select}}\left[j-1\right]$ and/or ${\mathbf{select}}\left[j\right]$ must be set to Nag_TRUE.
If ${\mathbf{how_many}}=\mathrm{Nag_ComputeAll}$, select is not referenced.
5:     nIntegerInput
On entry: $n$, the order of the matrix $T$.
Constraint: ${\mathbf{n}}\ge 0$.
6:     t[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array t must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdt}}×{\mathbf{n}}\right)$.
The $\left(i,j\right)$th element of the matrix $T$ is stored in
• ${\mathbf{t}}\left[\left(j-1\right)×{\mathbf{pdt}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{t}}\left[\left(i-1\right)×{\mathbf{pdt}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{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: ${\mathbf{pdt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
8:     vl[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array vl must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdvl}}×{\mathbf{mm}}\right)$ when ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$ and ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}×{\mathbf{pdvl}}\right)$ when ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$ and ${\mathbf{order}}=\mathrm{Nag_RowMajor}$;
• $1$ when ${\mathbf{job}}=\mathrm{Nag_EigVecs}$.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{vl}}\left[\left(j-1\right)×{\mathbf{pdvl}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{vl}}\left[\left(i-1\right)×{\mathbf{pdvl}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, vl must contain the left eigenvectors of $T$ (or of any matrix $QT{Q}^{\mathrm{T}}$ 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 ${\mathbf{job}}=\mathrm{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 ${\mathbf{order}}=\mathrm{Nag_ColMajor}$,
• if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvl}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{job}}=\mathrm{Nag_EigVecs}$, ${\mathbf{pdvl}}\ge 1$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$,
• if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvl}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$;
• if ${\mathbf{job}}=\mathrm{Nag_EigVecs}$, ${\mathbf{pdvl}}\ge 1$.
10:   vr[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array vr must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdvr}}×{\mathbf{mm}}\right)$ when ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$ and ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}×{\mathbf{pdvr}}\right)$ when ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$ and ${\mathbf{order}}=\mathrm{Nag_RowMajor}$;
• $1$ when ${\mathbf{job}}=\mathrm{Nag_EigVecs}$.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{vr}}\left[\left(j-1\right)×{\mathbf{pdvr}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{vr}}\left[\left(i-1\right)×{\mathbf{pdvr}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, vr must contain the right eigenvectors of $T$ (or of any matrix $QT{Q}^{\mathrm{T}}$ 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 ${\mathbf{job}}=\mathrm{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 ${\mathbf{order}}=\mathrm{Nag_ColMajor}$,
• if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvr}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{job}}=\mathrm{Nag_EigVecs}$, ${\mathbf{pdvr}}\ge 1$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$,
• if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvr}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$;
• if ${\mathbf{job}}=\mathrm{Nag_EigVecs}$, ${\mathbf{pdvr}}\ge 1$.
12:   s[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, of the array s must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ when ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$;
• $1$ when ${\mathbf{job}}=\mathrm{Nag_EigVecs}$.
On exit: the reciprocal condition numbers of the selected eigenvalues if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, stored in consecutive elements of the array. Thus ${\mathbf{s}}\left[j-1\right]$, ${\mathbf{sep}}\left[j-1\right]$ and the $j$th rows or columns of vl and vr all correspond to the same eigenpair (but not in general the $j$th 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 ${\mathbf{job}}=\mathrm{Nag_EigVecs}$.
13:   sep[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, of the array sep must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ when ${\mathbf{job}}=\mathrm{Nag_EigVecs}$ or $\mathrm{Nag_DoBoth}$;
• $1$ when ${\mathbf{job}}=\mathrm{Nag_EigVals}$.
On exit: the estimated reciprocal condition numbers of the selected right eigenvectors if ${\mathbf{job}}=\mathrm{Nag_EigVecs}$ or $\mathrm{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 ${\mathbf{sep}}\left[j-1\right]$, then ${\mathbf{sep}}\left[j-1\right]$ is set to zero; this can only occur when the true value would be very small anyway.
If ${\mathbf{job}}=\mathrm{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 ${\mathbf{how_many}}=\mathrm{Nag_ComputeAll}$; if ${\mathbf{how_many}}=\mathrm{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 $0\le m\le n$.
Constraint: ${\mathbf{mm}}\ge {\mathbf{m}}$.
15:   mInteger *Output
On exit: $m$, the number of elements of s and/or sep actually used to store the estimated condition numbers. If ${\mathbf{how_many}}=\mathrm{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.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_ENUM_INT_2
On entry, ${\mathbf{job}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdvl}}=〈\mathit{\text{value}}〉$, ${\mathbf{mm}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvl}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$;
if ${\mathbf{job}}=\mathrm{Nag_EigVecs}$, ${\mathbf{pdvl}}\ge 1$.
On entry, ${\mathbf{job}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdvl}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvl}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
if ${\mathbf{job}}=\mathrm{Nag_EigVecs}$, ${\mathbf{pdvl}}\ge 1$.
On entry, ${\mathbf{job}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdvr}}=〈\mathit{\text{value}}〉$, ${\mathbf{mm}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvr}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$;
if ${\mathbf{job}}=\mathrm{Nag_EigVecs}$, ${\mathbf{pdvr}}\ge 1$.
On entry, ${\mathbf{job}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdvr}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvr}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
if ${\mathbf{job}}=\mathrm{Nag_EigVecs}$, ${\mathbf{pdvr}}\ge 1$.
NE_INT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 0$.
On entry, ${\mathbf{pdt}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdt}}>0$.
On entry, ${\mathbf{pdvl}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdvl}}>0$.
On entry, ${\mathbf{pdvr}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdvr}}>0$.
NE_INT_2
On entry, ${\mathbf{mm}}=〈\mathit{\text{value}}〉$ and ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{mm}}\ge {\mathbf{m}}$.
On entry, ${\mathbf{pdt}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
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 ${\mathit{sep}}_{i}$ may over estimate the true value, but seldom by a factor of more than $3$.

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)