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_real_trapez_rq (f01qg)

## Purpose

nag_matop_real_trapez_rq (f01qg) reduces the $m$ by $n$ ($m\le n$) real upper trapezoidal matrix $A$ to upper triangular form by means of orthogonal transformations.

## Syntax

[a, zeta, ifail] = f01qg(a, 'm', m, 'n', n)
[a, zeta, ifail] = nag_matop_real_trapez_rq(a, 'm', m, 'n', n)

## Description

The $m$ by $n$ ($m\le n$) real upper trapezoidal matrix $A$ given by
 $A= U X ,$
where $U$ is an $m$ by $m$ upper triangular matrix, is factorized as
 $A= R 0 PT,$
where $P$ is an $n$ by $n$ orthogonal 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 0 0 Tk ,$
where
 $Tk=I-ukukT, uk= ζk 0 zk ,$
${\zeta }_{k}$ is a scalar and ${z}_{k}$ is an ($n-m$) element vector. ${\zeta }_{k}$ and ${z}_{k}$ are chosen to annihilate the elements of the $k$th row of $X$.
The vector ${u}_{k}$ is returned in the $k$th element of the array zeta and in the $k$th row of a, such that ${\zeta }_{k}$ is in ${\mathbf{zeta}}\left(k\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.
For further information on this factorization and its use see Section 6.5 of Golub and Van Loan (1996).

## 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)$ – double 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$ upper trapezoidal 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)$ – double 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 $\left(n-m\right)$ upper trapezoidal part of a will contain details of the factorization as described in Description.
2:     $\mathrm{zeta}\left({\mathbf{m}}\right)$ – double array
${\mathbf{zeta}}\left(k\right)$ contains the scalar ${\zeta }_{k}$ for the $\left(m-k+1\right)$th transformation. If ${T}_{k}=I$ then ${\mathbf{zeta}}\left(k\right)=0.0$, otherwise ${\mathbf{zeta}}\left(k\right)$ contains ${\zeta }_{k}$ as described in Description and ${\zeta }_{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
 $R0PT=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 $2×{m}^{2}\left(n-m\right)$.

## Example

This example reduces the $3$ by $5$ matrix
 $A= 2.4 0.8 -1.4 3.0 -0.8 0.0 1.6 0.8 0.4 -0.8 0.0 0.0 1.0 2.0 2.0$
to upper triangular form.
```function f01qg_example

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

a = [2.4, 0.8, -1.4, 3,   -0.8;
0,   1.6,  0.8, 0.4, -0.8;
0,   0,    1,   2,    2];

[RQ, zeta, ifail] = f01qg(a);

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

```
```f01qg example results

RQ Factorization of A
Vector zeta
1.2649    1.3416    1.1547

Matrix A after factorization (R in left-hand upper triangle
-4.0000   -1.0000   -1.0000    0.6325   -0.0000
0   -2.0000    0.0000    0.0000   -0.4472
0         0   -3.0000    0.5774    0.5774

```