f01 Chapter Contents
f01 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_complex_form_q (f01rec)

## 1  Purpose

nag_complex_form_q (f01rec) returns the first $\mathit{ncolq}$ columns of the $m$ by $m$ unitary matrix $Q$, where $Q$ is 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_form_q (Nag_WhereElements wheret, Integer m, Integer n, Integer ncolq, Complex a[], Integer tda, const Complex theta[], 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 ${\mathrm{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.
Wilkinson J H (1965) The Algebraic Eigenvalue Problem Oxford University Press, Oxford

## 5  Arguments

1:     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 $\mathrm{Nag_ElementsIn}$ or $\mathrm{Nag_ElementsSeparate}$.
2:     mIntegerInput
On entry: $m$, the number of rows of $A$.
Constraint: ${\mathbf{m}}\ge {\mathbf{n}}$.
3:     nIntegerInput
On entry: $n$, the number of columns of $A$.
Constraint: ${\mathbf{n}}\ge 0$.
4:     ncolqIntegerInput
On entry: $\mathit{ncolq}$, the required number of columns of $Q$.
When ${\mathbf{ncolq}}=0$ then an immediate return is effected.
Constraint: $0\le {\mathbf{ncolq}}\le {\mathbf{m}}$.
5:     a[${\mathbf{m}}×{\mathbf{tda}}$]ComplexInput/Output
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.
On exit: the first ncolq columns of the array a are overwritten by the first ncolq columns of the $m$ by $m$ unitary matrix $Q$. When ${\mathbf{n}}=0$ then the first ncolq columns of a are overwritten by the first ncolq columns of the unit matrix.
6:     tdaIntegerInput
On entry: the stride separating matrix column elements in the array a.
Constraint: ${\mathbf{tda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{n}},{\mathbf{ncolq}}\right)$.
7:     theta[n]const ComplexInput
On entry: if ${\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 $\mathrm{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 NULL.
8:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_2_INT_ARG_GT
On entry, ${\mathbf{ncolq}}=⟨\mathit{\text{value}}⟩$ while ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$. These arguments must satisfy ${\mathbf{ncolq}}\le {\mathbf{m}}$.
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 $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{n}},{\mathbf{ncolq}}\right)={\mathbf{ncolq}}$. These arguments must satisfy ${\mathbf{tda}}\ge {\mathbf{n}}$.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
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{ncolq}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ncolq}}\ge 0$.

## 7  Accuracy

The computed matrix $Q$ satisfies the relation
 $Q = P + E ,$
where $P$ is an exactly unitary matrix and
 $E ≤ c ε ,$
$\epsilon$ being the machine precision, $c$ is a modest function of $m$ and $\text{.}$ denotes the spectral (two) norm. See also Section 9 of nag_complex_qr (f01rcc).

## 8  Parallelism and Performance

Not applicable.

The approximate number of real floating-point operations required is given by
 $8 3 n 3 m - n 2 ncolq - n - n ncolq - n ncolq > n 8 3 ncolq 2 3 m - ncolq ncolq ≤ n .$

## 10  Example

To obtain the 5 by 5 unitary matrix $Q$ 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.4 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 .$

### 10.1  Program Text

Program Text (f01rece.c)

### 10.2  Program Data

Program Data (f01rece.d)

### 10.3  Program Results

Program Results (f01rece.r)