Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_matop_complex_gen_rq_formq (f01rk)

## Purpose

nag_matop_complex_gen_rq_formq (f01rk) returns the first $\ell$ rows of the n$n$ by n$n$ unitary matrix PH${P}^{\mathrm{H}}$, where P$P$ is given as the product of Householder transformation matrices.
This function is intended for use following nag_matop_complex_gen_rq (f01rj).

## Syntax

[a, ifail] = f01rk(wheret, m, nrowp, a, theta, 'n', n)
[a, ifail] = nag_matop_complex_gen_rq_formq(wheret, m, nrowp, a, theta, 'n', n)

## Description

P$P$ is assumed to be given by
 P = Pm Pm − 1 ⋯ P1 , $P = Pm P m-1 ⋯ P1 ,$
where
$Pk=I-γkukukH, uk= wk ζk 0 zk$
Pk = I − γkukukH,
 uk = ( wk ζk 0 zk )
γk${\gamma }_{k}$ is a scalar for which Re(γk) = 1.0$\mathrm{Re}\left({\gamma }_{k}\right)=1.0$, ζk${\zeta }_{k}$ is a real scalar, wk${w}_{k}$ is a (k1)$\left(k-1\right)$ element vector and zk${z}_{k}$ is an (nm)$\left(n-m\right)$ element vector. wk${w}_{k}$ must be supplied in the k$k$th row of a in elements a(k,1),,a(k,k1)${\mathbf{a}}\left(k,1\right),\dots ,{\mathbf{a}}\left(k,k-1\right)$. zk${z}_{k}$ must be supplied in the k$k$th row of a in elements a(k,m + 1),,a(k,n)${\mathbf{a}}\left(k,m+1\right),\dots ,{\mathbf{a}}\left(k,n\right)$ and θk${\theta }_{k}$, given by
 θk = (ζk,Im(γk)), $θk=(ζk,Im(γk)),$
must be supplied either in a(k,k)${\mathbf{a}}\left(k,k\right)$ or in theta(k)${\mathbf{theta}}\left(k\right)$, depending upon the parameter wheret.

## References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Wilkinson J H (1965) The Algebraic Eigenvalue Problem Oxford University Press, Oxford

## Parameters

### Compulsory Input Parameters

1:     wheret – string (length ≥ 1)
Indicates where the elements of θ$\theta$ are to be found.
wheret = 'I'${\mathbf{wheret}}=\text{'I'}$ (In a)
The elements of θ$\theta$ are in a.
wheret = 'S'${\mathbf{wheret}}=\text{'S'}$ (Separate)
The elements of θ$\theta$ are separate from a, in theta.
Constraint: wheret = 'I'${\mathbf{wheret}}=\text{'I'}$ or 'S'$\text{'S'}$.
2:     m – int64int32nag_int scalar
m$m$, the number of rows of the matrix A$A$.
Constraint: m0${\mathbf{m}}\ge 0$.
3:     nrowp – int64int32nag_int scalar
$\ell$, the required number of rows of P$P$.
If nrowp = 0${\mathbf{nrowp}}=0$, an immediate return is effected.
Constraint: 0nrowpn$0\le {\mathbf{nrowp}}\le {\mathbf{n}}$.
4:     a(lda, : $:$) – complex array
The first dimension of the array a must be at least max (1,m,nrowp)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}},{\mathbf{nrowp}}\right)$
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The leading m$m$ by m$m$ strictly lower triangular part of the array a, and the m$m$ by (nm)$\left(n-m\right)$ rectangular part of a with top left-hand corner at element a(1,m + 1)${\mathbf{a}}\left(1,{\mathbf{m}}+1\right)$ must contain details of the matrix P$P$. In addition, if wheret = 'I'${\mathbf{wheret}}=\text{'I'}$, the diagonal elements of a must contain the elements of θ$\theta$.
5:     theta( : $:$) – complex array
Note: the dimension of the array theta must be at least max (1,m)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$ if wheret = 'S'${\mathbf{wheret}}=\text{'S'}$, and at least 1$1$ otherwise.
If wheret = 'S'${\mathbf{wheret}}=\text{'S'}$, the array theta must contain the elements of θ$\theta$. If theta(k) = 0.0${\mathbf{theta}}\left(k\right)=0.0$, Pk${P}_{k}$ is assumed to be I$I$, if theta(k) = α${\mathbf{theta}}\left(k\right)=\alpha$ and Re(α) < 0.0$\mathrm{Re}\left(\alpha \right)<0.0$, Pk${P}_{k}$ is assumed to be of the form
Pk =
 I 0 0 0 α 0 0 0 I
,
$Pk= I 0 0 0 α 0 0 0 I ,$
otherwise theta(k)${\mathbf{theta}}\left(k\right)$ is assumed to contain θk${\theta }_{k}$ given by
 θk = (ζk,Im(γk)). $θk=(ζk,Im(γk)).$
If wheret = 'I'${\mathbf{wheret}}=\text{'I'}$, the array theta is not referenced.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The second dimension of the array a.
n$n$, the number of columns of the matrix A$A$.
Constraint: nm${\mathbf{n}}\ge {\mathbf{m}}$.

lda work

### Output Parameters

1:     a(lda, : $:$) – complex array
The first dimension of the array a will be max (1,m,nrowp)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}},{\mathbf{nrowp}}\right)$
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
ldamax (1,m,nrowp)$\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}},{\mathbf{nrowp}}\right)$.
The first nrowp rows of the array a store the first nrowp rows of the n$n$ by n$n$ unitary matrix PH${P}^{\mathrm{H}}$.
2:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 1${\mathbf{ifail}}=-1$
 On entry, wheret ≠ 'I'${\mathbf{wheret}}\ne \text{'I'}$ or 'S'$\text{'S'}$, or m < 0${\mathbf{m}}<0$, or n < m${\mathbf{n}}<{\mathbf{m}}$, or nrowp < 0${\mathbf{nrowp}}<0$ or ${\mathbf{nrowp}}>{\mathbf{n}}$, or lda < max (1,m,nrowp)$\mathit{lda}<\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}},{\mathbf{nrowp}}\right)$.

