NAG Library Function Document

nag_ztgexc (f08ytc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

+− 9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

1 Purpose

nag_ztgexc (f08ytc) reorders the generalized Schur factorization of a complex matrix pair in generalized Schur form.

2 Specification

#include <nag.h>

#include <nagf08.h>

void	nag_ztgexc (Nag_OrderType order, Nag_Boolean wantq, Nag_Boolean wantz, Integer n, Complex a[], Integer pda, Complex b[], Integer pdb, Complex q[], Integer pdq, Complex z[], Integer pdz, Integer ifst, Integer ilst, NagError fail)

3 Description

nag_ztgexc (f08ytc) 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 nag_zgges (f08xnc), or nag_zhgeqz (f08xsc) with

job = Nag_Schur

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: order – Nag_OrderTypeInput

On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by

order = Nag_RowMajor

. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

or Nag_ColMajor.

2: wantq – Nag_BooleanInput

On entry: if

wantq = Nag_TRUE

, update the left transformation matrix

Q

wantq = Nag_FALSE

, do not update

Q

3: wantz – Nag_BooleanInput

On entry: if

wantz = Nag_TRUE

, update the right transformation matrix

Z

wantz = Nag_FALSE

, do not update

Z

4: n – IntegerInput

On entry:

n

, the order of the matrices

S

and

T

Constraint:

n \geq 0

5: a[ $\dim$ ] – ComplexInput/Output

Note: the dimension, dim, of the array a must be at least

\max (1, pda \times n)

The

(i, j)

th element of the matrix

A

is stored in

$a [(j - 1) \times pda + i - 1]$ when $order = Nag_ColMajor$ ;
$a [(i - 1) \times pda + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the matrix

S

in the pair

(S, T)

On exit: the updated matrix

\hat{S}

6: pda – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array a.

Constraint:

pda \geq \max (1, n)

7: b[ $\dim$ ] – ComplexInput/Output

Note: the dimension, dim, of the array b must be at least

\max (1, pdb \times n)

The

(i, j)

th element of the matrix

B

is stored in

$b [(j - 1) \times pdb + i - 1]$ when $order = Nag_ColMajor$ ;
$b [(i - 1) \times pdb + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the matrix

T

, in the pair

(S, T)

On exit: the updated matrix

\hat{T}

8: pdb – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array b.

Constraint:

pdb \geq \max (1, n)

9: q[ $\dim$ ] – ComplexInput/Output

Note: the dimension, dim, of the array q must be at least

$\max (1, pdq \times n)$ when $wantq = Nag_TRUE$ ;
$1$ otherwise.

The

(i, j)

th element of the matrix

Q

is stored in

$q [(j - 1) \times pdq + i - 1]$ when $order = Nag_ColMajor$ ;
$q [(i - 1) \times pdq + j - 1]$ when $order = Nag_RowMajor$ .

On entry: if

wantq = Nag_TRUE

, the unitary matrix

Q

On exit: if

wantq = Nag_TRUE

, the updated matrix

Q \hat{Q}

wantq = Nag_FALSE

, q is not referenced.

10: pdq – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array q.

Constraints:

if $wantq = Nag_TRUE$ , $pdq \geq \max (1, n)$ ;
otherwise $pdq \geq 1$ .

11: z[ $\dim$ ] – ComplexInput/Output

Note: the dimension, dim, of the array z must be at least

$\max (1, pdz \times n)$ when $wantz = Nag_TRUE$ ;
$1$ otherwise.

The

(i, j)

th element of the matrix

Z

is stored in

$z [(j - 1) \times pdz + i - 1]$ when $order = Nag_ColMajor$ ;
$z [(i - 1) \times pdz + j - 1]$ when $order = Nag_RowMajor$ .

On entry: if

wantz = Nag_TRUE

, the unitary matrix

Z

On exit: if

wantz = Nag_TRUE

, the updated matrix

Z \hat{Z}

wantz = Nag_FALSE

, z is not referenced.

12: pdz – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array z.

Constraints:

if $wantz = Nag_TRUE$ , $pdz \geq \max (1, n)$ ;
otherwise $pdz \geq 1$ .

13: ifst – IntegerInput

14: ilst – Integer *Input/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

15: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument $〈value〉$ had an illegal value.
NE_CONSTRAINT: On entry, $wantq = 〈value〉$ , $pdq = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $wantq = Nag_TRUE$ , $pdq \geq \max (1, n)$ ;
otherwise $pdq \geq 1$ .; On entry, $wantz = 〈value〉$ , $pdz = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $wantz = Nag_TRUE$ , $pdz \geq \max (1, n)$ ;
otherwise $pdz \geq 1$ .
NE_INT: On entry, $n = 〈value〉$ .
Constraint: $n \geq 0$ .; On entry, $pda = 〈value〉$ .
Constraint: $pda > 0$ .; On entry, $pdb = 〈value〉$ .
Constraint: $pdb > 0$ .; On entry, $pdq = 〈value〉$ .
Constraint: $pdq > 0$ .; On entry, $pdz = 〈value〉$ .
Constraint: $pdz > 0$ .
NE_INT_2: On entry, $pda = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pda \geq \max (1, n)$ .; On entry, $pdb = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdb \geq \max (1, n)$ .
NE_INT_3: On entry, $ifst = 〈value〉$ , $ilst = 〈value〉$ and $n = 〈value〉$ .
Constraint: $1 \leq ifst \leq n$ and $1 \leq ilst \leq n$ .
NE_INTERNAL_ERROR: An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_SCHUR: 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 Further Comments

The real analogue of this function is nag_dtgexc (f08yfc).

9 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 Function Documentnag_ztgexc (f08ytc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_ztgexc (f08ytc)