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_lapack_dgeqpf (f08be)

Purpose

nag_lapack_dgeqpf (f08be) computes the $QR$ factorization, with column pivoting, of a real $m$ by $n$ matrix.

Syntax

[a, jpvt, tau, info] = f08be(a, jpvt, 'm', m, 'n', n)
[a, jpvt, tau, info] = nag_lapack_dgeqpf(a, jpvt, 'm', m, 'n', n)

Description

nag_lapack_dgeqpf (f08be) forms the $QR$ factorization, with column pivoting, of an arbitrary rectangular real $m$ by $n$ matrix.
If $m\ge n$, the factorization is given by:
 $AP= Q R 0 ,$
where $R$ is an $n$ by $n$ upper triangular matrix, $Q$ is an $m$ by $m$ orthogonal matrix and $P$ is an $n$ by $n$ permutation matrix. It is sometimes more convenient to write the factorization as
 $AP= Q1 Q2 R 0 ,$
which reduces to
 $AP= Q1 R ,$
where ${Q}_{1}$ consists of the first $n$ columns of $Q$, and ${Q}_{2}$ the remaining $m-n$ columns.
If $m, $R$ is trapezoidal, and the factorization can be written
 $AP= Q R1 R2 ,$
where ${R}_{1}$ is upper triangular and ${R}_{2}$ is rectangular.
The matrix $Q$ is not formed explicitly but is represented as a product of $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ elementary reflectors (see the F08 Chapter Introduction for details). Functions are provided to work with $Q$ in this representation (see Further Comments).
Note also that for any $k, the information returned in the first $k$ columns of the array a represents a $QR$ factorization of the first $k$ columns of the permuted matrix $AP$.
The function allows specified columns of $A$ to be moved to the leading columns of $AP$ at the start of the factorization and fixed there. The remaining columns are free to be interchanged so that at the $i$th stage the pivot column is chosen to be the column which maximizes the $2$-norm of elements $i$ to $m$ over columns $i$ to $n$.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

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 $m$ by $n$ matrix $A$.
2:     $\mathrm{jpvt}\left(:\right)$int64int32nag_int array
The dimension of the array jpvt must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
If ${\mathbf{jpvt}}\left(i\right)\ne 0$, then the $i$ th column of $A$ is moved to the beginning of $AP$ before the decomposition is computed and is fixed in place during the computation. Otherwise, the $i$ th column of $A$ is a free column (i.e., one which may be interchanged during the computation with any other free column).

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$.
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 0$.

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)$.
If $m\ge n$, the elements below the diagonal store details of the orthogonal matrix $Q$ and the upper triangle stores the corresponding elements of the $n$ by $n$ upper triangular matrix $R$.
If $m, the strictly lower triangular part stores details of the orthogonal matrix $Q$ and the remaining elements store the corresponding elements of the $m$ by $n$ upper trapezoidal matrix $R$.
2:     $\mathrm{jpvt}\left(:\right)$int64int32nag_int array
The dimension of the array jpvt will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
Details of the permutation matrix $P$. More precisely, if ${\mathbf{jpvt}}\left(i\right)=k$, then the $k$th column of $A$ is moved to become the $i$ th column of $AP$; in other words, the columns of $AP$ are the columns of $A$ in the order ${\mathbf{jpvt}}\left(1\right),{\mathbf{jpvt}}\left(2\right),\dots ,{\mathbf{jpvt}}\left(n\right)$.
3:     $\mathrm{tau}\left(\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)\right)$ – double array
Further details of the orthogonal matrix $Q$.
4:     $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $i$ had an illegal value on entry. The parameters are numbered as follows:
1: m, 2: n, 3: a, 4: lda, 5: jpvt, 6: tau, 7: work, 8: info.
It is possible that info refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.

Accuracy

The computed factorization is the exact factorization of a nearby matrix $\left(A+E\right)$, where
 $E2 = Oε A2 ,$
