NAG Library Routine Document

F08YTF (ZTGEXC)

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     WANTQ – LOGICALInput

On entry: if $\mathbf{WANTQ}=\mathrm{.TRUE.}$, update the left transformation matrix $Q$.

If $\mathbf{WANTQ}=\mathrm{.FALSE.}$, do not update $Q$.

2:     WANTZ – LOGICALInput

On entry: if $\mathbf{WANTZ}=\mathrm{.TRUE.}$, update the right transformation matrix $Z$.

If $\mathbf{WANTZ}=\mathrm{.FALSE.}$, do not update $Z$.

3:     N – INTEGERInput

On entry: $n$, the order of the matrices $S$ and $T$.

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

4:     A(LDA,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output

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

On entry: the matrix $S$ in the pair $\left(S,T\right)$.

On exit: the updated matrix $\hat{S}$.

5:     LDA – INTEGERInput

On entry: the first dimension of the array A as declared in the (sub)program from which F08YTF (ZTGEXC) is called.

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

6:     B(LDB,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output

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

On entry: the matrix $T$, in the pair $\left(S,T\right)$.

On exit: the updated matrix $\hat{T}$ 

7:     LDB – INTEGERInput

On entry: the first dimension of the array B as declared in the (sub)program from which F08YTF (ZTGEXC) is called.

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

8:     Q(LDQ,$*$) – COMPLEX (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{WANTQ}=\mathrm{.TRUE.}$, and at least $1$ otherwise.

On entry: if $\mathbf{WANTQ}=\mathrm{.TRUE.}$, the unitary matrix $Q$.

On exit: if $\mathbf{WANTQ}=\mathrm{.TRUE.}$, the updated matrix $Q\hat{Q}$.

If $\mathbf{WANTQ}=\mathrm{.FALSE.}$, Q is not referenced.

9:     LDQ – INTEGERInput

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

Constraints:

• if $\mathbf{WANTQ}=\mathrm{.TRUE.}$, $\mathbf{LDQ}\ge \max \left(1,\mathbf{N}\right)$;
• otherwise $\mathbf{LDQ}\ge 1$.

10:   Z(LDZ,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array Z must be at least $\max \left(1,\mathbf{N}\right)$ if $\mathbf{WANTZ}=\mathrm{.TRUE.}$, and at least $1$ otherwise.

On entry: if $\mathbf{WANTZ}=\mathrm{.TRUE.}$, the unitary matrix $Z$.

On exit: if $\mathbf{WANTZ}=\mathrm{.TRUE.}$, the updated matrix $Z\hat{Z}$.

If $\mathbf{WANTZ}=\mathrm{.FALSE.}$, Z is not referenced.

11:   LDZ – INTEGERInput

On entry: the first dimension of the array Z as declared in the (sub)program from which F08YTF (ZTGEXC) is called.

Constraints:

• if $\mathbf{WANTZ}=\mathrm{.TRUE.}$, $\mathbf{LDZ}\ge \max \left(1,\mathbf{N}\right)$;
• otherwise $\mathbf{LDZ}\ge 1$.

12:   IFST – INTEGERInput

13:   ILST – INTEGERInput/Output

On entry: the indices $i_1$ and $i_2$ that specify the reordering of the diagonal elements of $\left(S,T\right)$. The element with row index IFST is moved to row ILST, by a sequence of swapping between adjacent diagonal elements.

On exit: ILST points to the row in its final position.

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

14:   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$

The transformed matrix pair $\left(\hat{S},\hat{T}\right)$ would be too far from generalized Schur form; the problem is ill-conditioned. $\left(S,T\right)$ may have been partially reordered, and ILST points to the first row of the current position of the block being moved.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (f08ytfe.f90)

9.2  Program Data

Program Data (f08ytfe.d)

9.3  Program Results

Program Results (f08ytfe.r)