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$ 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_lapack_dtrsna (f08ql) 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_lapack_dtrexc (f08qf) 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 .$

## References

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{job}$ – string (length ≥ 1)
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:     $\mathrm{howmny}$ – string (length ≥ 1)
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:     $\mathrm{select}\left(:\right)$ – logical array
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
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:     $\mathrm{t}\left(\mathit{ldt},:\right)$ – double array
The first dimension of the array t must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array t must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The $n$ by $n$ upper quasi-triangular matrix $T$ in canonical Schur form, as returned by nag_lapack_dhseqr (f08pe).
5:     $\mathrm{vl}\left(\mathit{ldvl},:\right)$ – double array
The first dimension, $\mathit{ldvl}$, of the array vl must satisfy
• if ${\mathbf{job}}=\text{'E'}$ or $\text{'B'}$, $\mathit{ldvl}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{job}}=\text{'V'}$, $\mathit{ldvl}\ge 1$.
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'}$.
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 nag_lapack_dhsein (f08pk) or nag_lapack_dtrevc (f08qk).
If ${\mathbf{job}}=\text{'V'}$, vl is not referenced.
6:     $\mathrm{vr}\left(\mathit{ldvr},:\right)$ – double array
The first dimension, $\mathit{ldvr}$, of the array vr must satisfy
• if ${\mathbf{job}}=\text{'E'}$ or $\text{'B'}$, $\mathit{ldvr}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{job}}=\text{'V'}$, $\mathit{ldvr}\ge 1$.
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'}$.
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 nag_lapack_dhsein (f08pk) or nag_lapack_dtrevc (f08qk).
If ${\mathbf{job}}=\text{'V'}$, vr is not referenced.
7:     $\mathrm{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$, 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}}$.

### Optional Input Parameters

1:     $\mathrm{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$, the order of the matrix $T$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{s}\left(:\right)$ – double array
The dimension of the array s will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ if ${\mathbf{job}}=\text{'E'}$ or $\text{'B'}$ and $1$ otherwise
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.
If ${\mathbf{job}}=\text{'V'}$, s is not referenced.
2:     $\mathrm{sep}\left(:\right)$ – double array
The dimension of the array sep will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ if ${\mathbf{job}}=\text{'V'}$ or $\text{'B'}$ and $1$ otherwise
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.
3:     $\mathrm{m}$int64int32nag_int scalar
$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$.
4:     $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $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 ${\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_lapack_dhseqr (f08pe).
The complex analogue of this function is nag_lapack_ztrsna (f08qy).

## 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 .$
```function f08ql_example

fprintf('f08ql example results\n\n');

% Schur form matrix T
n = int64(4);
t = [0.7995, -0.1144,  0.0060,  0.0336;
0,      -0.0994,  0.2478,  0.3474;
0,      -0.6483, -0.0994,  0.2026;
0,       0,       0,      -0.1007];

% Calculate left and right eigenvectors of T
job = 'Both';
howmny = 'All';
select = [false];
[select, vl, vr, m, info] = ...
f08qk( ...
job, howmny, select, t, zeros(n,n), zeros(n,n), n);

% Estimate condition numbers of eigenvalues and right eigenvectors
[s, sep, m, info] = f08ql( ...
job, howmny, select, t, vl, vr, m);

disp('s');
disp(s');
disp('sep');
disp(sep');
tnorm = norm(t,1);
disp('Approximate error estimates for eigenvalues of T (machine-dependent)');
fprintf('%11.1e',x02aj*tnorm./s);
fprintf('\n\n%s %s\n', 'Approximate error estimates for right', ...
'eigenvectors (machine-dependent)');
fprintf('%11.1e',x02aj*tnorm./sep);
fprintf('\n');

```
```f08ql example results

s
0.9937    0.7028    0.7028    0.5711

sep
0.6252    0.3743    0.3743    0.3125

Approximate error estimates for eigenvalues of T (machine-dependent)
9.6e-17    1.4e-16    1.4e-16    1.7e-16

Approximate error estimates for right eigenvectors (machine-dependent)
1.5e-16    2.6e-16    2.6e-16    3.1e-16
```