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_square_solve_1rhs (f04at)

## Purpose

nag_linsys_real_square_solve_1rhs (f04at) calculates the accurate solution of a set of real linear equations with a single right-hand side, using an $LU$ factorization with partial pivoting, and iterative refinement.

## Syntax

[c, aa, ifail] = f04at(a, b, 'n', n)
[c, aa, ifail] = nag_linsys_real_square_solve_1rhs(a, b, 'n', n)

## Description

Given a set of real linear equations, $Ax=b$, the function first computes an $LU$ factorization of $A$ with partial pivoting, $PA=LU$, where $P$ is a permutation matrix, $L$ is lower triangular and $U$ is unit upper triangular. An approximation to $x$ is found by forward and backward substitution in $Ly=Pb$ and $Ux=y$. The residual vector $r=b-Ax$ is then calculated using additional precision, and a correction $d$ to $x$ is found by solving $LUd=r$. $x$ is replaced by $x+d$, and this iterative refinement of the solution is repeated until full machine accuracy is 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},:\right)$ – double array
The first dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\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 $n$ by $n$ matrix $A$.
2:     $\mathrm{b}\left(:\right)$ – double array
The dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The right-hand side vector $b$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array a and the second dimension of the arrays a, b.
$n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{c}\left({\mathbf{n}}\right)$ – double array
The solution vector $x$.
2:     $\mathrm{aa}\left(\mathit{ldaa},{\mathbf{n}}\right)$ – double array
The first dimension of the array aa will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array aa will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The triangular factors $L$ and $U$, except that the unit diagonal elements of $U$ are not stored.
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$
The matrix $A$ is singular, possibly due to rounding errors.
${\mathbf{ifail}}=2$
Iterative refinement fails to improve the solution, i.e., the matrix $A$ is too ill-conditioned.
${\mathbf{ifail}}=3$
 On entry, ${\mathbf{n}}<0$, or $\mathit{lda}<\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$, or $\mathit{ldaa}<\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
${\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 solutions should be correct to full machine accuracy. For a detailed error analysis see page 107 of Wilkinson and Reinsch (1971).

The time taken by nag_linsys_real_square_solve_1rhs (f04at) is approximately proportional to ${n}^{3}$.
The function must not be called with the same name for arguments b and c.

## Example

This example solves the set of linear equations $Ax=b$ where
 $A= 33 16 72 -24 -10 -57 -8 -4 -17 and b= -359 281 85 .$
```function f04at_example

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

% Accurate solution to Ax = b, for general A
a = [  33,  16,  72;
-24, -10, -57;
-8,  -4, -17];
b = [-359;
281;
85];

[x, LU, ifail] = f04at(a, b);

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

```
```f04at example results

Solution
1
-2
-5

```