NAG Library Routine Document

Integer, Intent (In)	::	n, lda, ldb, ldq, ldz, ifst
Integer, Intent (Inout)	::	ilst
Integer, Intent (Out)	::	info
Complex (Kind=nag_wp), Intent (Inout)	::	a(lda,), b(ldb,), q(ldq,), z(ldz,)
Logical, Intent (In)	::	wantq, wantz

C Header Interface

#include <nagmk26.h>

void	f08ytf_ (const logical wantq, const logical wantz, const Integer n, Complex a[], const Integer lda, Complex b[], const Integer ldb, Complex q[], const Integer ldq, Complex z[], const Integer ldz, const Integer ifst, Integer ilst, Integer info)

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

Arguments

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

f08ytf (ztgexc) is not threaded in any implementation.

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 Document

f08ytf (ztgexc)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

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

2

Specification

3

Description

4

References

5

Arguments

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