and $\epsilon$ is the machine precision.

The total number of floating-point operations is approximately $\frac{2}{3}{n}^{2}\left(3m-n\right)$ if $m\ge n$ or $\frac{2}{3}{m}^{2}\left(3n-m\right)$ if $m.
To form the orthogonal matrix $Q$ nag_lapack_dgeqpf (f08be) may be followed by a call to nag_lapack_dorgqr (f08af):
```[a, info] = f08af(a(:,1:m), tau);
```
but note that the second dimension of the array a must be at least m, which may be larger than was required by nag_lapack_dgeqpf (f08be).
When $m\ge n$, it is often only the first $n$ columns of $Q$ that are required, and they may be formed by the call:
```[a, info] = f08af(a, tau);
```
To apply $Q$ to an arbitrary real rectangular matrix $C$, nag_lapack_dgeqpf (f08be) may be followed by a call to nag_lapack_dormqr (f08ag). For example,
```[c, info] = f08ag('Left','Transpose', a(:,1:min(m,n)), tau, c);
```
forms $C={Q}^{\mathrm{T}}C$, where $C$ is $m$ by $p$.
To compute a $QR$ factorization without column pivoting, use nag_lapack_dgeqrf (f08ae).
The complex analogue of this function is nag_lapack_zgeqpf (f08bs).

Example

This example finds the basic solutions for the linear least squares problems
 $minimize⁡ Axi - bi 2 , i=1,2$
where ${b}_{1}$ and ${b}_{2}$ are the columns of the matrix $B$,
 $A = -0.09 0.14 -0.46 0.68 1.29 -1.56 0.20 0.29 1.09 0.51 -1.48 -0.43 0.89 -0.71 -0.96 -1.09 0.84 0.77 2.11 -1.27 0.08 0.55 -1.13 0.14 1.74 -1.59 -0.72 1.06 1.24 0.34 and B= -0.01 -0.04 0.04 -0.03 0.05 0.01 -0.03 -0.02 0.02 0.05 -0.06 0.07 .$
Here $A$ is approximately rank-deficient, and hence it is preferable to use nag_lapack_dgeqpf (f08be) rather than nag_lapack_dgeqrf (f08ae).
```function f08be_example

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

a = [-0.09,  0.14, -0.46,  0.68,  1.29;
-1.56,  0.2,   0.29,  1.09,  0.51;
-1.48, -0.43,  0.89, -0.71, -0.96;
-1.09,  0.84,  0.77,  2.11, -1.27;
0.08,  0.55, -1.13,  0.14,  1.74;
-1.59, -0.72,  1.06,  1.24,  0.34];
b = [-0.01, -0.04;
0.04, -0.03;
0.05,  0.01;
-0.03, -0.02;
0.02,  0.05;
-0.06,  0.07];
jpvt = [int64(0);0;0;0;0];

% Compute the QR factorization of a
[a, jpvt, tau, info] = f08be( ...
a, jpvt);

% Choose tol to reflect the relative accuracy of the input data
tol = 0.01;

% Determine which columns of R to use
k = find(abs(diag(a)) <= tol*abs(a(1,1)));
if numel(k) == 0
k = numel(diag(a));
else
k = k(1)-1;
end

% Compute c = (q^t)*b,
[c, info] = f08ag( ...
'Left', 'Transpose', a, tau, b);

% Compute least-squares solution by backsubstitution in r*b = c
c(1:k, :) = inv(triu(a(1:k,1:k)))*c(1:k,:);
c(k+1:5, :) = 0;

% Unscramble the least-squares solution stored in c
x = zeros(5, 2);
for i=1:5
x(jpvt(i), :) = c(i, :);
end

fprintf('\nLeast-squares solution\n');
disp(x);

```
```f08be example results

Least-squares solution
-0.0370   -0.0044
0.0647   -0.0335
0         0
-0.0515    0.0018
0.0066    0.0102

```