nag_complex_apply_q (f01rdc) (PDF version)
f01 Chapter Contents
f01 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_complex_apply_q (f01rdc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_complex_apply_q (f01rdc) performs one of the transformations
B : = QB   or   B : = Q H B ,
where B  is an m  by ncolb  complex matrix and Q  is an m  by m  unitary matrix, given as the product of Householder transformation matrices.
This function is intended for use following nag_complex_qr (f01rcc).

2  Specification

#include <nag.h>
#include <nagf01.h>
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 Q 1 H ,
Q k  being given in the form
Q k = I 0 0 T k ,
where
T k = I - γ k u k u k H ,
u k = ζ k z k ,
γ 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×tda+k-1] , , a[m-1×tda+k-1]  and θ k , given by
θ k = ζ k ,Im γ k ,
must be supplied either in a[k-1×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:     transMatrixTranspose Input
On entry: the operation to be performed as follows:
  • trans=NoTranspose, perform the operation B := QB .
  • trans=ConjugateTranspose, perform the operation B := Q H B .
Constraint: trans must be one of NoTranspose or ConjugateTranspose.
2:     wheretNag_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 or Nag_ElementsSeparate.
3:     mIntegerInput
On entry: m , the number of rows of A .
Constraint: mn .
4:     nIntegerInput
On entry: n , the number of columns of A .
When n=0  then an immediate return is effected.
Constraint: n0 .
5:     a[m×tda]ComplexInput
On entry: the leading m  by 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:     tdaIntegerInput
On entry: the stride separating matrix column elements in the array a.
Constraint: tdan .
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 = α 0 0 I ; ​
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 set to the null pointer, i.e., (Complex *)0.
8:     ncolbIntegerInput
On entry: ncolb , the number of columns of B .
When ncolb=0  then an immediate return is effected.
Constraint: ncolb0 .
9:     b[m×tdb]ComplexInput/Output
Note: the i,jth element of the matrix B is stored in b[i-1×tdb+j-1].
On entry: the leading m  by ncolb  part of the array b must contain the matrix to be transformed.
On exit: b is overwritten by the transformed matrix.
10:   tdbIntegerInput
On entry: the stride separating matrix column elements in the array b.
Constraint: tdbncolb .
11:   failNagError *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 mn .
On entry, tda=value  while n=value . These arguments must satisfy tdan .
On entry, tdb=value  while ncolb=value . These arguments must satisfy tdbncolb .
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: n0.
On entry, ncolb=value.
Constraint: ncolb0.

7  Accuracy

Letting C  denote the computed matrix Q H B , C  satisfies the relation
QC = B + E
where E 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 QB . See also Section 8.

8  Further Comments

The approximate number of real floating point operations is given by 8 n 2 m - n ncolb .

9  Example

To obtain the matrix Q H B  for the matrix B  given by
B = -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
following the QR  factorization of the 5 by 3 matrix A  given by
A = 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.3 i -0.4 + 0.4 i - 1.8 +1.4 i 0.3 - 0.4 i 0.1 + 0.7 i - 0.0 +1.4 i -0.3 i - 0.3 + 0.3 i 2.4 i .

9.1  Program Text

Program Text (f01rdce.c)

9.2  Program Data

Program Data (f01rdce.d)

9.3  Program Results

Program Results (f01rdce.r)


nag_complex_apply_q (f01rdc) (PDF version)
f01 Chapter Contents
f01 Chapter Introduction
NAG C Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2012