NAG Library Routine Document

F08YTF (ZTGEXC)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

▸▿ 10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1 Purpose

F08YTF (ZTGEXC) reorders the generalized Schur factorization of a complex matrix pair in generalized Schur form.

2 Specification

SUBROUTINE F08YTF (

WANTQ, WANTZ, N, A, LDA, B, LDB, Q, LDQ, Z, LDZ, IFST, ILST, INFO)

INTEGER	N, LDA, LDB, LDQ, LDZ, IFST, ILST, INFO
COMPLEX (KIND=nag_wp)	A(LDA,), B(LDB,), Q(LDQ,), Z(LDZ,)
LOGICAL	WANTQ, WANTZ

The routine may be called by its LAPACK name ztgexc.

3 Description

F08YTF (ZTGEXC) reorders the generalized complex

n

n

matrix pair

(S, T)

in generalized Schur form, so that the diagonal element of

(S, T)

with row index

i_{1}

is moved to row

i_{2}

, using a unitary equivalence transformation. That is,

S

and

T

are factorized as

S = \hat{Q} \hat{S} {\hat{Z}}^{H}, T = \hat{Q} \hat{T} {\hat{Z}}^{H},

where

(\hat{S}, \hat{T})

are also in generalized Schur form.

The pair

(S, T)

are in generalized Schur form if

S

and

T

are upper triangular as returned, for example, by F08XNF (ZGGES), or F08XSF (ZHGEQZ) with

JOB ='S'

S

and

T

are the result of a generalized Schur factorization of a matrix pair

(A, B)

A = Q S Z^{H}, B = Q T Z^{H}

then, optionally, the matrices

Q

and

Z

can be updated as

Q \hat{Q}

and

Z \hat{Z}

4 References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug

5 Parameters

1: $WANTQ$ – LOGICALInput

On entry: if

WANTQ = .TRUE.

, update the left transformation matrix

Q

WANTQ = .FALSE.

, do not update

Q

2: $WANTZ$ – LOGICALInput

On entry: if

WANTZ = .TRUE.

, update the right transformation matrix

Z

WANTZ = .FALSE.

, do not update

Z

3: $N$ – INTEGERInput

On entry:

n

, the order of the matrices

S

and

T

Constraint:

N \geq 0

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

Note: the second dimension of the array A must be at least

\max (1, N)

On entry: the matrix

S

in the pair

(S, T)

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:

LDA \geq \max (1, N)

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

Note: the second dimension of the array B must be at least

\max (1, N)

On entry: the matrix

T

, in the pair

(S, T)

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:

LDB \geq \max (1, N)

8: $Q (LDQ *)$ – COMPLEX (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array Q must be at least

\max (1, N)

WANTQ = .TRUE.

, and at least

1

otherwise.

On entry: if

WANTQ = .TRUE.

, the unitary matrix

Q

On exit: if

WANTQ = .TRUE.

, the updated matrix

Q \hat{Q}

WANTQ = .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 $WANTQ = .TRUE.$ , $LDQ \geq \max (1, N)$ ;
otherwise $LDQ \geq 1$ .

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

Note: the second dimension of the array Z must be at least

\max (1, N)

WANTZ = .TRUE.

, and at least

1

otherwise.

On entry: if

WANTZ = .TRUE.

, the unitary matrix

Z

On exit: if

WANTZ = .TRUE.

, the updated matrix

Z \hat{Z}

WANTZ = .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 $WANTZ = .TRUE.$ , $LDZ \geq \max (1, N)$ ;
otherwise $LDZ \geq 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

(S, T)

. 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 \leq IFST \leq N

and

1 \leq ILST \leq N

14: $INFO$ – INTEGEROutput

On exit:

INFO = 0

unless the routine detects an error (see Section 6).

6 Error Indicators and Warnings

$INFO < 0$: If $INFO = - i$ , argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.

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

7 Accuracy

The computed generalized Schur form is nearly the exact generalized Schur form for nearby matrices

(S + E)

and

(T + F)

, where

{‖E‖}_{2} = O ε {‖S‖}_{2} and {‖F‖}_{2} = O ε {‖T‖}_{2},

and

ε

is the machine precision. See Section 4.11 of Anderson et al. (1999) for further details of error bounds for the generalized nonsymmetric eigenproblem.

8 Parallelism and Performance

Not applicable.

9 Further Comments

The real analogue of this routine is F08YFF (DTGEXC).

10 Example

This example exchanges rows 4 and 1 of the matrix pair

(S, T)

, where

S = (\begin{array}{r} 4.0 + 4.0 i & 1.0 + 1.0 i & 1.0 + 1.0 i & 2.0 - 1.0 i \\ 0 & 2.0 + 1.0 i & 1.0 + 1.0 i & 1.0 + 1.0 i \\ 0 & 0 & 2.0 - 1.0 i & 1.0 + 1.0 i \\ 0 & 0 & 0 & 6.0 - 2.0 i \end{array})

and

T = (\begin{array}{r} 2.0 & 1.0 + 1.0 i & 1.0 + 1.0 i & 3.0 - 1.0 i \\ 0 & 1.0 & 2.0 + 1.0 i & 1.0 + 1.0 i \\ 0 & 0 & 1.0 & 1.0 + 1.0 i \\ 0 & 0 & 0 & 2.0 \end{array}) .

NAG Library Routine DocumentF08YTF (ZTGEXC)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG Library Routine Document

F08YTF (ZTGEXC)