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$m$ by n$n$ (mn$m\le n$) real upper trapezoidal matrix A$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$m$ by n$n$ (mn$m\le n$) real upper trapezoidal matrix A$A$ given by
A =
 ( U X )
,
$A= U X ,$
where U$U$ is an m$m$ by m$m$ upper triangular matrix, is factorized as
A =
 ( R 0 )
PT,
$A= R 0 PT,$
where P$P$ is an n$n$ by n$n$ orthogonal matrix and R$R$ is an m$m$ by m$m$ upper triangular matrix.
P$P$ is given as a sequence of Householder transformation matrices
 P = Pm ⋯ P2P1, $P=Pm⋯P2P1,$
the (mk + 1)$\left(m-k+1\right)$th transformation matrix, Pk${P}_{k}$, being used to introduce zeros into the k$k$th row of A$A$. Pk${P}_{k}$ has the form
Pk =
 ( I 0 ) 0 Tk
,
$Pk= I 0 0 Tk ,$
where
$Tk=I-ukukT, uk= ζk 0 zk ,$
Tk = I − ukukT,
 uk = ( ζk 0 zk ),
ζk${\zeta }_{k}$ is a scalar and zk${z}_{k}$ is an (nm$n-m$) element vector. ζk${\zeta }_{k}$ and zk${z}_{k}$ are chosen to annihilate the elements of the k$k$th row of X$X$.
The vector uk${u}_{k}$ is returned in the k$k$th element of the array zeta and in the k$k$th row of a, such that ζk${\zeta }_{k}$ is in zeta(k)${\mathbf{zeta}}\left(k\right)$ and the elements of zk${z}_{k}$ are in a(k,m + 1),,a(k,n)${\mathbf{a}}\left(k,m+1\right),\dots ,{\mathbf{a}}\left(k,n\right)$. The elements of R$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:     a(lda, : $:$) – double array
The first dimension of the array a must be at least max (1,m)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\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 n$n$ upper trapezoidal part of the array a must contain the matrix to be factorized.

### Optional Input Parameters

1:     m – int64int32nag_int scalar
Default: The first dimension of the array a.
m$m$, the number of rows of the matrix A$A$.
When m = 0${\mathbf{m}}=0$ then an immediate return is effected.
Constraint: m0${\mathbf{m}}\ge 0$.
2:     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

### Output Parameters

1:     a(lda, : $:$) – double array
The first dimension of the array a will be max (1,m)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\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)$\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The m$m$ by m$m$ upper triangular part of a will contain the upper triangular matrix R$R$, and the m$m$ by (nm)$\left(n-m\right)$ upper trapezoidal part of a will contain details of the factorization as described in Section [Description].
2:     zeta(m) – double array
zeta(k)${\mathbf{zeta}}\left(k\right)$ contains the scalar ζk${\zeta }_{k}$ for the (mk + 1)$\left(m-k+1\right)$th transformation. If Tk = I${T}_{k}=I$ then zeta(k) = 0.0${\mathbf{zeta}}\left(k\right)=0.0$, otherwise zeta(k)${\mathbf{zeta}}\left(k\right)$ contains ζk${\zeta }_{k}$ as described in Section [Description] and ζk${\zeta }_{k}$ is always in the range (1.0,sqrt(2.0))$\left(1.0,\sqrt{2.0}\right)$.
3:     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, m < 0${\mathbf{m}}<0$, or n < m${\mathbf{n}}<{\mathbf{m}}$, or lda < m$\mathit{lda}<{\mathbf{m}}$.

## Accuracy

The computed factors R$R$ and P$P$ satisfy the relation
 (R0)PT = A + E, $(R0)PT=A+E,$
where
 ‖E‖ ≤ cε ‖A‖, $‖E‖≤cε ‖A‖,$
ε$\epsilon$ is the machine precision (see nag_machine_precision (x02aj)), c$c$ is a modest function of m$m$ and n$n$ and . $‖.‖$ denotes the spectral (two) norm.

The approximate number of floating point operations is given by 2 × m2(nm)$2×{m}^{2}\left(n-m\right)$.

## Example

```function nag_matop_real_trapez_rq_example
a = [2.4, 0.8, -1.4, 3, -0.8;
0, 1.6, 0.8, 0.4, -0.8;
0, 0, 1, 2, 2];
[aOut, zeta, ifail] = nag_matop_real_trapez_rq(a)
```
```

aOut =

-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

zeta =

1.2649
1.3416
1.1547

ifail =

0

```
```function f01qg_example
a = [2.4, 0.8, -1.4, 3, -0.8;
0, 1.6, 0.8, 0.4, -0.8;
0, 0, 1, 2, 2];
[aOut, zeta, ifail] = f01qg(a)
```
```

aOut =

-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

zeta =

1.2649
1.3416
1.1547

ifail =

0

```