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

PDF version (NAG web site, 64-bit version, 64-bit version)
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$. 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.
nag_lapack_ztrsna (f08qy) 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_ztrexc (f08qt) 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 .$

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 eigenvalue ${\lambda }_{j}$, ${\mathbf{select}}\left(j\right)$ must be set to true.
If ${\mathbf{howmny}}=\text{'A'}$, select is not referenced.
4:     $\mathrm{t}\left(\mathit{ldt},:\right)$ – complex 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 triangular matrix $T$, as returned by nag_lapack_zhseqr (f08ps).
5:     $\mathrm{vl}\left(\mathit{ldvl},:\right)$ – complex 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{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 nag_lapack_zhsein (f08px) or nag_lapack_ztrevc (f08qx).
If ${\mathbf{job}}=\text{'V'}$, vl is not referenced.
6:     $\mathrm{vr}\left(\mathit{ldvr},:\right)$ – complex 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{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 nag_lapack_zhsein (f08px) or nag_lapack_ztrevc (f08qx).
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, $\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$.
Constraints:
• if ${\mathbf{howmny}}=\text{'A'}$, ${\mathbf{mm}}\ge {\mathbf{n}}$;
• otherwise ${\mathbf{mm}}\ge \mathit{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).
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.
If ${\mathbf{job}}=\text{'E'}$, sep is not referenced.
3:     $\mathrm{m}$int64int32nag_int scalar
$\mathit{m}$, the number of selected eigenpairs. 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: 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 ${\mathit{sep}}_{i}$ may over estimate the true value, but seldom by a factor of more than $3$.

Further Comments

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

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

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

% Matrix in complex Schur form
n = int64(4);
T = [-6.0004 - 6.9999i, 0.3637 - 0.3656i, -0.1880 + 0.4787i, 0.8785 - 0.2539i;
0      + 0i,     -5.0000 + 2.0060i, -0.0307 - 0.7217i,-0.2290 + 0.1313i;
0      + 0i,      0      + 0i,       7.9982 - 0.9964i, 0.9357 + 0.5359i;
0      + 0i,      0      + 0i,       0      + 0i,      3.0023 - 3.9998i];

% Calculate the eigenvectors of T
select = [false];
vl = complex(zeros(n,n));
vr = complex(zeros(n,n));
job = 'Both';
howmny = 'All';

[T, vl, vr, m, info] = ...
f08qx( ...
job, howmny, select, T, vl, vr, n);

[s, sep, m, info] = ...
f08qy( ...
job, howmny, select, T, vl, vr, n);
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');

```
```f08qy example results

s:
0.9932    0.9964    0.9814    0.9779

sep:
8.4012    8.0215    5.8292    5.8292

Approximate error estimates for eigenvalues of T (machine-dependent)
1.0e-15    1.0e-15    1.1e-15    1.1e-15

Approximate error estimates for right eigenvectors (machine-dependent)
1.2e-16    1.3e-16    1.8e-16    1.8e-16
```

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015