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 (f01rj)

## Purpose

nag_matop_complex_gen_rq (f01rj) finds the $RQ$ factorization of the complex $m$ by $n$ ($m\le n$), matrix $A$, so that $A$ is reduced to upper triangular form by means of unitary transformations from the right.

## Syntax

[a, theta, ifail] = f01rj(a, 'm', m, 'n', n)
[a, theta, ifail] = nag_matop_complex_gen_rq(a, 'm', m, 'n', n)

## Description

The $m$ by $n$ matrix $A$ is factorized as
 $A= R 0 PH when ​m
where $P$ is an $n$ by $n$ unitary matrix and $R$ is an $m$ by $m$ upper triangular matrix.
$P$ is given as a sequence of Householder transformation matrices
 $P=Pm⋯P2P1,$
the $\left(m-k+1\right)$th transformation matrix, ${P}_{k}$, being used to introduce zeros into the $k$th row of $A$. ${P}_{k}$ has the form
 $Pk=I-γkukukH,$
where
 $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. ${\gamma }_{k}$ and ${u}_{k}$ are chosen to annihilate the elements in the $k$th row of $A$.
The scalar ${\gamma }_{k}$ and the vector ${u}_{k}$ are returned in the $k$th element of theta and in the $k$th row of a, such that ${\theta }_{k}$, given by
 $θk=ζk,Imγk.$
is in ${\mathbf{theta}}\left(k\right)$, the elements of ${w}_{k}$ are in ${\mathbf{a}}\left(k,1\right),\dots ,{\mathbf{a}}\left(k,k-1\right)$ and the elements of ${z}_{k}$ are in ${\mathbf{a}}\left(k,m+1\right),\dots ,{\mathbf{a}}\left(k,n\right)$. The elements of $R$ are returned in the upper triangular part of a.

## 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{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}}\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 $n$ part of the array a must contain the matrix to be factorized.

### Optional Input Parameters

1:     $\mathrm{m}$int64int32nag_int scalar
Default: the first dimension of the array a.
$m$, the number of rows of the matrix $A$.
When ${\mathbf{m}}=0$ then an immediate return is effected.
Constraint: ${\mathbf{m}}\ge 0$.
2:     $\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}}\right)$.
The second dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The $m$ by $m$ upper triangular part of a will contain the upper triangular matrix $R$, and the $m$ by $m$ strictly lower triangular part of a and the $m$ by $\left(n-m\right)$ rectangular part of a to the right of the upper triangular part will contain details of the factorization as described in Description.
2:     $\mathrm{theta}\left({\mathbf{m}}\right)$ – complex array
${\mathbf{theta}}\left(k\right)$ contains the scalar ${\theta }_{k}$ for the $\left(m-k+1\right)$th transformation. If ${P}_{k}=I$ then ${\mathbf{theta}}\left(k\right)=0.0$; if
 $Tk= I 0 0 0 α 0 0 0 I , Reα<0.0$
then ${\mathbf{theta}}\left(k\right)=\alpha$, otherwise ${\mathbf{theta}}\left(k\right)$ contains ${\theta }_{k}$ as described in Description and ${\theta }_{k}$ is always in the range $\left(1.0,\sqrt{2.0}\right)$.
3:     $\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{m}}<0$, or ${\mathbf{n}}<{\mathbf{m}}$, or $\mathit{lda}<{\mathbf{m}}$.
${\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 factors $R$ and $P$ satisfy the relation
 $R0PH=A+E,$
where
 $E≤cε A,$
$\epsilon$ is the machine precision (see nag_machine_precision (x02aj)), $c$ is a modest function of $m$ and $n$, and $‖.‖$ denotes the spectral (two) norm.

The approximate number of floating-point operations is given by $8×{m}^{2}\left(3n-m\right)/3$.
The first $k$ rows of the unitary matrix ${P}^{\mathrm{H}}$ can be obtained by calling nag_matop_complex_gen_rq_formq (f01rk), which overwrites the $k$ rows of ${P}^{\mathrm{H}}$ on the first $k$ rows of the array a. ${P}^{\mathrm{H}}$ is obtained by the call:
```[a, ifail] = f01qk('Separate', m, k, a, theta);
```

## Example

This example obtains the $RQ$ factorization of the $3$ by $5$ matrix
 $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 f01rj_example

fprintf('f01rj 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);

disp('RQ Factorization of A');
disp('Vector theta');
disp(theta');
disp('Matrix A after factorization (R in left-hand upper triangle');
disp(RQ);

```
```f01rj example results

RQ Factorization of A
Vector theta
1.0387 + 0.1006i   1.1810 - 0.3809i   1.2244 + 0.0000i

Matrix A after factorization (R in left-hand upper triangle
0.7878 + 0.0000i  -0.2549 - 0.4006i  -0.2774 - 0.2774i  -0.2850 + 0.5586i   0.1154 + 0.7031i
0.0396 + 0.5222i  -2.1122 + 0.0000i  -1.1094 - 0.5547i   0.1283 + 0.2317i   0.0790 - 0.0361i
-0.2265 + 0.2265i   0.0453 + 0.3171i  -3.6056 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.5436i

```