NAG Library Function Document

nag_zunmhr (f08nuc)

void	nag_zunmhr (Nag_OrderType order, Nag_SideType side, Nag_TransType trans, Integer m, Integer n, Integer ilo, Integer ihi, const Complex a[], Integer pda, const Complex tau[], Complex c[], Integer pdc, NagError *fail)

3 Description

nag_zunmhr (f08nuc) is intended to be used following a call to nag_zgehrd (f08nsc), which reduces a complex general matrix

A

to upper Hessenberg form

H

by a unitary similarity transformation:

A = Q H Q^{H}

. nag_zgehrd (f08nsc) represents the matrix

Q

as a product of

i_{hi} - i_{lo}

elementary reflectors. Here

i_{lo}

and

i_{hi}

are values determined by nag_zgebal (f08nvc) when balancing the matrix; if the matrix has not been balanced,

i_{lo} = 1

and

i_{hi} = n

This function may be used to form one of the matrix products

Q C, Q^{H} C, C Q ​ or ​ C Q^{H},

overwriting the result on

C

(which may be any complex rectangular matrix).

A common application of this function is to transform a matrix

V

of eigenvectors of

H

to the matrix

QV

of eigenvectors of

A

4 References

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: side – Nag_SideTypeInput

On entry: indicates how

Q

Q^{H}

is to be applied to

C

$side = Nag_LeftSide$: $Q$ or $Q^{H}$ is applied to $C$ from the left.
$side = Nag_RightSide$: $Q$ or $Q^{H}$ is applied to $C$ from the right.

Constraint:

side = Nag_LeftSide

Nag_RightSide

3: trans – Nag_TransTypeInput

On entry: indicates whether

Q

Q^{H}

is to be applied to

C

$trans = Nag_NoTrans$: $Q$ is applied to $C$ .
$trans = Nag_ConjTrans$: $Q^{H}$ is applied to $C$ .

Constraint:

trans = Nag_NoTrans

Nag_ConjTrans

4: m – IntegerInput

On entry:

m

, the number of rows of the matrix

C

;

m

is also the order of

Q

side = Nag_LeftSide

Constraint:

m \geq 0

5: n – IntegerInput

On entry:

n

, the number of columns of the matrix

C

;

n

is also the order of

Q

side = Nag_RightSide

Constraint:

n \geq 0

6: ilo – IntegerInput

7: ihi – IntegerInput

On entry: these must be the same arguments ilo and ihi, respectively, as supplied to nag_zgehrd (f08nsc).

Constraints:

if $side = Nag_LeftSide$ and $m > 0$ , $1 \leq ilo \leq ihi \leq m$ ;
if $side = Nag_LeftSide$ and $m = 0$ , $ilo = 1$ and $ihi = 0$ ;
if $side = Nag_RightSide$ and $n > 0$ , $1 \leq ilo \leq ihi \leq n$ ;
if $side = Nag_RightSide$ and $n = 0$ , $ilo = 1$ and $ihi = 0$ .

8: a[ $\dim$ ] – const ComplexInput

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

$\max (1, pda \times m)$ when $side = Nag_LeftSide$ ;
$\max (1, pda \times n)$ when $side = Nag_RightSide$ .

On entry: details of the vectors which define the elementary reflectors, as returned by nag_zgehrd (f08nsc).

9: pda – IntegerInput

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

Constraints:

if $side = Nag_LeftSide$ , $pda \geq \max (1, m)$ ;
if $side = Nag_RightSide$ , $pda \geq \max (1, n)$ .

10: tau[ $\dim$ ] – const ComplexInput

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

$\max (1, m - 1)$ when $side = Nag_LeftSide$ ;
$\max (1, n - 1)$ when $side = Nag_RightSide$ .

On entry: further details of the elementary reflectors, as returned by nag_zgehrd (f08nsc).

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

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

$\max (1, pdc \times n)$ when $order = Nag_ColMajor$ ;
$\max (1, m \times pdc)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

