NAG Library Function Document

nag_zgghrd (f08wsc)

void	nag_zgghrd (Nag_OrderType order, Nag_ComputeQType compq, Nag_ComputeZType compz, Integer n, Integer ilo, Integer ihi, Complex a[], Integer pda, Complex b[], Integer pdb, Complex q[], Integer pdq, Complex z[], Integer pdz, NagError *fail)

3 Description

nag_zgghrd (f08wsc) is usually the third step in the solution of the complex generalized eigenvalue problem

A x = λ B x .

The (optional) first step balances the two matrices using nag_zggbal (f08wvc). In the second step, matrix

B

is reduced to upper triangular form using the

Q R

factorization function nag_zgeqrf (f08asc) and this unitary transformation

Q

is applied to matrix

A

by calling nag_zunmqr (f08auc).

nag_zgghrd (f08wsc) reduces a pair of complex matrices

(A, B)

, where

B

is triangular, to the generalized upper Hessenberg form using unitary transformations. This two-sided transformation is of the form

\begin{matrix} Q^{H} A Z = H \\ Q^{H} B Z = T \end{matrix}

where

H

is an upper Hessenberg matrix,

T

is an upper triangular matrix and

Q

and

Z

are unitary matrices determined as products of Givens rotations. They may either be formed explicitly, or they may be postmultiplied into input matrices

Q_{1}

and

Z_{1}

, so that

\begin{matrix} Q_{1} A Z_{1}^{H} = (Q_{1} Q) H {(Z_{1} Z)}^{H}, \\ Q_{1} B Z_{1}^{H} = (Q_{1} Q) T {(Z_{1} Z)}^{H} . \end{matrix}

4 References

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

Moler C B and Stewart G W (1973) An algorithm for generalized matrix eigenproblems SIAM J. Numer. Anal. 10 241–256

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: compq – Nag_ComputeQTypeInput

On entry: specifies the form of the computed unitary matrix

Q

$compq = Nag_NotQ$: Do not compute $Q$ .
$compq = Nag_InitQ$: The unitary matrix $Q$ is returned.
$compq = Nag_UpdateSchur$: q must contain a unitary matrix $Q_{1}$ , and the product $Q_{1} Q$ is returned.

Constraint:

compq = Nag_NotQ

Nag_InitQ

Nag_UpdateSchur

3: compz – Nag_ComputeZTypeInput

On entry: specifies the form of the computed unitary matrix

Z

$compz = Nag_NotZ$: Do not compute $Z$ .
$compz = Nag_InitZ$: The unitary matrix $Z$ is returned.
$compz = Nag_UpdateZ$: z must contain a unitary matrix $Z_{1}$ , and the product $Z_{1} Z$ is returned.

Constraint:

compz = Nag_NotZ

Nag_InitZ

Nag_UpdateZ

4: n – IntegerInput

On entry:

n

, the order of the matrices

A

and

B

Constraint:

n \geq 0

5: ilo – IntegerInput

6: ihi – IntegerInput

On entry:

i_{lo}

and

i_{hi}

as determined by a previous call to nag_zggbal (f08wvc). Otherwise, they should be set to

1

and

n

, respectively.

Constraints:

if $n > 0$ , $1 \leq ilo \leq ihi \leq n$ ;
if $n = 0$ , $ilo = 1$ and $ihi = 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 matrix

A

of the matrix pair

(A, B)

. Usually, this is the matrix

A

returned by nag_zunmqr (f08auc).

On exit: a is overwritten by the upper Hessenberg matrix

H

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 upper triangular matrix

B

of the matrix pair

(A, B)

. Usually, this is the matrix

B

returned by the

Q R

factorization function nag_zgeqrf (f08asc).

On exit: b is overwritten by the upper triangular matrix

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: q[ $\dim$ ] – ComplexInput/Output

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

$\max (1, pdq \times n)$ when $compq = Nag_InitQ$ or $Nag_UpdateSchur$ ;
$1$ when $compq = Nag_NotQ$ .

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

compq = Nag_UpdateSchur

, q must contain a unitary matrix

Q_{1}

compq = Nag_NotQ

, q is not referenced.

On exit: if

compq = Nag_InitQ

, q contains the unitary matrix

Q

Iif

compq = Nag_UpdateSchur

, q is overwritten by

Q_{1} Q

12: pdq – IntegerInput

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

Constraints:

if $compq = Nag_InitQ$ or $Nag_UpdateSchur$ , $pdq \geq \max (1, n)$ ;
if $compq = Nag_NotQ$ , $pdq \geq 1$ .

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

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

$\max (1, pdz \times n)$ when $compz = Nag_InitZ$ or $Nag_UpdateZ$ ;
$1$ when $compz = Nag_NotZ$ .

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

compz = Nag_UpdateZ

, z must contain a unitary matrix

Z_{1}

compz = Nag_NotZ

, z is not referenced.

On exit: if

compz = Nag_InitZ

, z contains the unitary matrix

Z

compz = Nag_UpdateZ

, z is overwritten by

Z_{1} Z

14: pdz – IntegerInput

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

Constraints:

if $compz = Nag_InitZ$ or $Nag_UpdateZ$ , $pdz \geq \max (1, n)$ ;
if $compz = Nag_NotZ$ , $pdz \geq 1$ .

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_ENUM_INT_2: On entry, $compq = 〈value〉$ , $pdq = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $compq = Nag_InitQ$ or $Nag_UpdateSchur$ , $pdq \geq \max (1, n)$ ;
if $compq = Nag_NotQ$ , $pdq \geq 1$ .; On entry, $compz = 〈value〉$ , $pdz = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $compz = Nag_InitZ$ or $Nag_UpdateZ$ , $pdz \geq \max (1, n)$ ;
if $compz = Nag_NotZ$ , $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, $n = 〈value〉$ , $ilo = 〈value〉$ and $ihi = 〈value〉$ .
Constraint: if $n > 0$ , $1 \leq ilo \leq ihi \leq n$ ;
if $n = 0$ , $ilo = 1$ and $ihi = 0$ .
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.