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$ by $n$ unitary matrix ${P}^{\mathrm{H}}$, where $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$ is assumed to be given by
 $P = Pm P m-1 ⋯ P1 ,$
where
 $Pk=I-γkukukH, uk= wk ζk 0 zk$
${\gamma }_{k}$ is a scalar for which $\mathrm{Re}\left({\gamma }_{k}\right)=1.0$, ${\zeta }_{k}$ is a real scalar, ${w}_{k}$ is a $\left(k-1\right)$ element vector and ${z}_{k}$ is an $\left(n-m\right)$ element vector. ${w}_{k}$ must be supplied in the $k$th row of a in elements ${\mathbf{a}}\left(k,1\right),\dots ,{\mathbf{a}}\left(k,k-1\right)$. ${z}_{k}$ must be supplied in the $k$th row of a in elements ${\mathbf{a}}\left(k,m+1\right),\dots ,{\mathbf{a}}\left(k,n\right)$ and ${\theta }_{k}$, given by
 $θk=ζk,Imγk,$
must be supplied either in ${\mathbf{a}}\left(k,k\right)$ or in ${\mathbf{theta}}\left(k\right)$, depending upon the argument 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:     $\mathrm{wheret}$ – string (length ≥ 1)
Indicates where the elements of $\theta$ are to be found.
${\mathbf{wheret}}=\text{'I'}$ (In a)
The elements of $\theta$ are in a.
${\mathbf{wheret}}=\text{'S'}$ (Separate)
The elements of $\theta$ are separate from a, in theta.
Constraint: ${\mathbf{wheret}}=\text{'I'}$ or $\text{'S'}$.
2:     $\mathrm{m}$int64int32nag_int scalar
$m$, the number of rows of the matrix $A$.
Constraint: ${\mathbf{m}}\ge 0$.
3:     $\mathrm{nrowp}$int64int32nag_int scalar
$\ell$, the required number of rows of $P$.
If ${\mathbf{nrowp}}=0$, an immediate return is effected.
Constraint: $0\le {\mathbf{nrowp}}\le {\mathbf{n}}$.
4:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}},{\mathbf{nrowp}}\right)$.
The second dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The leading $m$ by $m$ strictly lower triangular part of the array a, and the $m$ by $\left(n-m\right)$ rectangular part of a with top left-hand corner at element ${\mathbf{a}}\left(1,{\mathbf{m}}+1\right)$ must contain details of the matrix $P$. In addition, if ${\mathbf{wheret}}=\text{'I'}$, the diagonal elements of a must contain the elements of $\theta$.
5:     $\mathrm{theta}\left(:\right)$ – complex array
The dimension of the array theta must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$ if ${\mathbf{wheret}}=\text{'S'}$, and at least $1$ otherwise
If ${\mathbf{wheret}}=\text{'S'}$, the array theta must contain the elements of $\theta$. If ${\mathbf{theta}}\left(k\right)=0.0$, ${P}_{k}$ is assumed to be $I$, if ${\mathbf{theta}}\left(k\right)=\alpha$ and $\mathrm{Re}\left(\alpha \right)<0.0$, ${P}_{k}$ is assumed to be of the form
 $Pk= I 0 0 0 α 0 0 0 I ,$
otherwise ${\mathbf{theta}}\left(k\right)$ is assumed to contain ${\theta }_{k}$ given by
 $θk=ζk,Imγk.$
If ${\mathbf{wheret}}=\text{'I'}$, the array theta is not referenced.

### Optional Input Parameters

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

### Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}},{\mathbf{nrowp}}\right)$.
The second dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The first nrowp rows of the array a store the first nrowp rows of the $n$ by $n$ unitary matrix ${P}^{\mathrm{H}}$.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{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:
${\mathbf{ifail}}=-1$
 On entry, ${\mathbf{wheret}}\ne \text{'I'}$ or $\text{'S'}$, or ${\mathbf{m}}<0$, or ${\mathbf{n}}<{\mathbf{m}}$, or ${\mathbf{nrowp}}<0$ or ${\mathbf{nrowp}}>{\mathbf{n}}$, or $\mathit{lda}<\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}},{\mathbf{nrowp}}\right)$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

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

The approximate number of floating-point operations is given by
 $83n3n-m2ℓ-m-mℓ-m, if ​ℓ≥m, and ​ 83ℓ23n-ℓ, if ​ℓ

## Example

This example obtains the $5$ by $5$ unitary matrix $P$ following the $RQ$ factorization of the $3$ by $5$ matrix $A$ given by
 $A = -0.5i 0.4-0.3i 0.4i+0.0 0.3-0.4i 0.3i -0.5-1.5i 0.9-1.3i -0.4-0.4i 0.1-0.7i 0.3-0.3i -1.0-1.0i 0.2-1.4i 1.8i+0.0 0.0i+0.0 -2.4i .$
```function f01rk_example

fprintf('f01rk example results\n\n');

a = [  0   - 0.5i,  0.4 - 0.3i,  0.4 + 0i,    0.3 + 0.4i,  0   + 0.3i;
-0.5 - 1.5i,  0.9 - 1.3i, -0.4 - 0.4i,  0.1 - 0.7i,  0.3 - 0.3i;
-1   - i,     0.2 - 1.4i,  1.8 + 0i,    0   + 0i,    0   - 2.4i];

[RQ, theta, ifail] = f01rj(a);

wheret = 'Separate';
m     = int64(size(a,1));
nrowp = int64(size(a,2));
RQ(m+1:nrowp,1:nrowp) = complex(0);

[PT, ifail] = f01rk( ...
wheret, m, nrowp, RQ, theta);

P = PT';
disp('Matrix P');
disp(P);

```
```f01rk example results

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

```