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_dgesv (f07aa)

## Purpose

nag_lapack_dgesv (f07aa) computes the solution to a real system of linear equations
 $AX=B ,$
where $A$ is an $n$ by $n$ matrix and $X$ and $B$ are $n$ by $r$ matrices.

## Syntax

[a, ipiv, b, info] = f07aa(a, b, 'n', n, 'nrhs_p', nrhs_p)
[a, ipiv, b, info] = nag_lapack_dgesv(a, b, 'n', n, 'nrhs_p', nrhs_p)

## Description

nag_lapack_dgesv (f07aa) uses the $LU$ decomposition with partial pivoting and row interchanges to factor $A$ as
 $A=PLU ,$
where $P$ is a permutation matrix, $L$ is unit lower triangular, and $U$ is upper triangular. The factored form of $A$ is then used to solve the system of equations $AX=B$.

## References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
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{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$ coefficient matrix $A$.
2:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double array
The first dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{nrhs_p}}\right)$.
The $n$ by $r$ right-hand side matrix $B$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array b.
$n$, the number of linear equations, i.e., the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
2:     $\mathrm{nrhs_p}$int64int32nag_int scalar
Default: the second dimension of the array b.
$r$, the number of right-hand sides, i.e., the number of columns of the matrix $B$.
Constraint: ${\mathbf{nrhs_p}}\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{n}}\right)$.
The second dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The factors $L$ and $U$ from the factorization $A=PLU$; the unit diagonal elements of $L$ are not stored.
2:     $\mathrm{ipiv}\left({\mathbf{n}}\right)$int64int32nag_int array
If no constraints are violated, the pivot indices that define the permutation matrix $P$; at the $i$th step row $i$ of the matrix was interchanged with row ${\mathbf{ipiv}}\left(i\right)$. ${\mathbf{ipiv}}\left(i\right)=i$ indicates a row interchange was not required.
3:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double array
The first dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{nrhs_p}}\right)$.
If ${\mathbf{info}}={\mathbf{0}}$, the $n$ by $r$ solution matrix $X$.
4:     $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

${\mathbf{info}}<0$
If ${\mathbf{info}}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.
W  ${\mathbf{info}}>0$
Element $_$ of the diagonal is exactly zero. The factorization has been completed, but the factor $U$ is exactly singular, so the solution could not be computed.

## Accuracy

The computed solution for a single right-hand side, $\stackrel{^}{x}$, satisfies the equation of the form
 $A+E x^=b ,$
where
 $E1 = Oε A1$
and $\epsilon$ is the machine precision. An approximate error bound for the computed solution is given by
 $x^ - x 1 x 1 ≤ κA E 1 A 1$
where $\kappa \left(A\right)={‖{A}^{-1}‖}_{1}{‖A‖}_{1}$, the condition number of $A$ with respect to the solution of the linear equations. See Section 4.4 of Anderson et al. (1999) for further details.
Following the use of nag_lapack_dgesv (f07aa), nag_lapack_dgecon (f07ag) can be used to estimate the condition number of $A$ and nag_lapack_dgerfs (f07ah) can be used to obtain approximate error bounds. Alternatives to nag_lapack_dgesv (f07aa), which return condition and error estimates directly are nag_linsys_real_square_solve (f04ba) and nag_lapack_dgesvx (f07ab).

The total number of floating-point operations is approximately $\frac{2}{3}{n}^{3}+2{n}^{2}r$, where $r$ is the number of right-hand sides.
The complex analogue of this function is nag_lapack_zgesv (f07an).

## Example

This example solves the equations
 $Ax = b ,$
where $A$ is the general matrix
 $A = 1.80 2.88 2.05 -0.89 5.25 -2.95 -0.95 -3.80 1.58 -2.69 -2.90 -1.04 -1.11 -0.66 -0.59 0.80 and b = 9.52 24.35 0.77 -6.22 .$
Details of the $LU$ factorization of $A$ are also output.
```function f07aa_example

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

% Linear system
a = [ 1.80,  2.88,  2.05, -0.89;
5.25, -2.95, -0.95, -3.80;
1.58, -2.69, -2.90, -1.04;
-1.11, -0.66, -0.59,  0.80];
b = [ 9.52;
24.35;
0.77;
-6.22];

% Solve
[LU, ipiv, x, info] = f07aa(a, b);

disp('Solution');
disp(x');
disp('Details of factorization');
disp(LU);
disp('Pivot indices');
disp(double(ipiv'));

```
```f07aa example results

Solution
1.0000   -1.0000    3.0000   -5.0000

Details of factorization
5.2500   -2.9500   -0.9500   -3.8000
0.3429    3.8914    2.3757    0.4129
0.3010   -0.4631   -1.5139    0.2948
-0.2114   -0.3299    0.0047    0.1314

Pivot indices
2     2     3     4

```