F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual

NAG Library Routine DocumentF08QLF (DTRSNA)

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

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

2  Specification

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

3  Description

F08QLF (DTRSNA) 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.
F08QLF (DTRSNA) 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 F08QFF (DTREXC) 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  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 real eigenvalue ${\lambda }_{j}$, ${\mathbf{SELECT}}\left(j\right)$ must be set .TRUE.. To select condition numbers corresponding to a complex conjugate pair of eigenvalues ${\lambda }_{j}$ and ${\lambda }_{j+1}$, ${\mathbf{SELECT}}\left(j\right)$ and/or ${\mathbf{SELECT}}\left(j+1\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,$*$) – REAL (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 quasi-triangular matrix $T$ in canonical Schur form, as returned by F08PEF (DHSEQR).
6:     LDT – INTEGERInput
On entry: the first dimension of the array T as declared in the (sub)program from which F08QLF (DTRSNA) is called.
Constraint: ${\mathbf{LDT}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
7:     VL(LDVL,$*$) – REAL (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{T}}$ with $Q$ orthogonal) corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VL, as returned by F08PKF (DHSEIN) or F08QKF (DTREVC).
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 F08QLF (DTRSNA) 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,$*$) – REAL (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{T}}$ with $Q$ orthogonal) corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VR, as returned by F08PKF (DHSEIN) or F08QKF (DTREVC).
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 F08QLF (DTRSNA) 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). 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}}=\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. 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\right)$, then ${\mathbf{SEP}}\left(j\right)$ is set to zero; this can only occur when the true value would be very small anyway.
If ${\mathbf{JOB}}=\text{'E'}$, SEP is not referenced.
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, $m$, is $n$ if ${\mathbf{HOWMNY}}=\text{'A'}$; if ${\mathbf{HOWMNY}}=\text{'S'}$, $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}}$.
14:   M – INTEGEROutput
On exit: $m$, the number of elements of S and/or SEP actually used to store the estimated condition numbers. If ${\mathbf{HOWMNY}}=\text{'A'}$, M is set to $n$.
15:   WORK(LDWORK,$*$) – REAL (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}}+6\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 F08QLF (DTRSNA) 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:   IWORK($*$) – INTEGER arrayWorkspace
Note: the dimension of the array IWORK must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,2×\left({\mathbf{N}}-1\right)\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$.

For a description of canonical Schur form, see the document for F08PEF (DHSEQR).
The complex analogue of this routine is F08QYF (ZTRSNA).

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

9.2  Program Data

Program Data (f08qlfe.d)

9.3  Program Results

Program Results (f08qlfe.r)