NAG Toolbox: nag_lapack_ztrsna (f08qy)

Purpose

Syntax

Description

References

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 $\max \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 $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array t must be at least $\max \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 \max \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 $\max \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 \max \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 $\max \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 $\max \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 $\max \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

Further Comments

Example

Open in the MATLAB editor: f08qy_example

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