nag_zgemqrt (f08aqc) : NAG Library, Mark 24

2 Specification

#include <nag.h>

#include <nagf08.h>

void	nag_zgemqrt (Nag_OrderType order, Nag_SideType side, Nag_TransType trans, Integer m, Integer n, Integer k, Integer nb, const Complex v[], Integer pdv, const Complex t[], Integer pdt, Complex c[], Integer pdc, NagError *fail)

3 Description

nag_zgemqrt (f08aqc) is intended to be used after a call to nag_zgeqrt (f08apc), which performs a

Q R

factorization of a complex matrix

A

. The unitary matrix

Q

is represented as a product of elementary reflectors.

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 in solving linear least squares problems, as described in the f08 Chapter Introduction and illustrated in Section 10 in nag_zgeqrt (f08apc).

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

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

Constraint:

m \geq 0

5: n – IntegerInput

On entry:

n

, the number of columns of the matrix

C

Constraint:

n \geq 0

6: k – IntegerInput

On entry:

k

, the number of elementary reflectors whose product defines the matrix

Q

. Usually

k = \min (m_{A}, n_{A})

where

m_{A}

n_{A}

are the dimensions of the matrix

A

supplied in a previous call to nag_zgeqrt (f08apc).

Constraints:

if $side = Nag_LeftSide$ , $m \geq k \geq 0$ ;
if $side = Nag_RightSide$ , $n \geq k \geq 0$ .

7: nb – IntegerInput

On entry: the block size used in the

Q R

factorization performed in a previous call to nag_zgeqrt (f08apc); this value must remain unchanged from that call.

Constraints:

$nb \geq 1$ ;
if $k > 0$ , $nb \leq k$ .

8: v[

\dim

] – const ComplexInput

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

$\max (1, pdv \times k)$ when $order = Nag_ColMajor$ ;
$\max (1, m \times pdv)$ when $order = Nag_RowMajor$ and $side = Nag_LeftSide$ ;
$\max (1, n \times pdv)$ when $order = Nag_RowMajor$ and $side = Nag_RightSide$ .

On entry: details of the vectors which define the elementary reflectors, as returned by nag_zgeqrt (f08apc) in the first

k

columns of its array argument a.

9: pdv – IntegerInput

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

Constraints:

if order=Nag_ColMajor,
- if $side = Nag_LeftSide$ , $pdv \geq \max (1, m)$ ;
- if $side = Nag_RightSide$ , $pdv \geq \max (1, n)$ ;
if $order = Nag_RowMajor$ , $pdv \geq \max (1, k)$ .

10: t[

\dim

] – const ComplexInput

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

$\max (1, pdt \times k)$ when $order = Nag_ColMajor$ ;
$\max (1, nb \times pdt)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

T

is stored in

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

On entry: further details of the unitary matrix

Q

as returned by nag_zgeqrt (f08apc). The number of blocks is

b = ⌈\frac{k}{nb}⌉

, where

k = \min (m, n)

and each block is of order nb except for the last block, which is of order

k - (b - 1) \times nb

. For the

b

blocks the upper triangular block reflector factors

T_{1}, T_{2}, \dots, T_{b}

are stored in the

nb

n

matrix

T

T = [T_{1} | T_{2} | \dots | T_{b}]

11: pdt – IntegerInput

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

Constraints:

if $order = Nag_ColMajor$ , $pdt \geq nb$ ;
if $order = Nag_RowMajor$ , $pdt \geq \max (1, k)$ .

12: 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.

13: 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)$ .

14: 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

k = ⟨value⟩

.
Constraint: if

side = Nag_LeftSide

m \geq k \geq 0

;
if

side = Nag_RightSide

n \geq k \geq 0

On entry,

side = ⟨value⟩

m = ⟨value⟩

n = ⟨value⟩

and

pdv = ⟨value⟩

.
Constraint: if

side = Nag_LeftSide

pdv \geq \max (1, m)

;
if

side = Nag_RightSide

pdv \geq \max (1, n)

NE_INT

On entry,

m = ⟨value⟩

.
Constraint:

m \geq 0

On entry,

n = ⟨value⟩

.
Constraint:

n \geq 0

NE_INT_2

On entry,

nb = ⟨value⟩

and

k = ⟨value⟩

.
Constraint:

nb \geq 1

and
if

k > 0

nb \leq k

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)

On entry,

pdt = ⟨value⟩

and

k = ⟨value⟩

.
Constraint:

pdt \geq \max (1, k)

On entry,

pdt = ⟨value⟩

and

nb = ⟨value⟩

.
Constraint:

pdt \geq nb

On entry,

pdv = ⟨value⟩

and

k = ⟨value⟩

.
Constraint:

pdv \geq \max (1, k)

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.

8 Parallelism and Performance

nag_zgemqrt (f08aqc) is not threaded by NAG in any implementation.

nag_zgemqrt (f08aqc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

Please consult the Users' Note for your implementation for any additional implementation-specific information.

NAG Library Function Document

nag_zgemqrt (f08aqc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

NAG Library Function Documentnag_zgemqrt (f08aqc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

NAG Library Function Document

nag_zgemqrt (f08aqc)