NAG Library Function Document

nag_zgges (f08xnc)

Integer n, Complex a[], Integer pda, Complex b[], Integer pdb, Integer *sdim, Complex alpha[], Complex beta[], Complex vsl[], Integer pdvsl, Complex vsr[], Integer pdvsr, NagError *fail)

3 Description

The generalized Schur factorization for a pair of complex matrices

(A, B)

is given by

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

where

Q

and

Z

are unitary,

T

and

S

are upper triangular. The generalized eigenvalues,

λ

, of

(A, B)

are computed from the diagonals of

T

and

S

and satisfy

A z = λ B z,

where

z

is the corresponding generalized eigenvector.

λ

is actually returned as the pair

(α, β)

such that

λ = α / β

since

β

, or even both

α

and

β

can be zero. The columns of

Q

and

Z

are the left and right generalized Schur vectors of

(A, B)

Optionally, nag_zgges (f08xnc) can order the generalized eigenvalues on the diagonals of

(S, T)

so that selected eigenvalues are at the top left. The leading columns of

Q

and

Z

then form an orthonormal basis for the corresponding eigenspaces, the deflating subspaces.

nag_zgges (f08xnc) computes

T

to have real non-negative diagonal entries. The generalized Schur factorization, before reordering, is computed by the

Q Z

algorithm.

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

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

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: jobvsl – Nag_LeftVecsTypeInput

On entry: if

jobvsl = Nag_NotLeftVecs

, do not compute the left Schur vectors.

jobvsl = Nag_LeftVecs

, compute the left Schur vectors.

Constraint:

jobvsl = Nag_NotLeftVecs

Nag_LeftVecs

3: jobvsr – Nag_RightVecsTypeInput

On entry: if

jobvsr = Nag_NotRightVecs

, do not compute the right Schur vectors.

jobvsr = Nag_RightVecs

, compute the right Schur vectors.

Constraint:

jobvsr = Nag_NotRightVecs

Nag_RightVecs

4: sort – Nag_SortEigValsTypeInput

On entry: specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.

$sort = Nag_NoSortEigVals$: Eigenvalues are not ordered.
$sort = Nag_SortEigVals$: Eigenvalues are ordered (see selctg).

Constraint:

sort = Nag_NoSortEigVals

Nag_SortEigVals

5: selctg – function, supplied by the userExternal Function

sort = Nag_SortEigVals

, selctg is used to select generalized eigenvalues to the top left of the generalized Schur form.

sort = Nag_NoSortEigVals

, selctg is not referenced by nag_zgges (f08xnc), and may be specified as NULLFN.

The specification of selctg is:

Nag_Boolean

selctg (Complex a, Complex b)

1: a – ComplexInput
2: b – ComplexInput: On entry: an eigenvalue $a [j - 1] / b [j - 1]$ is selected if $selctg (a [j - 1], b [j - 1])$ is Nag_TRUE.
Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy $selctg (a [j - 1], b [j - 1]) = Nag_TRUE$ after ordering. $fail . code =$ NE_SCHUR_REORDER_SELECT in this case.

6: n – IntegerInput

On entry:

n

, the order of the matrices

A

and

B

Constraint:

n \geq 0

7: 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 first of the pair of matrices,

A

On exit: a has been overwritten by its generalized Schur form

S

8: 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)

9: 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 second of the pair of matrices,

B

On exit: b has been overwritten by its generalized Schur form

T

10: 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)

11: sdim – Integer *Output

On exit: if

sort = Nag_NoSortEigVals

sdim = 0

sort = Nag_SortEigVals

sdim =

number of eigenvalues (after sorting) for which selctg is Nag_TRUE.

12: alpha[n] – ComplexOutput

On exit: see the description of beta.

13: beta[n] – ComplexOutput

On exit:

alpha [j - 1] / beta [j - 1]

, for

j = 1, 2, \dots, n

, will be the generalized eigenvalues.

alpha [j - 1]

, for

j = 1, 2, \dots, n

and

beta [j - 1]

, for

j = 1, 2, \dots, n

, are the diagonals of the complex Schur form

(A, B)

output by nag_zgges (f08xnc). The

beta [j - 1]

will be non-negative real.

Note: the quotients

alpha [j - 1] / beta [j - 1]

may easily overflow or underflow, and

beta [j - 1]

may even be zero. Thus, you should avoid naively computing the ratio

