Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_dtrsna (f08ql)

## Purpose

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

## Syntax

[s, sep, m, info] = f08ql(job, howmny, select, t, vl, vr, mm, 'n', n)
[s, sep, m, info] = nag_lapack_dtrsna(job, howmny, select, t, vl, vr, mm, 'n', n)

## Description

nag_lapack_dtrsna (f08ql) estimates condition numbers for specified eigenvalues and/or right eigenvectors of a real upper quasi-triangular matrix T$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$A=ZT{Z}^{\mathrm{T}}$ (with orthogonal Z$Z$), from which T$T$ may have been derived.
nag_lapack_dtrsna (f08ql) computes the reciprocal of the condition number of an eigenvalue λi${\lambda }_{i}$ as
 si = (|vHu|)/(‖u‖E‖v‖E) , $si = |vHu| ‖u‖E‖v‖E ,$
where u$u$ and v$v$ are the right and left eigenvectors of T$T$, respectively, corresponding to λi${\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 λi${\lambda }_{i}$ is then given by
 (ε‖T‖)/(si) , $ε‖T‖ si ,$
where ε$\epsilon$ is the machine precision.
To estimate the reciprocal of the condition number of the right eigenvector corresponding to λi${\lambda }_{i}$, the function first calls nag_lapack_dtrexc (f08qf) to reorder the eigenvalues so that λi${\lambda }_{i}$ is in the leading position:
T = Q
 ( λi cT ) 0 T22
QT.
$T =Q λi cT 0 T22 QT.$
The reciprocal condition number of the eigenvector is then estimated as sepi${\mathit{sep}}_{i}$, the smallest singular value of the matrix (T22λiI)$\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$u$ corresponding to λi${\lambda }_{i}$ is then given by
 (ε‖T‖)/(sepi) . $ε‖T‖ sepi .$

## References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## Parameters

### Compulsory Input Parameters

1:     job – string (length ≥ 1)
Indicates whether condition numbers are required for eigenvalues and/or eigenvectors.
job = 'E'${\mathbf{job}}=\text{'E'}$
Condition numbers for eigenvalues only are computed.
job = 'V'${\mathbf{job}}=\text{'V'}$
Condition numbers for eigenvectors only are computed.
job = 'B'${\mathbf{job}}=\text{'B'}$
Condition numbers for both eigenvalues and eigenvectors are computed.
Constraint: job = 'E'${\mathbf{job}}=\text{'E'}$, 'V'$\text{'V'}$ or 'B'$\text{'B'}$.
2:     howmny – string (length ≥ 1)
Indicates how many condition numbers are to be computed.
howmny = 'A'${\mathbf{howmny}}=\text{'A'}$
Condition numbers for all eigenpairs are computed.
howmny = 'S'${\mathbf{howmny}}=\text{'S'}$
Condition numbers for selected eigenpairs (as specified by select) are computed.
Constraint: howmny = 'A'${\mathbf{howmny}}=\text{'A'}$ or 'S'$\text{'S'}$.
3:     select( : $:$) – logical array
Note: the dimension of the array select must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if howmny = 'S'${\mathbf{howmny}}=\text{'S'}$, and at least 1$1$ otherwise.
Specifies the eigenpairs for which condition numbers are to be computed if howmny = 'S'${\mathbf{howmny}}=\text{'S'}$. To select condition numbers for the eigenpair corresponding to the real eigenvalue λj${\lambda }_{j}$, select(j)${\mathbf{select}}\left(j\right)$ must be set true. To select condition numbers corresponding to a complex conjugate pair of eigenvalues λj${\lambda }_{j}$ and λj + 1${\lambda }_{j+1}$, select(j)${\mathbf{select}}\left(j\right)$ and/or select(j + 1)${\mathbf{select}}\left(j+1\right)$ must be set to true.
If howmny = 'A'${\mathbf{howmny}}=\text{'A'}$, select is not referenced.
4:     t(ldt, : $:$) – double array
The first dimension of the array t must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The n$n$ by n$n$ upper quasi-triangular matrix T$T$ in canonical Schur form, as returned by nag_lapack_dhseqr (f08pe).
5:     vl(ldvl, : $:$) – double array
The first dimension, ldvl, of the array vl must satisfy
• if job = 'E'${\mathbf{job}}=\text{'E'}$ or 'B'$\text{'B'}$, ldvl max (1,n) $\mathit{ldvl}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if job = 'V'${\mathbf{job}}=\text{'V'}$, ldvl1$\mathit{ldvl}\ge 1$.
The second dimension of the array must be at least max (1,mm)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ if job = 'E'${\mathbf{job}}=\text{'E'}$ or 'B'$\text{'B'}$ and at least 1$1$ if job = 'V'${\mathbf{job}}=\text{'V'}$
If job = 'E'${\mathbf{job}}=\text{'E'}$ or 'B'$\text{'B'}$, vl must contain the left eigenvectors of T$T$ (or of any matrix QTQT$QT{Q}^{\mathrm{T}}$ with Q$Q$ orthogonal) corresponding to the eigenpairs specified by howmny and select. The eigenvectors must be stored in consecutive columns of vl, as returned by nag_lapack_dhsein (f08pk) or nag_lapack_dtrevc (f08qk).
If job = 'V'${\mathbf{job}}=\text{'V'}$, vl is not referenced.
6:     vr(ldvr, : $:$) – double array
The first dimension, ldvr, of the array vr must satisfy
• if job = 'E'${\mathbf{job}}=\text{'E'}$ or 'B'$\text{'B'}$, ldvr max (1,n) $\mathit{ldvr}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if job = 'V'${\mathbf{job}}=\text{'V'}$, ldvr1$\mathit{ldvr}\ge 1$.
The second dimension of the array must be at least max (1,mm)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ if job = 'E'${\mathbf{job}}=\text{'E'}$ or 'B'$\text{'B'}$ and at least 1$1$ if job = 'V'${\mathbf{job}}=\text{'V'}$
If job = 'E'${\mathbf{job}}=\text{'E'}$ or 'B'$\text{'B'}$, vr must contain the right eigenvectors of T$T$ (or of any matrix QTQT$QT{Q}^{\mathrm{T}}$ with Q$Q$ orthogonal) corresponding to the eigenpairs specified by howmny and select. The eigenvectors must be stored in consecutive columns of vr, as returned by nag_lapack_dhsein (f08pk) or nag_lapack_dtrevc (f08qk).
If job = 'V'${\mathbf{job}}=\text{'V'}$, vr is not referenced.
7:     mm – int64int32nag_int scalar
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$m$, is n$n$ if howmny = 'A'${\mathbf{howmny}}=\text{'A'}$; if howmny = 'S'${\mathbf{howmny}}=\text{'S'}$, m$m$ is obtained by counting 1$1$ for each selected real eigenvalue, and 2$2$ for each selected complex conjugate pair of eigenvalues (see select), in which case 0mn$0\le m\le n$.
Constraint: mmm${\mathbf{mm}}\ge {\mathbf{m}}$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the array t and the second dimension of the array t. (An error is raised if these dimensions are not equal.)
n$n$, the order of the matrix T$T$.
Constraint: n0${\mathbf{n}}\ge 0$.

### Input Parameters Omitted from the MATLAB Interface

ldt ldvl ldvr work ldwork iwork

### Output Parameters

1:     s( : $:$) – double array
Note: the dimension of the array s must be at least max (1,mm)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ if job = 'E'${\mathbf{job}}=\text{'E'}$ or 'B'$\text{'B'}$ and at least 1$1$ if job = 'V'${\mathbf{job}}=\text{'V'}$.
The reciprocal condition numbers of the selected eigenvalues if job = 'E'${\mathbf{job}}=\text{'E'}$ or 'B'$\text{'B'}$, stored in consecutive elements of the array. Thus s(j)${\mathbf{s}}\left(j\right)$, sep(j)${\mathbf{sep}}\left(j\right)$ and the j$j$th columns of vl and vr all correspond to the same eigenpair (but not in general the j$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 job = 'V'${\mathbf{job}}=\text{'V'}$.
2:     sep( : $:$) – double array
Note: the dimension of the array sep must be at least max (1,mm)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ if job = 'V'${\mathbf{job}}=\text{'V'}$ or 'B'$\text{'B'}$ and at least 1$1$ if job = 'E'${\mathbf{job}}=\text{'E'}$.
The estimated reciprocal condition numbers of the selected right eigenvectors if job = 'V'${\mathbf{job}}=\text{'V'}$ or 'B'$\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 sep(j)${\mathbf{sep}}\left(j\right)$, then sep(j)${\mathbf{sep}}\left(j\right)$ is set to zero; this can only occur when the true value would be very small anyway.
If job = 'E'${\mathbf{job}}=\text{'E'}$, sep is not referenced.
3:     m – int64int32nag_int scalar
m$m$, the number of elements of s and/or sep actually used to store the estimated condition numbers. If howmny = 'A'${\mathbf{howmny}}=\text{'A'}$, m is set to n$n$.
4:     info – int64int32nag_int scalar
info = 0${\mathbf{info}}=0$ unless the function detects an error (see Section [Error Indicators and Warnings]).

## Error Indicators and Warnings

info = i${\mathbf{info}}=-i$
If info = i${\mathbf{info}}=-i$, parameter i$i$ had an illegal value on entry. The parameters are numbered as follows:
1: job, 2: howmny, 3: select, 4: n, 5: t, 6: ldt, 7: vl, 8: ldvl, 9: vr, 10: ldvr, 11: s, 12: sep, 13: mm, 14: m, 15: work, 16: ldwork, 17: iwork, 18: info.
It is possible that info refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.

## Accuracy

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

For a description of canonical Schur form, see the document for nag_lapack_dhseqr (f08pe).
The complex analogue of this function is nag_lapack_ztrsna (f08qy).

## Example

```function nag_lapack_dtrsna_example
job = 'Both';
howmny = 'All';
select = [false];
t = [0.7995, -0.1144, 0.006, 0.0336;
0, -0.0994, 0.2478, 0.3474;
0, -0.6483, -0.0994, 0.2026;
0, 0, 0, -0.1007];
vl = [1, 0, 0, 0;
-0.1101757724599591, 0.8492971136777001, 0, 0;
-0.02369735945664465, 0, 0.5250761453388553, 0;
-0.01052671448401023, -0.2630232022148211, 0.7369767977851788, 1];
vr = [1, 0.06811593844054897, 0.02369735945664464, 0.008112867113990377;
0, 0.6182478862610575, 0, 0.2206494686069181;
0, 0, 1, -1;
0, 0, 0, 0.7124731021612292];
mm = int64(4);
[s, sep, m, info] = nag_lapack_dtrsna(job, howmny, select, t, vl, vr, mm)
```
```

s =

0.9937
0.7028
0.7028
0.5711

sep =

0.6252
0.3743
0.3743
0.3125

m =

4

info =

0

```
```function f08ql_example
job = 'Both';
howmny = 'All';
select = [false];
t = [0.7995, -0.1144, 0.006, 0.0336;
0, -0.0994, 0.2478, 0.3474;
0, -0.6483, -0.0994, 0.2026;
0, 0, 0, -0.1007];
vl = [1, 0, 0, 0;
-0.1101757724599591, 0.8492971136777001, 0, 0;
-0.02369735945664465, 0, 0.5250761453388553, 0;
-0.01052671448401023, -0.2630232022148211, 0.7369767977851788, 1];
vr = [1, 0.06811593844054897, 0.02369735945664464, 0.008112867113990377;
0, 0.6182478862610575, 0, 0.2206494686069181;
0, 0, 1, -1;
0, 0, 0, 0.7124731021612292];
mm = int64(4);
[s, sep, m, info] = f08ql(job, howmny, select, t, vl, vr, mm)
```
```

s =

0.9937
0.7028
0.7028
0.5711

sep =

0.6252
0.3743
0.3743
0.3125

m =

4

info =

0

```