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_sparse_direct_real_gen_solve (f11mf)

## Purpose

nag_sparse_direct_real_gen_solve (f11mf) solves a real sparse system of linear equations with multiple right-hand sides given an $LU$ factorization of the sparse matrix computed by nag_sparse_direct_real_gen_lu (f11me).

## Syntax

[b, ifail] = f11mf(trans, iprm, il, lval, iu, uval, b, 'n', n, 'nrhs_p', nrhs_p)
[b, ifail] = nag_sparse_direct_real_gen_solve(trans, iprm, il, lval, iu, uval, b, 'n', n, 'nrhs_p', nrhs_p)

## Description

nag_sparse_direct_real_gen_solve (f11mf) solves a real system of linear equations with multiple right-hand sides $AX=B$ or ${A}^{\mathrm{T}}X=B$, according to the value of the argument trans, where the matrix factorization ${P}_{r}A{P}_{c}=LU$ corresponds to an $LU$ decomposition of a sparse matrix stored in compressed column (Harwell–Boeing) format, as computed by nag_sparse_direct_real_gen_lu (f11me).
In the above decomposition $L$ is a lower triangular sparse matrix with unit diagonal elements and $U$ is an upper triangular sparse matrix; ${P}_{r}$ and ${P}_{c}$ are permutation matrices.

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{trans}$ – string (length ≥ 1)
Specifies whether $AX=B$ or ${A}^{\mathrm{T}}X=B$ is solved.
${\mathbf{trans}}=\text{'N'}$
$AX=B$ is solved.
${\mathbf{trans}}=\text{'T'}$
${A}^{\mathrm{T}}X=B$ is solved.
Constraint: ${\mathbf{trans}}=\text{'N'}$ or $\text{'T'}$.
2:     $\mathrm{iprm}\left(7×{\mathbf{n}}\right)$int64int32nag_int array
The column permutation which defines ${P}_{c}$, the row permutation which defines ${P}_{r}$, plus associated data structures as computed by nag_sparse_direct_real_gen_lu (f11me).
3:     $\mathrm{il}\left(:\right)$int64int32nag_int array
The dimension of the array il must be at least as large as the dimension of the array of the same name in nag_sparse_direct_real_gen_lu (f11me)
Records the sparsity pattern of matrix $L$ as computed by nag_sparse_direct_real_gen_lu (f11me).
4:     $\mathrm{lval}\left(:\right)$ – double array
The dimension of the array lval must be at least as large as the dimension of the array of the same name in nag_sparse_direct_real_gen_lu (f11me)
Records the nonzero values of matrix $L$ and some nonzero values of matrix $U$ as computed by nag_sparse_direct_real_gen_lu (f11me).
5:     $\mathrm{iu}\left(:\right)$int64int32nag_int array
The dimension of the array iu must be at least as large as the dimension of the array of the same name in nag_sparse_direct_real_gen_lu (f11me)
Records the sparsity pattern of matrix $U$ as computed by nag_sparse_direct_real_gen_lu (f11me).
6:     $\mathrm{uval}\left(:\right)$ – double array
The dimension of the array uval must be at least as large as the dimension of the array of the same name in nag_sparse_direct_real_gen_lu (f11me)
Records some nonzero values of matrix $U$ as computed by nag_sparse_direct_real_gen_lu (f11me).
7:     $\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 ${\mathbf{n}}$ by ${\mathbf{nrhs_p}}$ right-hand side matrix $B$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array b.
$n$, 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.
$\mathit{nrhs}$, the number of right-hand sides in $B$.
Constraint: ${\mathbf{nrhs_p}}\ge 0$.

### Output Parameters

1:     $\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)$.
The ${\mathbf{n}}$ by ${\mathbf{nrhs_p}}$ solution matrix $X$.
2:     $\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$
Constraint: $\mathit{ldb}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
Constraint: ${\mathbf{n}}\ge 0$.
Constraint: ${\mathbf{nrhs_p}}\ge 0$.
On entry, ${\mathbf{trans}}=_$.
Constraint: ${\mathbf{trans}}=\text{'N'}$ or $\text{'T'}$.
${\mathbf{ifail}}=2$
Incorrect row permutations in array iprm.
${\mathbf{ifail}}=3$
Incorrect column permutations in array iprm.
${\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

For each right-hand side vector $b$, the computed solution $x$ is the exact solution of a perturbed system of equations $\left(A+E\right)x=b$, where
 $E≤cnεLU,$
$c\left(n\right)$ is a modest linear function of $n$, and $\epsilon$ is the machine precision, when partial pivoting is used.
If $\stackrel{^}{x}$ is the true solution, then the computed solution $x$ satisfies a forward error bound of the form
 $x-x^∞ x∞ ≤cncondA,xε$
where $\mathrm{cond}\left(A,x\right)={‖\left|{A}^{-1}\right|\left|A\right|\left|x\right|‖}_{\infty }/{‖x‖}_{\infty }\le \mathrm{cond}\left(A\right)={‖\left|{A}^{-1}\right|\left|A\right|‖}_{\infty }\le {\kappa }_{\infty }\left(A\right)$. Note that $\mathrm{cond}\left(A,x\right)$ can be much smaller than $\mathrm{cond}\left(A\right)$, and $\mathrm{cond}\left({A}^{\mathrm{T}}\right)$ can be much larger (or smaller) than $\mathrm{cond}\left(A\right)$.
Forward and backward error bounds can be computed by calling nag_sparse_direct_real_gen_refine (f11mh), and an estimate for ${\kappa }_{\infty }\left(A\right)$ can be obtained by calling nag_sparse_direct_real_gen_cond (f11mg).

nag_sparse_direct_real_gen_solve (f11mf) may be followed by a call to nag_sparse_direct_real_gen_refine (f11mh) to refine the solution and return an error estimate.

## Example

This example solves the system of equations $AX=B$, where
 $A= 2.00 1.00 0 0 0 0 0 1.00 -1.00 0 4.00 0 1.00 0 1.00 0 0 0 1.00 2.00 0 -2.00 0 0 3.00 and B= 1.56 3.12 -0.25 -0.50 3.60 7.20 1.33 2.66 0.52 1.04 .$
Here $A$ is nonsymmetric and must first be factorized by nag_sparse_direct_real_gen_lu (f11me).
```function f11mf_example

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

% A and b
n = int64(5);
nz = int64(11);
icolzp = [int64(1); 3; 5; 7; 9; 12];
irowix = [int64(1); 3; 1; 5; 2; 3; 2; 4; 3; 4; 5];
a = [2; 4; 1; -2; 1; 1; -1; 1; 1; 2; 3];
b = [  1.56,  3.12;
-0.25, -0.50;
3.60,  7.20;
1.33,  2.66;
0.52,  1.04];

% Calculate COLAMD permutation
spec = 'M';
iprm = zeros(1, 7*n, 'int64');

[iprm, ifail] = f11md( ...
spec, n, icolzp, irowix, iprm);

% Factorise
thresh = 1;
nzlmx = int64(8*nz);
nzlumx = int64(8*nz);
nzumx = int64(8*nz);

[iprm, nzlumx, il, lval, iu, uval, nnzl, nnzu, flop, ifail] = ...
f11me( ...
n, irowix, a, iprm, thresh, nzlmx, nzlumx, nzumx);

% Solve
trans = 'N';
[x, ifail] = f11mf( ...
trans, iprm, il, lval, iu, uval, b);
disp('Solutions');
disp(x);

```
```f11mf example results

Solutions
0.7000    1.4000
0.1600    0.3200
0.5200    1.0400
0.7700    1.5400
0.2800    0.5600

```