C

is stored in

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

On entry: the

m

n

matrix

C

On exit: c is overwritten by

Q C

Q^{H} C

C Q

C Q^{H}

as specified by side and trans.

12: pdc – IntegerInput

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

Constraints:

if $order = Nag_ColMajor$ , $pdc \geq \max (1, m)$ ;
if $order = Nag_RowMajor$ , $pdc \geq \max (1, n)$ .

13: 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_3: On entry, $side = 〈value〉$ , $m = 〈value〉$ , $n = 〈value〉$ and $pda = 〈value〉$ .
Constraint: if $side = Nag_LeftSide$ , $pda \geq \max (1, m)$ ;
if $side = Nag_RightSide$ , $pda \geq \max (1, n)$ .; On entry, $side = 〈value〉$ , $pda = 〈value〉$ , $m = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $side = Nag_LeftSide$ , $pda \geq \max (1, m)$ ;
if $side = Nag_RightSide$ , $pda \geq \max (1, n)$ .
NE_ENUM_INT_4: On entry, $side = 〈value〉$ , $m = 〈value〉$ , $n = 〈value〉$ , $ilo = 〈value〉$ and $ihi = 〈value〉$ .
Constraint: if $side = Nag_LeftSide$ and $m > 0$ , $1 \leq ilo \leq ihi \leq m$ ;
if $side = Nag_LeftSide$ and $m = 0$ , $ilo = 1$ and $ihi = 0$ ;
if $side = Nag_RightSide$ and $n > 0$ , $1 \leq ilo \leq ihi \leq n$ ;
if $side = Nag_RightSide$ and $n = 0$ , $ilo = 1$ and $ihi = 0$ .
NE_INT: On entry, $m = 〈value〉$ .
Constraint: $m \geq 0$ .; On entry, $n = 〈value〉$ .
Constraint: $n \geq 0$ .; On entry, $pda = 〈value〉$ .
Constraint: $pda > 0$ .; On entry, $pdc = 〈value〉$ .
Constraint: $pdc > 0$ .
NE_INT_2: On entry, $pdc = 〈value〉$ and $m = 〈value〉$ .
Constraint: $pdc \geq \max (1, m)$ .; On entry, $pdc = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdc \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.

7 Accuracy

The computed result differs from the exact result by a matrix

E

such that

{‖E‖}_{2} = O (ε) {‖C‖}_{2},

where

ε

is the machine precision.

8 Further Comments

The total number of real floating point operations is approximately

8 n q^{2}

side = Nag_LeftSide

and

8 m q^{2}

side = Nag_RightSide

, where

q = i_{hi} - i_{lo}

The real analogue of this function is nag_dormhr (f08ngc).

9 Example

This example computes all the eigenvalues of the matrix

A

, where

A = (\begin{array}{r} - 3.97 - 5.04 i & - 4.11 + 3.70 i & - 0.34 + 1.01 i & 1.29 - 0.86 i \\ 0.34 - 1.50 i & 1.52 - 0.43 i & 1.88 - 5.38 i & 3.36 + 0.65 i \\ 3.31 - 3.85 i & 2.50 + 3.45 i & 0.88 - 1.08 i & 0.64 - 1.48 i \\ - 1.10 + 0.82 i & 1.81 - 1.59 i & 3.25 + 1.33 i & 1.57 - 3.44 i \end{array}),

and those eigenvectors which correspond to eigenvalues

λ

such that

Re (λ) < 0

. Here

A

is general and must first be reduced to upper Hessenberg form

H

by nag_zgehrd (f08nsc). The program then calls nag_zhseqr (f08psc) to compute the eigenvalues, and nag_zhsein (f08pxc) to compute the required eigenvectors of

H

by inverse iteration. Finally nag_zunmhr (f08nuc) is called to transform the eigenvectors of

H

back to eigenvectors of the original matrix

A

NAG Library Function Documentnag_zunmhr (f08nuc)

+− 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_zunmhr (f08nuc)