F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual

# NAG Library Routine DocumentF08QYF (ZTRSNA)

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

## 1  Purpose

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

## 2  Specification

 SUBROUTINE F08QYF ( JOB, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, S, SEP, MM, M, WORK, LDWORK, RWORK, INFO)
 INTEGER N, LDT, LDVL, LDVR, MM, M, LDWORK, INFO REAL (KIND=nag_wp) S(*), SEP(*), RWORK(*) COMPLEX (KIND=nag_wp) T(LDT,*), VL(LDVL,*), VR(LDVR,*), WORK(LDWORK,*) LOGICAL SELECT(*) CHARACTER(1) JOB, HOWMNY
The routine may be called by its LAPACK name ztrsna.

## 3  Description

F08QYF (ZTRSNA) 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=ZT{Z}^{\mathrm{H}}$ (with unitary $Z$), from which $T$ may have been derived.
F08QYF (ZTRSNA) 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 routine first calls F08QTF (ZTREXC) to reorder the eigenvalues so that ${\lambda }_{i}$ is in the leading position:
 $T =Q λi cH 0 T22 QH.$
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  Parameters

1:     JOB – CHARACTER(1)Input
On entry: indicates whether condition numbers are required for eigenvalues and/or eigenvectors.
${\mathbf{JOB}}=\text{'E'}$
Condition numbers for eigenvalues only are computed.
${\mathbf{JOB}}=\text{'V'}$
Condition numbers for eigenvectors only are computed.
${\mathbf{JOB}}=\text{'B'}$
Condition numbers for both eigenvalues and eigenvectors are computed.
Constraint: ${\mathbf{JOB}}=\text{'E'}$, $\text{'V'}$ or $\text{'B'}$.
2:     HOWMNY – CHARACTER(1)Input
On entry: indicates how many condition numbers are to be computed.
${\mathbf{HOWMNY}}=\text{'A'}$
Condition numbers for all eigenpairs are computed.
${\mathbf{HOWMNY}}=\text{'S'}$
Condition numbers for selected eigenpairs (as specified by SELECT) are computed.
Constraint: ${\mathbf{HOWMNY}}=\text{'A'}$ or $\text{'S'}$.
3:     SELECT($*$) – LOGICAL arrayInput
Note: the dimension of the array SELECT must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$ if ${\mathbf{HOWMNY}}=\text{'S'}$, and at least $1$ otherwise.
On entry: specifies the eigenpairs for which condition numbers are to be computed if ${\mathbf{HOWMNY}}=\text{'S'}$. To select condition numbers for the eigenpair corresponding to the eigenvalue ${\lambda }_{j}$, ${\mathbf{SELECT}}\left(j\right)$ must be set to .TRUE..
If ${\mathbf{HOWMNY}}=\text{'A'}$, SELECT is not referenced.
4:     N – INTEGERInput
On entry: $n$, the order of the matrix $T$.
Constraint: ${\mathbf{N}}\ge 0$.
5:     T(LDT,$*$) – COMPLEX (KIND=nag_wp) arrayInput
Note: the second dimension of the array T must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
On entry: the $n$ by $n$ upper triangular matrix $T$, as returned by F08PSF (ZHSEQR).
6:     LDT – INTEGERInput
On entry: the first dimension of the array T as declared in the (sub)program from which F08QYF (ZTRSNA) is called.
Constraint: ${\mathbf{LDT}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
7:     VL(LDVL,$*$) – COMPLEX (KIND=nag_wp) arrayInput
Note: the second dimension of the array VL must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{MM}}\right)$ if ${\mathbf{JOB}}=\text{'E'}$ or $\text{'B'}$ and at least $1$ if ${\mathbf{JOB}}=\text{'V'}$.
On entry: if ${\mathbf{JOB}}=\text{'E'}$ or $\text{'B'}$, VL must contain the left eigenvectors of $T$ (or of any matrix $QT{Q}^{\mathrm{H}}$ with $Q$ unitary) corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VL, as returned by F08PXF (ZHSEIN) or F08QXF (ZTREVC).
If ${\mathbf{JOB}}=\text{'V'}$, VL is not referenced.
8:     LDVL – INTEGERInput
On entry: the first dimension of the array VL as declared in the (sub)program from which F08QYF (ZTRSNA) is called.
Constraints:
• if ${\mathbf{JOB}}=\text{'E'}$ or $\text{'B'}$, ${\mathbf{LDVL}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$;
• if ${\mathbf{JOB}}=\text{'V'}$, ${\mathbf{LDVL}}\ge 1$.
9:     VR(LDVR,$*$) – COMPLEX (KIND=nag_wp) arrayInput
Note: the second dimension of the array VR must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{MM}}\right)$ if ${\mathbf{JOB}}=\text{'E'}$ or $\text{'B'}$ and at least $1$ if ${\mathbf{JOB}}=\text{'V'}$.
On entry: if ${\mathbf{JOB}}=\text{'E'}$ or $\text{'B'}$, VR must contain the right eigenvectors of $T$ (or of any matrix $QT{Q}^{\mathrm{H}}$ with $Q$ unitary) corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VR, as returned by F08PXF (ZHSEIN) or F08QXF (ZTREVC).
If ${\mathbf{JOB}}=\text{'V'}$, VR is not referenced.
10:   LDVR – INTEGERInput
On entry: the first dimension of the array VR as declared in the (sub)program from which F08QYF (ZTRSNA) is called.
Constraints:
• if ${\mathbf{JOB}}=\text{'E'}$ or $\text{'B'}$, ${\mathbf{LDVR}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$;
• if ${\mathbf{JOB}}=\text{'V'}$, ${\mathbf{LDVR}}\ge 1$.
11:   S($*$) – REAL (KIND=nag_wp) arrayOutput
Note: the dimension of the array S must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{MM}}\right)$ if ${\mathbf{JOB}}=\text{'E'}$ or $\text{'B'}$ and at least $1$ if ${\mathbf{JOB}}=\text{'V'}$.
On exit: the reciprocal condition numbers of the selected eigenvalues if ${\mathbf{JOB}}=\text{'E'}$ or $\text{'B'}$, stored in consecutive elements of the array. Thus ${\mathbf{S}}\left(j\right)$, ${\mathbf{SEP}}\left(j\right)$ and the $j$th 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).
S is not referenced if ${\mathbf{JOB}}=\text{'V'}$.
12:   SEP($*$) – REAL (KIND=nag_wp) arrayOutput
Note: the dimension of the array SEP must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{MM}}\right)$ if ${\mathbf{JOB}}=\text{'V'}$ or $\text{'B'}$ and at least $1$ if ${\mathbf{JOB}}=\text{'E'}$.
On exit: the estimated reciprocal condition numbers of the selected right eigenvectors if ${\mathbf{JOB}}=\text{'V'}$ or $\text{'B'}$, stored in consecutive elements of the array.
If ${\mathbf{JOB}}=\text{'E'}$, SEP is not referenced i.
13:   MM – INTEGERInput
On entry: the number of elements in the arrays S and SEP, and the number of columns in the arrays VL and VR (if used). The precise number required, $\mathit{m}$, is $n$ if ${\mathbf{HOWMNY}}=\text{'A'}$; if ${\mathbf{HOWMNY}}=\text{'S'}$, $\mathit{m}$ is the number of selected eigenpairs (see SELECT), in which case $0\le \mathit{m}\le n$.
Constraint: ${\mathbf{MM}}\ge \mathit{m}$.
14:   M – INTEGEROutput
On exit: $\mathit{m}$, the number of selected eigenpairs. If ${\mathbf{HOWMNY}}=\text{'A'}$, M is set to $n$.
15:   WORK(LDWORK,$*$) – COMPLEX (KIND=nag_wp) arrayWorkspace
Note: the second dimension of the array WORK must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}+1\right)$ if ${\mathbf{JOB}}=\text{'V'}$ or $\text{'B'}$ and at least $1$ if ${\mathbf{JOB}}=\text{'E'}$.
If ${\mathbf{JOB}}=\text{'E'}$, WORK is not referenced.
16:   LDWORK – INTEGERInput
On entry: the first dimension of the array WORK as declared in the (sub)program from which F08QYF (ZTRSNA) is called.
Constraints:
• if ${\mathbf{JOB}}=\text{'V'}$ or $\text{'B'}$, ${\mathbf{LDWORK}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$;
• if ${\mathbf{JOB}}=\text{'E'}$, ${\mathbf{LDWORK}}\ge 1$.
17:   RWORK($*$) – REAL (KIND=nag_wp) arrayWorkspace
Note: the dimension of the array RWORK must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
18:   INFO – INTEGEROutput
On exit: ${\mathbf{INFO}}=0$ unless the routine detects an error (see Section 6).

## 6  Error Indicators and Warnings

${\mathbf{INFO}}<0$
If ${\mathbf{INFO}}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.

## 7  Accuracy

The computed values ${\mathit{sep}}_{i}$ may over estimate the true value, but seldom by a factor of more than $3$.

The real analogue of this routine is F08QLF (DTRSNA).

## 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 (f08qyfe.f90)

### 9.2  Program Data

Program Data (f08qyfe.d)

### 9.3  Program Results

Program Results (f08qyfe.r)