NAG Library Routine Document

f08qlf  (dtrsna)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:     $\mathbf{job}$ – Character(1)Input

On entry: 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:     $\mathbf{howmny}$ – Character(1)Input

On entry: 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:     $\mathbf{select}\left(*\right)$ – Logical arrayInput

Note: 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.

On entry: 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:     $\mathbf{n}$ – IntegerInput

On entry: $n$, the order of the matrix $T$.

Constraint: $\mathbf{n}\ge 0$.

5:     $\mathbf{t}\left(\mathbf{ldt},*\right)$ – Real (Kind=nag_wp) arrayInput

Note: the second dimension of the array t must be at least $\max \left(1,\mathbf{n}\right)$.

On entry: the $n$ by $n$ upper quasi-triangular matrix $T$ in canonical Schur form, as returned by f08pef (dhseqr).

6:     $\mathbf{ldt}$ – IntegerInput

On entry: the first dimension of the array t as declared in the (sub)program from which f08qlf (dtrsna) is called.

Constraint: $\mathbf{ldt}\ge \max \left(1,\mathbf{n}\right)$.

7:     $\mathbf{vl}\left(\mathbf{ldvl},*\right)$ – Real (Kind=nag_wp) arrayInput

Note: 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'}$.

On entry: 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 f08pkf (dhsein) or f08qkf (dtrevc).

If $\mathbf{job}=\text{'V'}$, vl is not referenced.

8:     $\mathbf{ldvl}$ – IntegerInput

On entry: the first dimension of the array vl as declared in the (sub)program from which f08qlf (dtrsna) is called.

Constraints:

• if $\mathbf{job}=\text{'E'}$ or $\text{'B'}$, $\mathbf{ldvl}\ge \max \left(1,\mathbf{n}\right)$;
• if $\mathbf{job}=\text{'V'}$, $\mathbf{ldvl}\ge 1$.

9:     $\mathbf{vr}\left(\mathbf{ldvr},*\right)$ – Real (Kind=nag_wp) arrayInput

Note: 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'}$.

On entry: 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 f08pkf (dhsein) or f08qkf (dtrevc).

If $\mathbf{job}=\text{'V'}$, vr is not referenced.

10:   $\mathbf{ldvr}$ – IntegerInput

On entry: the first dimension of the array vr as declared in the (sub)program from which f08qlf (dtrsna) is called.

Constraints:

• if $\mathbf{job}=\text{'E'}$ or $\text{'B'}$, $\mathbf{ldvr}\ge \max \left(1,\mathbf{n}\right)$;
• if $\mathbf{job}=\text{'V'}$, $\mathbf{ldvr}\ge 1$.

11:   $\mathbf{s}\left(*\right)$ – Real (Kind=nag_wp) arrayOutput

Note: the dimension of the array s must be at least $\max \left(1,\mathbf{mm}\right)$ if $\mathbf{job}=\text{'E'}$ or $\text{'B'}$, and at least $1$ otherwise.

On exit: 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.

12:   $\mathbf{sep}\left(*\right)$ – Real (Kind=nag_wp) arrayOutput

Note: the dimension of the array sep must be at least $\max \left(1,\mathbf{mm}\right)$ if $\mathbf{job}=\text{'V'}$ or $\text{'B'}$, and at least $1$ otherwise.

On exit: 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)$, $\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.

13:   $\mathbf{mm}$ – IntegerInput

On entry: 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}$.

14:   $\mathbf{m}$ – IntegerOutput

On exit: $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$.

15:   $\mathbf{work}\left(\mathbf{ldwork},*\right)$ – Real (Kind=nag_wp) arrayWorkspace

Note: the second dimension of the array work must be at least $\max \left(1,\mathbf{n}+6\right)$ if $\mathbf{job}=\text{'V'}$ or $\text{'B'}$ and at least $1$ if $\mathbf{job}=\text{'E'}$.

If $\mathbf{job}=\text{'E'}$, work is not referenced.

16:   $\mathbf{ldwork}$ – IntegerInput

On entry: the first dimension of the array work as declared in the (sub)program from which f08qlf (dtrsna) is called.

Constraints:

• if $\mathbf{job}=\text{'V'}$ or $\text{'B'}$, $\mathbf{ldwork}\ge \max \left(1,\mathbf{n}\right)$;
• if $\mathbf{job}=\text{'E'}$, $\mathbf{ldwork}\ge 1$.

17:   $\mathbf{iwork}\left(*\right)$ – Integer arrayWorkspace

Note: the dimension of the array iwork must be at least $\max \left(1,2\times \left(\mathbf{n}-1\right)\right)$.

18:   $\mathbf{info}$ – IntegerOutput

On exit: $\mathbf{info}=0$ unless the routine detects an error (see Section 6).

6

Error Indicators and Warnings

$\mathbf{info}<0$

If $\mathbf{info}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (f08qlfe.f90)

10.2

Program Data

Program Data (f08qlfe.d)

10.3

Program Results

Program Results (f08qlfe.r)