NAG Library Routine Document

F08QFF (DTREXC)

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     $\mathrm{COMPQ}$ – CHARACTER(1)Input

On entry: indicates whether the matrix $Q$ of Schur vectors is to be updated.

$\mathbf{COMPQ}=\text{'V'}$

The matrix $Q$ of Schur vectors is updated.

$\mathbf{COMPQ}=\text{'N'}$

No Schur vectors are updated.

Constraint: $\mathbf{COMPQ}=\text{'V'}$ or $\text{'N'}$.

2:     $\mathrm{N}$ – INTEGERInput

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

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

3:     $\mathrm{T}\left(\mathbf{LDT},*\right)$ – REAL (KIND=nag_wp) arrayInput/Output

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

On exit: T is overwritten by the updated matrix $\tilde{T}$. See also Section 9.

4:     $\mathrm{LDT}$ – INTEGERInput

On entry: the first dimension of the array T as declared in the (sub)program from which F08QFF (DTREXC) is called.

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

5:     $\mathrm{Q}\left(\mathbf{LDQ},*\right)$ – REAL (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array Q must be at least $\max \left(1,\mathbf{N}\right)$ if $\mathbf{COMPQ}=\text{'V'}$ and at least $1$ if $\mathbf{COMPQ}=\text{'N'}$.

On entry: if $\mathbf{COMPQ}=\text{'V'}$, Q must contain the $n$ by $n$ orthogonal matrix $Q$ of Schur vectors.

On exit: if $\mathbf{COMPQ}=\text{'V'}$, Q contains the updated matrix of Schur vectors.

If $\mathbf{COMPQ}=\text{'N'}$, Q is not referenced.

6:     $\mathrm{LDQ}$ – INTEGERInput

On entry: the first dimension of the array Q as declared in the (sub)program from which F08QFF (DTREXC) is called.

Constraints:

• if $\mathbf{COMPQ}=\text{'V'}$, $\mathbf{LDQ}\ge \max \left(1,\mathbf{N}\right)$;
• if $\mathbf{COMPQ}=\text{'N'}$, $\mathbf{LDQ}\ge 1$.

7:     $\mathrm{IFST}$ – INTEGERInput/Output

8:     $\mathrm{ILST}$ – INTEGERInput/Output

On entry: IFST and ILST must specify the reordering of the diagonal elements or blocks of $T$. The element or block with row index IFST is moved to row ILST by a sequence of exchanges between adjacent elements or blocks.

On exit: if IFST pointed to the second row of a $2$ by $2$ block on entry, it is changed to point to the first row. ILST always points to the first row of the block in its final position (which may differ from its input value by $\pm 1$).

Constraint: $1\le \mathbf{IFST}\le \mathbf{N}$ and $1\le \mathbf{ILST}\le \mathbf{N}$.

9:     $\mathrm{WORK}\left(\mathbf{N}\right)$ – REAL (KIND=nag_wp) arrayWorkspace

10:   $\mathrm{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.

$\mathbf{INFO}=1$

Two adjacent diagonal elements or blocks could not be successfully exchanged. This error can only occur if the exchange involves at least one $2$ by $2$ block; it implies that the problem is very ill-conditioned, and that the eigenvalues of the two blocks are very close. On exit, $T$ may have been partially reordered, and ILST points to the first row of the current position of the block being moved; $Q$ (if requested) is updated consistently with $T$.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f08qffe.f90)

10.2  Program Data

Program Data (f08qffe.d)

10.3  Program Results

Program Results (f08qffe.r)