NAG Library Routine Document

F08QLF (DTRSNA)

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     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:     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:     SELECT($*$) – 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:     N – INTEGERInput

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

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

5:     T(LDT,$*$) – 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:     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:     VL(LDVL,$*$) – 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:     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:     VR(LDVR,$*$) – 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:   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:   S($*$) – 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$ if $\mathbf{JOB}=\text{'V'}$.

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.

S is not referenced if $\mathbf{JOB}=\text{'V'}$.

12:   SEP($*$) – 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$ if $\mathbf{JOB}=\text{'E'}$.

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)$, 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.

13:   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:   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:   WORK(LDWORK,$*$) – 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:   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:   IWORK($*$) – 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:   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  Further Comments

9  Example

9.1  Program Text

Program Text (f08qlfe.f90)

9.2  Program Data

Program Data (f08qlfe.d)

9.3  Program Results

Program Results (f08qlfe.r)