α / β

. However, alpha will always be less than and usually comparable with

‖a‖

in magnitude, and beta will always be less than and usually comparable with

‖b‖

14: vsl[ $\dim$ ] – ComplexOutput

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

$\max (1, pdvsl \times n)$ when $jobvsl = Nag_LeftVecs$ ;
$1$ otherwise.

The

(i, j)

th element of the matrix is stored in

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

On exit: if

jobvsl = Nag_LeftVecs

, vsl will contain the left Schur vectors,

Q

jobvsl = Nag_NotLeftVecs

, vsl is not referenced.

15: pdvsl – IntegerInput

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

Constraints:

if $jobvsl = Nag_LeftVecs$ , $pdvsl \geq \max (1, n)$ ;
otherwise $pdvsl \geq 1$ .

16: vsr[ $\dim$ ] – ComplexOutput

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

$\max (1, pdvsr \times n)$ when $jobvsr = Nag_RightVecs$ ;
$1$ otherwise.

The

(i, j)

th element of the matrix is stored in

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

On exit: if

jobvsr = Nag_RightVecs

, vsr will contain the right Schur vectors,

Z

jobvsr = Nag_NotRightVecs

, vsr is not referenced.

17: pdvsr – IntegerInput

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

Constraints:

if $jobvsr = Nag_RightVecs$ , $pdvsr \geq \max (1, n)$ ;
otherwise $pdvsr \geq 1$ .

18: 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_ENUM_INT_2: On entry, $jobvsl = 〈value〉$ , $pdvsl = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $jobvsl = Nag_LeftVecs$ , $pdvsl \geq \max (1, n)$ ;
otherwise $pdvsl \geq 1$ .; On entry, $jobvsr = 〈value〉$ , $pdvsr = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $jobvsr = Nag_RightVecs$ , $pdvsr \geq \max (1, n)$ ;
otherwise $pdvsr \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, $pdvsl = 〈value〉$ .
Constraint: $pdvsl > 0$ .; On entry, $pdvsr = 〈value〉$ .
Constraint: $pdvsr > 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_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_ITERATION_QZ: The $Q Z$ iteration did not converge and the matrix pair $(A, B)$ is not in the generalized Schur form. The computed $α_{i}$ and $β_{i}$ should be correct for $i = 〈value〉, \dots, 〈value〉$ .; The $Q Z$ iteration failed with an unexpected error, please contact NAG.
NE_SCHUR_REORDER: The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).
NE_SCHUR_REORDER_SELECT: After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy $selctg = Nag_TRUE$ . This could also be caused by underflow due to scaling.

7 Accuracy

The computed generalized Schur factorization satisfies

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

where

{‖(E, F)‖}_{F} = O (ε) {‖(A, B)‖}_{F}

and

ε

is the machine precision. See Section 4.11 of Anderson et al. (1999) for further details.

8 Further Comments

The total number of floating point operations is proportional to

n^{3}

The real analogue of this function is nag_dgges (f08xac).

9 Example

This example finds the generalized Schur factorization of the matrix pair

(A, B)

, where

A = (\begin{array}{r} - 21.10 - 22.50 i & 53.50 - 50.50 i & - 34.50 + 127.50 i & 7.50 + 0.50 i \\ - 0.46 - 7.78 i & - 3.50 - 37.50 i & - 15.50 + 58.50 i & - 10.50 - 1.50 i \\ 4.30 - 5.50 i & 39.70 - 17.10 i & - 68.50 + 12.50 i & - 7.50 - 3.50 i \\ 5.50 + 4.40 i & 14.40 + 43.30 i & - 32.50 - 46.00 i & - 19.00 - 32.50 i \end{array})

and

B = (\begin{array}{r} 1.00 - 5.00 i & 1.60 + 1.20 i & - 3.00 + 0.00 i & 0.00 - 1.00 i \\ 0.80 - 0.60 i & 3.00 - 5.00 i & - 4.00 + 3.00 i & - 2.40 - 3.20 i \\ 1.00 + 0.00 i & 2.40 + 1.80 i & - 4.00 - 5.00 i & 0.00 - 3.00 i \\ 0.00 + 1.00 i & - 1.80 + 2.40 i & 0.00 - 4.00 i & 4.00 - 5.00 i \end{array}) .

NAG Library Function Documentnag_zgges (f08xnc)

+− 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_zgges (f08xnc)