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_ztrsna (f08qy)

## Purpose

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

## Syntax

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

## Description

nag_lapack_ztrsna (f08qy) estimates condition numbers for specified eigenvalues and/or right eigenvectors of a complex upper triangular matrix T$T$. These are the same as the condition numbers of the eigenvalues and right eigenvectors of an original matrix A = ZTZH$A=ZT{Z}^{\mathrm{H}}$ (with unitary Z$Z$), from which T$T$ may have been derived.
nag_lapack_ztrsna (f08qy) 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_ztrexc (f08qt) to reorder the eigenvalues so that λi${\lambda }_{i}$ is in the leading position:
T = Q
 ( λi cH ) 0 T22
QH.
$T =Q λi cH 0 T22 QH.$
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 eigenvalue λj${\lambda }_{j}$, select(j)${\mathbf{select}}\left(j\right)$ must be set to true.
If howmny = 'A'${\mathbf{howmny}}=\text{'A'}$, select is not referenced.
4:     t(ldt, : $:$) – complex 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 triangular matrix T$T$, as returned by nag_lapack_zhseqr (f08ps).
5:     vl(ldvl, : $:$) – complex 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 QTQH$QT{Q}^{\mathrm{H}}$ with Q$Q$ unitary) corresponding to the eigenpairs specified by howmny and select. The eigenvectors must be stored in consecutive columns of vl, as returned by nag_lapack_zhsein (f08px) or nag_lapack_ztrevc (f08qx).
If job = 'V'${\mathbf{job}}=\text{'V'}$, vl is not referenced.
6:     vr(ldvr, : $:$) – complex 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 QTQH$QT{Q}^{\mathrm{H}}$ with Q$Q$ unitary) corresponding to the eigenpairs specified by howmny and select. The eigenvectors must be stored in consecutive columns of vr, as returned by nag_lapack_zhsein (f08px) or nag_lapack_ztrevc (f08qx).
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$\mathit{m}$, is n$n$ if howmny = 'A'${\mathbf{howmny}}=\text{'A'}$; if howmny = 'S'${\mathbf{howmny}}=\text{'S'}$, m$\mathit{m}$ is the number of selected eigenpairs (see select), in which case 0mn$0\le \mathit{m}\le n$.
Constraint: mmm${\mathbf{mm}}\ge \mathit{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 rwork

### 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).
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.
If job = 'E'${\mathbf{job}}=\text{'E'}$, sep is not referenced i.
3:     m – int64int32nag_int scalar
m$\mathit{m}$, the number of selected eigenpairs. 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: rwork, 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$.

The real analogue of this function is nag_lapack_dtrsna (f08ql).

## Example

```function nag_lapack_ztrsna_example
job = 'Both';
howmny = 'All';
select = [false];
t = [ -6.0004 - 6.9999i,  0.3637 - 0.3656i, ...
-0.188 + 0.4787i,  0.8785 - 0.2539i;
0 + 0i,  -5 + 2.006i,  -0.0307 - 0.7217i,  -0.229 + 0.1313i;
0 + 0i,  0 + 0i,  7.9982 - 0.9964i,  0.9357 + 0.5359i;
0 + 0i,  0 + 0i,  0 + 0i,  3.0023 - 3.9998i];
vl = [complex(1),  0 + 0i,  0 + 0i,  0 + 0i;
0.03566943515948521 - 0.04434689513913646i,  1 + 0i,  0 + 0i,  0 + 0i;
-0.002207376074206878 + 0.03131341253433394i, ...
-0.009933197113414047 - 0.05322864465746685i,  1 + 0i,  0 + 0i;
-0.07824388063236407 - 0.05827078558456029i, ...
0.03187495330451339 - 0.001955906687244087i,  0.1849408889864736 + 0.0039135022682549i,  1 + 0i];
vr = [1,  -0.03566943515948521 - 0.04434689513913646i, ...
-0.0005074605791794694 + 0.03277154177278579i,  0.0792597025312869 - 0.06285024830308554i;
0 + 0i,  1 + 0i,  0.009933197113414047 - 0.05322864465746685i, ...
-0.03350369718754292 + 0.00792711976468731i;
0 + 0i,  0 + 0i,  1 + 0i,  -0.1849408889864736 + 0.0039135022682549i;
0 + 0i,  0 + 0i,  0 + 0i,  1 + 0i];
mm = int64(4);
[s, sep, m, info] = nag_lapack_ztrsna(job, howmny, select, t, vl, vr, mm)
```
```

s =

0.9932
0.9964
0.9814
0.9779

sep =

8.4012
8.0215
5.8292
5.8292

m =

4

info =

0

```
```function f08qy_example
job = 'Both';
howmny = 'All';
select = [false];
t = [ -6.0004 - 6.9999i,  0.3637 - 0.3656i, ...
-0.188 + 0.4787i,  0.8785 - 0.2539i;
0 + 0i,  -5 + 2.006i,  -0.0307 - 0.7217i,  -0.229 + 0.1313i;
0 + 0i,  0 + 0i,  7.9982 - 0.9964i,  0.9357 + 0.5359i;
0 + 0i,  0 + 0i,  0 + 0i,  3.0023 - 3.9998i];
vl = [complex(1),  0 + 0i,  0 + 0i,  0 + 0i;
0.03566943515948521 - 0.04434689513913646i,  1 + 0i,  0 + 0i,  0 + 0i;
-0.002207376074206878 + 0.03131341253433394i, ...
-0.009933197113414047 - 0.05322864465746685i,  1 + 0i,  0 + 0i;
-0.07824388063236407 - 0.05827078558456029i, ...
0.03187495330451339 - 0.001955906687244087i,  0.1849408889864736 + 0.0039135022682549i, ...
1 + 0i];
vr = [1,  -0.03566943515948521 - 0.04434689513913646i, ...
-0.0005074605791794694 + 0.03277154177278579i,  0.0792597025312869 - 0.06285024830308554i; ...

0 + 0i,  1 + 0i,  0.009933197113414047 - 0.05322864465746685i, ...
-0.03350369718754292 + 0.00792711976468731i;
0 + 0i,  0 + 0i,  1 + 0i,  -0.1849408889864736 + 0.0039135022682549i;
0 + 0i,  0 + 0i,  0 + 0i,  1 + 0i];
mm = int64(4);
[s, sep, m, info] = f08qy(job, howmny, select, t, vl, vr, mm)
```
```

s =

0.9932
0.9964
0.9814
0.9779

sep =

8.4012
8.0215
5.8292
5.8292

m =

4

info =

0

```