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_linsys_real_gen_lsqsol (f04am)

## Purpose

nag_linsys_real_gen_lsqsol (f04am) calculates the accurate least squares solution of a set of $m$ linear equations in $n$ unknowns, $m\ge n$ and rank $\text{}=n$, with multiple right-hand sides, $AX=B$, using a $QR$ factorization and iterative refinement.

## Syntax

[x, qr, alpha, ipiv, ifail] = f04am(a, b, eps, 'm', m, 'n', n, 'ir', ir)
[x, qr, alpha, ipiv, ifail] = nag_linsys_real_gen_lsqsol(a, b, eps, 'm', m, 'n', n, 'ir', ir)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 22: m was made optional

## Description

To compute the least squares solution to a set of $m$ linear equations in $n$ unknowns $\left(m\ge n\right)$ $AX=B$, nag_linsys_real_gen_lsqsol (f04am) first computes a $QR$ factorization of $A$ with column pivoting, $AP=QR$, where $R$ is upper triangular, $Q$ is an $m$ by $m$ orthogonal matrix, and $P$ is a permutation matrix. ${Q}^{\mathrm{T}}$ is applied to the $m$ by $r$ right-hand side matrix $B$ to give $C={Q}^{\mathrm{T}}B$, and the $n$ by $r$ solution matrix $X$ is calculated, to a first approximation, by back-substitution in $RX=C$. The residual matrix $S=B-AX$ is calculated using additional precision, and a correction $D$ to $X$ is computed as the least squares solution to $AD=S$. $X$ is replaced by $X+D$ and this iterative refinement of the solution is repeated until full machine accuracy has been obtained.

## References

Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra Springer–Verlag

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{a}\left(\mathit{lda},{\mathbf{n}}\right)$ – double array
lda, the first dimension of the array, must satisfy the constraint $\mathit{lda}\ge {\mathbf{m}}$.
The $m$ by $n$ matrix $A$.
2:     $\mathrm{b}\left(\mathit{ldb},{\mathbf{ir}}\right)$ – double array
ldb, the first dimension of the array, must satisfy the constraint $\mathit{ldb}\ge {\mathbf{m}}$.
The $m$ by $r$ right-hand side matrix $B$.
3:     $\mathrm{eps}$ – double scalar
Must be set to the value of the machine precision.

### Optional Input Parameters

1:     $\mathrm{m}$int64int32nag_int scalar
Default: the first dimension of the arrays a, b. (An error is raised if these dimensions are not equal.)
$m$, the number of rows of the matrix $A$, i.e., the number of equations.
Constraint: ${\mathbf{m}}\ge 1$.
2:     $\mathrm{n}$int64int32nag_int scalar
Default: the second dimension of the array a.
$n$, the number of columns of the matrix $A$, i.e., the number of unknowns.
Constraint: $0\le {\mathbf{n}}\le {\mathbf{m}}$.
3:     $\mathrm{ir}$int64int32nag_int scalar
Default: the second dimension of the array b.
$r$, the number of right-hand sides.

### Output Parameters

1:     $\mathrm{x}\left(\mathit{ldx},{\mathbf{ir}}\right)$ – double array
The $n$ by $r$ solution matrix $X$.
2:     $\mathrm{qr}\left(\mathit{ldqr},{\mathbf{n}}\right)$ – double array
Details of the $QR$ factorization.
3:     $\mathrm{alpha}\left({\mathbf{n}}\right)$ – double array
The diagonal elements of the upper triangular matrix $R$.
4:     $\mathrm{ipiv}\left({\mathbf{n}}\right)$int64int32nag_int array
Details of the column interchanges.
5:     $\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$
The rank of $A$ is less than $n$; the problem does not have a unique solution.
${\mathbf{ifail}}=2$
The iterative refinement fails to converge, i.e., the matrix $A$ is too ill-conditioned.
${\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

Although the correction process is continued until the solution has converged to full machine accuracy, all the figures in the final solution may not be correct since the correction $D$ to $X$ is itself the solution to a linear least squares problem. For a detailed error analysis see page 116 of Wilkinson and Reinsch (1971).

The time taken by nag_linsys_real_gen_lsqsol (f04am) is approximately proportional to ${n}^{2}\left(3m-n\right)$, provided $r$ is small compared with $n$.

## Example

This example calculates the accurate least squares solution of the equations
 $1.1x1+0.9x2=2.2 1.2x1+1.0x2=2.3 1.0x1+1.0x2=2.1$
```function f04am_example

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

% Least-squares solution to Ax = b, m>n
a = [1.1, 0.9;
1.2, 1;
1,   1];
b = [2.2;
2.3;
2.1];

epsilon = x02aj;
[x, qr, alpha, ipiv, ifail] = f04am( ...
a, b, epsilon);

disp('Solution');
disp(x);

```
```f04am example results

Solution
1.3010
0.7935

```