f01 Chapter Contents
f01 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_complex_apply_q (f01rdc)

## 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 $\mathit{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 #include
 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 ,$
${\gamma }_{k}$ is a scalar for which Re ${\gamma }_{k}=1.0$, ${\zeta }_{k}$ is a real scalar and ${z}_{k}$ is an $\left(m-k\right)$ element vector.
${z}_{k}$ must be supplied in the $\left(k-1\right)$th column of a in elements ${\mathbf{a}}\left[\left(k\right)×{\mathbf{tda}}+k-1\right],\dots ,{\mathbf{a}}\left[\left(m-1\right)×{\mathbf{tda}}+k-1\right]$ and ${\theta }_{k}$, given by
 $θ k = ζ k ,Im⁡ γ k ,$
must be supplied either in ${\mathbf{a}}\left[\left(k-1\right)×{\mathbf{tda}}+k-1\right]$ or in ${\mathbf{theta}}\left[k-1\right]$, 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:
• ${\mathbf{trans}}=\mathrm{NoTranspose}$, perform the operation $B:=QB$.
• ${\mathbf{trans}}=\mathrm{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 $\theta$ are to be found as follows:
• ${\mathbf{wheret}}=\mathrm{Nag_ElementsIn}$ The elements of $\theta$ are in $A$.
• ${\mathbf{wheret}}=\mathrm{Nag_ElementsSeparate}$ The elements of $\theta$ 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: ${\mathbf{m}}\ge {\mathbf{n}}$.
4:     nIntegerInput
On entry: $n$, the number of columns of $A$.
When ${\mathbf{n}}=0$ then an immediate return is effected.
Constraint: ${\mathbf{n}}\ge 0$.
5:     a[${\mathbf{m}}×{\mathbf{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 ${\mathbf{wheret}}=\mathrm{Nag_ElementsIn}$, then the diagonal elements of a must contain the elements of $\theta$ as described under the argument theta. When ${\mathbf{wheret}}=\mathrm{Nag_ElementsSeparate}$, then the diagonal elements of the array a are referenced, since they are used temporarily to store the ${\zeta }_{k}$, but they contain their original values on return.
6:     tdaIntegerInput
On entry: the stride separating matrix column elements in the array a.
Constraint: ${\mathbf{tda}}\ge {\mathbf{n}}$.
7:     theta[n]const ComplexInput
On entry: with ${\mathbf{wheret}}=\mathrm{Nag_ElementsSeparate}$, the array theta must contain the elements of $\theta$. If ${\mathbf{theta}}\left[k-1\right]=0.0$ then ${T}_{k}$ is assumed to be $I$; if ${\mathbf{theta}}\left[k-1\right]=\alpha$, with Re $\alpha <0.0$, then ${T}_{k}$ is assumed to be of the form
 $T k = α 0 0 I ; ​$
otherwise ${\mathbf{theta}}\left[k-1\right]$ is assumed to contain ${\theta }_{k}$ given by ${\theta }_{k}=\left({\zeta }_{k},\mathrm{Im}{\gamma }_{k}\right)$.
When ${\mathbf{wheret}}=\mathrm{Nag_ElementsIn}$, the array theta is not referenced, and may be set to the null pointer, i.e., (Complex *)0.
8:     ncolbIntegerInput
On entry: $\mathit{ncolb}$, the number of columns of $B$.
When ${\mathbf{ncolb}}=0$ then an immediate return is effected.
Constraint: ${\mathbf{ncolb}}\ge 0$.
9:     b[${\mathbf{m}}×{\mathbf{tdb}}$]ComplexInput/Output
Note: the $\left(i,j\right)$th element of the matrix $B$ is stored in ${\mathbf{b}}\left[\left(i-1\right)×{\mathbf{tdb}}+j-1\right]$.
On entry: the leading $m$ by $\mathit{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: ${\mathbf{tdb}}\ge {\mathbf{ncolb}}$.
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, ${\mathbf{m}}=〈\mathit{\text{value}}〉$ while ${\mathbf{n}}=〈\mathit{\text{value}}〉$. These arguments must satisfy ${\mathbf{m}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{tda}}=〈\mathit{\text{value}}〉$ while ${\mathbf{n}}=〈\mathit{\text{value}}〉$. These arguments must satisfy ${\mathbf{tda}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{tdb}}=〈\mathit{\text{value}}〉$ while ${\mathbf{ncolb}}=〈\mathit{\text{value}}〉$. These arguments must satisfy ${\mathbf{tdb}}\ge {\mathbf{ncolb}}$.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument trans had an illegal value.
On entry, argument wheret had an illegal value.
NE_INT_ARG_LT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 0$.
On entry, ${\mathbf{ncolb}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ncolb}}\ge 0$.

## 7  Accuracy

Letting $C$ denote the computed matrix ${Q}^{H}B$, $C$ satisfies the relation
 $QC = B + E$
where $‖E‖\le c\epsilon ‖B‖$, $\epsilon$ being the machine precision, $c$ is a modest function of $m$ and $\text{.}$ denotes the spectral (two) norm. An equivalent result holds for the computed matrix $QB$. See also Section 8.

The approximate number of real floating point operations is given by $8n\left(2m-n\right)\mathit{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)