NAG Library Function Document

nag_zunmbr (f08kuc)

void	nag_zunmbr (Nag_OrderType order, Nag_VectType vect, Nag_SideType side, Nag_TransType trans, Integer m, Integer n, Integer k, const Complex a[], Integer pda, const Complex tau[], Complex c[], Integer pdc, NagError *fail)

3 Description

nag_zunmbr (f08kuc) is intended to be used after a call to nag_zgebrd (f08ksc), which reduces a complex rectangular matrix

A

to real bidiagonal form

B

by a unitary transformation:

A = Q B P^{H}

. nag_zgebrd (f08ksc) represents the matrices

Q

and

P^{H}

as products of elementary reflectors.

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

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

overwriting the result on

C

(which may be any complex rectangular matrix).

4 References

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

5 Arguments

Note: in the descriptions below,

r

denotes the order of

Q

P^{H}

: if

side = Nag_LeftSide

r = m

and if

side = Nag_RightSide

r = n

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: vect – Nag_VectTypeInput

On entry: indicates whether

Q

Q^{H}

P

P^{H}

is to be applied to

C

$vect = Nag_ApplyQ$: $Q$ or $Q^{H}$ is applied to $C$ .
$vect = Nag_ApplyP$: $P$ or $P^{H}$ is applied to $C$ .

Constraint:

vect = Nag_ApplyQ

Nag_ApplyP

3: side – Nag_SideTypeInput

On entry: indicates how

Q

Q^{H}

P

P^{H}

is to be applied to

C

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

Constraint:

side = Nag_LeftSide

Nag_RightSide

4: trans – Nag_TransTypeInput

On entry: indicates whether

Q

P

Q^{H}

P^{H}

is to be applied to

C

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

Constraint:

trans = Nag_NoTrans

Nag_ConjTrans

5: m – IntegerInput

On entry:

m

, the number of rows of the matrix

C

Constraint:

m \geq 0

6: n – IntegerInput

On entry:

n

, the number of columns of the matrix

C

Constraint:

n \geq 0

7: k – IntegerInput

On entry: if

vect = Nag_ApplyQ

, the number of columns in the original matrix

A

vect = Nag_ApplyP

, the number of rows in the original matrix

A

Constraint:

k \geq 0

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

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

$\max (1, pda \times \min (r, k))$ when $vect = Nag_ApplyQ$ and $order = Nag_ColMajor$ ;
$\max (1, r \times pda)$ when $vect = Nag_ApplyQ$ and $order = Nag_RowMajor$ ;
$\max (1, pda \times r)$ when $vect = Nag_ApplyP$ and $order = Nag_ColMajor$ ;
$\max (1, \min (r, k) \times pda)$ when $vect = Nag_ApplyP$ and $order = Nag_RowMajor$ .

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

9: pda – IntegerInput

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

Constraints:

if order=Nag_ColMajor,
- if $vect = Nag_ApplyQ$ , $pda \geq \max (1, r)$ ;
- if $vect = Nag_ApplyP$ , $pda \geq \max (1, \min (r, k))$ ;
if order=Nag_RowMajor,
- if $vect = Nag_ApplyQ$ , $pda \geq \max (1, \min (r, k))$ ;
- if $vect = Nag_ApplyP$ , $pda \geq \max (1, r)$ .

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

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

\max (1, \min (r, k))

On entry: further details of the elementary reflectors, as returned by nag_zgebrd (f08ksc) in its argument tauq if

vect = Nag_ApplyQ

, or in its argument taup if

vect = Nag_ApplyP

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 matrix

C

On exit: c is overwritten by

Q C

Q^{H} C

C Q

C^{H} Q

P C

P^{H} C

C P

C^{H} P

as specified by vect, 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_2: On entry, $vect = 〈value〉$ , $pda = 〈value〉$ , $k = 〈value〉$ .
Constraint: if $vect = Nag_ApplyQ$ , $pda \geq \max (1, \min (r, k))$ ;
if $vect = Nag_ApplyP$ , $pda \geq \max (1, r)$ .; On entry, $vect = 〈value〉$ , $pda = 〈value〉$ and $k = 〈value〉$ .
Constraint: if $vect = Nag_ApplyQ$ , $pda \geq \max (1, r)$ ;
if $vect = Nag_ApplyP$ , $pda \geq \max (1, \min (r, k))$ .
NE_INT: On entry, $k = 〈value〉$ .
Constraint: $k \geq 0$ .; 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

if $side = Nag_LeftSide$ and $m \geq k$ , $8 n k (2 m - k)$ ;
if $side = Nag_RightSide$ and $n \geq k$ , $8 m k (2 n - k)$ ;
if $side = Nag_LeftSide$ and $m < k$ , $8 m^{2} n$ ;
if $side = Nag_RightSide$ and $n < k$ , $8 m n^{2}$ ,

where

k

is the value of the argument k.

The real analogue of this function is nag_dormbr (f08kgc).

9 Example

For this function two examples are presented. Both illustrate how the reduction to bidiagonal form of a matrix

A

may be preceded by a

Q R

L Q

factorization of

A

In the first example,

m > n

, and

A = (\begin{array}{r} 0.96 - 0.81 i & - 0.03 + 0.96 i & - 0.91 + 2.06 i & - 0.05 + 0.41 i \\ - 0.98 + 1.98 i & - 1.20 + 0.19 i & - 0.66 + 0.42 i & - 0.81 + 0.56 i \\ 0.62 - 0.46 i & 1.01 + 0.02 i & 0.63 - 0.17 i & - 1.11 + 0.60 i \\ - 0.37 + 0.38 i & 0.19 - 0.54 i & - 0.98 - 0.36 i & 0.22 - 0.20 i \\ 0.83 + 0.51 i & 0.20 + 0.01 i & - 0.17 - 0.46 i & 1.47 + 1.59 i \\ 1.08 - 0.28 i & 0.20 - 0.12 i & - 0.07 + 1.23 i & 0.26 + 0.26 i \end{array}) .

The function first performs a

Q R

factorization of

A

A = Q_{a} R

and then reduces the factor

R

to bidiagonal form

B

R = Q_{b} B P^{H}

. Finally it forms

Q_{a}

and calls nag_zunmbr (f08kuc) to form

Q = Q_{a} Q_{b}

In the second example,

m < n

, and

A = (\begin{array}{r} 0.28 - 0.36 i & 0.50 - 0.86 i & - 0.77 - 0.48 i & 1.58 + 0.66 i \\ - 0.50 - 1.10 i & - 1.21 + 0.76 i & - 0.32 - 0.24 i & - 0.27 - 1.15 i \\ 0.36 - 0.51 i & - 0.07 + 1.33 i & - 0.75 + 0.47 i & - 0.08 + 1.01 i \end{array}) .

The function first performs an

L Q

factorization of

A

A = L P_{a}^{H}

and then reduces the factor

L

to bidiagonal form

B

L = Q B P_{b}^{H}

. Finally it forms

P_{b}^{H}

and calls nag_zunmbr (f08kuc) to form

P^{H} = P_{b}^{H} P_{a}^{H}

NAG Library Function Documentnag_zunmbr (f08kuc)

+− 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_zunmbr (f08kuc)