NAG Toolbox: nag_lapack_dtrsna (f08ql)

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 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 $\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 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 \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{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 \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{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 $\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). 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 $\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. 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

Further Comments

Example

Open in the MATLAB editor: f08ql_example

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