NAG Library Function Document

nag_complex_apply_q (f01rdc)

void	nag_complex_apply_q (MatrixTranspose trans, Nag_WhereElements wheret, Integer m, Integer n, Complex a[], Integer tda, const Complex theta[], Integer ncolb, Complex b[], Integer tdb, NagError *fail)

3 Description

The unitary matrix

Q

is assumed to be given by

Q = {(Q_{n} Q_{n - 1} \dots Q_{1})}^{H},

Q_{k}

being given in the form

Q_{k} = (\begin{matrix} I & 0 \\ 0 & T_{k} \end{matrix}),

where

T_{k} = I - γ_{k} u_{k} u_{k}^{H},

u_{k} = (\begin{matrix} ζ_{k} \\ z_{k} \end{matrix}),

γ_{k}

is a scalar for which Re

γ_{k} = 1.0

ζ_{k}

is a real scalar and

z_{k}

is an

(m - k)

element vector.

z_{k}

must be supplied in the

(k - 1)

th column of a in elements

a [(k) \times tda + k - 1], \dots, a [(m - 1) \times tda + k - 1]

and

θ_{k}

, given by

θ_{k} = (ζ_{k}, Im γ_{k}),

must be supplied either in

a [(k - 1) \times tda + k - 1]

or in

theta [k - 1]

, depending upon the argument wheret.

To obtain

Q

explicitly

B

may be set to

I

and premultiplied by

Q

. This is more efficient than obtaining

Q^{H}

. Alternatively, nag_complex_form_q (f01rec) may be used to obtain

Q

overwritten on

A

4 References

Wilkinson J H (1965) The Algebraic Eigenvalue Problem Oxford University Press, Oxford

5 Arguments

1: trans – MatrixTranspose Input

On entry: the operation to be performed as follows:

$trans = NoTranspose$ , perform the operation $B := Q B$ .
$trans = ConjugateTranspose$ , perform the operation $B := Q^{H} B$ .

Constraint: trans must be one of

NoTranspose

ConjugateTranspose

2: wheret – Nag_WhereElementsInput

On entry: the elements of

θ

are to be found as follows:

$wheret = Nag_ElementsIn$ The elements of $θ$ are in $A$ .
$wheret = Nag_ElementsSeparate$ The elements of $θ$ are separate from $A$ , in theta.

Constraint: wheret must be one of

Nag_ElementsIn

Nag_ElementsSeparate

3: m – IntegerInput

On entry:

m

, the number of rows of

A

Constraint:

m \geq n

4: n – IntegerInput

On entry:

n

, the number of columns of

A

When

n = 0

then an immediate return is effected.

Constraint:

n \geq 0

5: a[ $m \times tda$ ] – ComplexInput

On entry: the leading

m

n

strictly lower triangular part of the array a must contain details of the matrix

Q

. In addition, when

wheret = Nag_ElementsIn

, then the diagonal elements of a must contain the elements of

θ

as described under the argument theta. When

wheret = Nag_ElementsSeparate

, then the diagonal elements of the array a are referenced, since they are used temporarily to store the

ζ_{k}

, but they contain their original values on return.

6: tda – IntegerInput

On entry: the stride separating matrix column elements in the array a.

Constraint:

tda \geq n

7: theta[n] – const ComplexInput

On entry: with

wheret = Nag_ElementsSeparate

, the array theta must contain the elements of

θ

. If

theta [k - 1] = 0.0

then

T_{k}

is assumed to be

I

; if

theta [k - 1] = α

, with Re

α < 0.0

, then

T_{k}

is assumed to be of the form

T_{k} = (\begin{matrix} α & 0 \\ 0 & I \end{matrix}); ​

otherwise

theta [k - 1]

is assumed to contain

θ_{k}

given by

θ_{k} = (ζ_{k}, Im γ_{k})

When

wheret = Nag_ElementsIn

, the array theta is not referenced and may be NULL.

8: ncolb – IntegerInput

On entry:

ncolb

, the number of columns of

B

When

ncolb = 0

then an immediate return is effected.

Constraint:

ncolb \geq 0

9: b[ $m \times tdb$ ] – ComplexInput/Output

Note: the

(i, j)

th element of the matrix

B

is stored in

b [(i - 1) \times tdb + j - 1]

On entry: the leading

m

ncolb

part of the array b must contain the matrix to be transformed.

On exit: b is overwritten by the transformed matrix.

10: tdb – IntegerInput

On entry: the stride separating matrix column elements in the array b.

Constraint:

tdb \geq ncolb

11: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_2_INT_ARG_LT: On entry, $m = ⟨value⟩$ while $n = ⟨value⟩$ . These arguments must satisfy $m \geq n$ .
On entry, $tda = ⟨value⟩$ while $n = ⟨value⟩$ . These arguments must satisfy $tda \geq n$ .
On entry, $tdb = ⟨value⟩$ while $ncolb = ⟨value⟩$ . These arguments must satisfy $tdb \geq ncolb$ .
NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument trans had an illegal value.
On entry, argument wheret had an illegal value.
NE_INT_ARG_LT: On entry, $n = ⟨value⟩$ .
Constraint: $n \geq 0$ .
On entry, $ncolb = ⟨value⟩$ .
Constraint: $ncolb \geq 0$ .

7 Accuracy

Letting

C

denote the computed matrix

Q^{H} B

C

satisfies the relation

Q C = B + E

where

‖E‖ \leq c ε ‖B‖

ε

being the machine precision,

c

is a modest function of

m

and

.

denotes the spectral (two) norm. An equivalent result holds for the computed matrix

Q B

. See also Section 9.

8 Parallelism and Performance

Not applicable.

9 Further Comments

The approximate number of real floating-point operations is given by

8 n (2 m - n) ncolb

10 Example

To obtain the matrix

Q^{H} B

for the matrix

B

given by

B = (\begin{matrix} - 0.55 + 1.05 i & 0.45 + 1.05 i \\ 0.49 + 0.93 i & 1.09 + 0.13 i \\ 0.56 - 0.16 i & 0.64 + 0.16 i \\ 0.39 + 0.23 i & - 0.39 - 0.23 i \\ 1.13 + 0.83 i - 1.13 + 0.77 i \end{matrix})

following the

Q R

factorization of the 5 by 3 matrix

A

given by

A = (\begin{matrix} 0.5 i & - 0.5 + 1.5 i & - 1.0 + 1.0 i \\ 0.4 + 0.3 i & 0.9 + 1.3 i & 0.2 + 1.4 i \\ 0.4 & - 0.4 + 0.4 i & 1.8 \\ 0.3 - 0.4 i & 0.1 + 0.7 i & 0.0 \\ - 0.3 i & 0.3 + 0.3 i & 2.4 i \end{matrix}) .

NAG Library Function Documentnag_complex_apply_q (f01rdc)

+− 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

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG Library Function Document

nag_complex_apply_q (f01rdc)