## Accuracy

The computed matrix P$P$ satisfies the relation
 P = Q + E, $P=Q+E,$
where Q$Q$ is an exactly unitary matrix and
 ‖E‖ ≤ cε, $‖E‖≤cε,$
where ε$\epsilon$ the machine precision (see nag_machine_precision (x02aj)), c$c$ is a modest function of n$n$, and . $‖.‖$ denotes the spectral (two) norm. See also Section [Accuracy] in (f01rj).

The approximate number of floating point operations is given by
 (8/3)n[(3n − m)(2ℓ − m) − m(ℓ − m)], if ​ℓ ≥ m, and ​ (8/3)ℓ2(3n − ℓ), if ​ℓ < m.
$83n[(3n-m)(2ℓ-m)-m(ℓ-m)], if ​ℓ≥m, and ​ 83ℓ2(3n-ℓ), if ​ℓ

## Example

```function nag_matop_complex_gen_rq_formq_example
wheret = 'Separate';
m = int64(3);
nrowp = int64(5);
a = [0.7878385971583354,  -0.2549249642552304 - 0.4005963724010764i, ...
-0.2773500981126146 - 0.2773500981126146i, ...
-0.2849798528036647 + 0.5586154898871638i,  0.1153902061831629 + 0.7031378339767638i;
0.0395714585753771 + 0.5221710199103989i, ...
-2.112235418114766 + 0i,  -1.109400392450458 - 0.5547001962252291i, ...
0.1283479119207073 + 0.2317354439625548i,  0.07898771606177842 - 0.03608286554775068i;
-0.2265135394293346 + 0.2265135394293346i, ...
0.04530270788586691 + 0.3171189552010684i,  -3.605551275463989 + 0i,  0 - 0i,  0 + 0.5436324946304029i;
0 + 0i,  0 + 0i,  0 + 0i,  0 + 0i,  0 + 0i;
0 + 0i,  0 + 0i,  0 + 0i,  0 + 0i,  0 + 0i];
theta = [ 1.038730559968832 - 0.100646644310659i;
1.180971629471905 + 0.3808634421302063i;
1.224430551972102 - 0i];
[aOut, ifail] = ...
nag_matop_complex_gen_rq_formq(wheret, m, nrowp, a, theta)
```
```

aOut =

-0.1970 - 0.1970i   0.0394 - 0.2757i   0.3151 + 0.1576i   0.1970 + 0.5909i  -0.1182 + 0.5646i
0.1639 + 0.4916i  -0.2950 + 0.4261i   0.4516 + 0.3205i  -0.0473 + 0.3314i   0.0328 - 0.2076i
0.2774 + 0.2774i  -0.0555 + 0.3883i  -0.4992 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.6656i
0.3637 - 0.3213i  -0.4752 - 0.0982i  -0.2762 + 0.3049i   0.5121 + 0.0475i  -0.2287 - 0.2072i
0.0123 - 0.5142i  -0.4187 + 0.2987i  -0.0339 - 0.3867i  -0.3613 + 0.3239i   0.2901 - 0.0254i

ifail =

0

```
```function f01rk_example
wheret = 'Separate';
m = int64(3);
nrowp = int64(5);
a = [0.7878385971583354,  -0.2549249642552304 - 0.4005963724010764i, ...
-0.2773500981126146 - 0.2773500981126146i, ...
-0.2849798528036647 + 0.5586154898871638i,  ...
0.1153902061831629 + 0.7031378339767638i;
0.0395714585753771 + 0.5221710199103989i, ...
-2.112235418114766 + 0i,  -1.109400392450458 - 0.5547001962252291i, ...
0.1283479119207073 + 0.2317354439625548i,  ...
0.07898771606177842 - 0.03608286554775068i;
-0.2265135394293346 + 0.2265135394293346i, ...
0.04530270788586691 + 0.3171189552010684i,  -3.605551275463989 + 0i, ...
0 - 0i,  0 + 0.5436324946304029i;
0 + 0i,  0 + 0i,  0 + 0i,  0 + 0i,  0 + 0i;
0 + 0i,  0 + 0i,  0 + 0i,  0 + 0i,  0 + 0i];
theta = [ 1.038730559968832 - 0.100646644310659i;
1.180971629471905 + 0.3808634421302063i;
1.224430551972102 - 0i];
[aOut, ifail] = f01rk(wheret, m, nrowp, a, theta)
```
```

aOut =

-0.1970 - 0.1970i   0.0394 - 0.2757i   0.3151 + 0.1576i   0.1970 + 0.5909i  -0.1182 + 0.5646i
0.1639 + 0.4916i  -0.2950 + 0.4261i   0.4516 + 0.3205i  -0.0473 + 0.3314i   0.0328 - 0.2076i
0.2774 + 0.2774i  -0.0555 + 0.3883i  -0.4992 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.6656i
0.3637 - 0.3213i  -0.4752 - 0.0982i  -0.2762 + 0.3049i   0.5121 + 0.0475i  -0.2287 - 0.2072i
0.0123 - 0.5142i  -0.4187 + 0.2987i  -0.0339 - 0.3867i  -0.3613 + 0.3239i   0.2901 - 0.0254i

ifail =

0

```