f11 Chapter Contents
f11 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_sparse_nsym_precon_ilu_solve (f11dbc)

## 1  Purpose

nag_sparse_nsym_precon_ilu_solve (f11dbc) solves a system of linear equations involving the incomplete $LU$ preconditioning matrix generated by nag_sparse_nsym_fac (f11dac).

## 2  Specification

 #include #include
 void nag_sparse_nsym_precon_ilu_solve (Nag_TransType trans, Integer n, const double a[], Integer la, const Integer irow[], const Integer icol[], const Integer ipivp[], const Integer ipivq[], const Integer istr[], const Integer idiag[], Nag_SparseNsym_CheckData check, const double y[], double x[], NagError *fail)

## 3  Description

nag_sparse_nsym_precon_ilu_solve (f11dbc) solves a system of linear equations
 $Mx=y, or MTx=y,$
according to the value of the argument trans, where the matrix $M=PLDUQ$, corresponds to an incomplete $LU$ decomposition of a sparse matrix stored in coordinate storage (CS) format (see Section 2.1.1 in the f11 Chapter Introduction), as generated by nag_sparse_nsym_fac (f11dac).
In the above decomposition $L$ is a lower triangular sparse matrix with unit diagonal elements, $D$ is a diagonal matrix, $U$ is an upper triangular sparse matrix with unit diagonal elements and, $P$ and $Q$ are permutation matrices. $L$, $D$ and $U$ are supplied to nag_sparse_nsym_precon_ilu_solve (f11dbc) through the matrix
 $C=L+D-1+U-2I$
which is an n by n sparse matrix, stored in CS format, as returned by nag_sparse_nsym_fac (f11dac). The permutation matrices $P$ and $Q$ are returned from nag_sparse_nsym_fac (f11dac) via the arrays ipivp and ipivq.
It is envisaged that a common use of nag_sparse_nsym_precon_ilu_solve (f11dbc) will be to carry out the preconditioning step required in the application of nag_sparse_nsym_basic_solver (f11bec) to sparse linear systems. nag_sparse_nsym_precon_ilu_solve (f11dbc) is used for this purpose by the Black Box function nag_sparse_nsym_fac_sol (f11dcc).
nag_sparse_nsym_precon_ilu_solve (f11dbc) may also be used in combination with nag_sparse_nsym_fac (f11dac) to solve a sparse system of linear equations directly (see Section 9.5 in nag_sparse_nsym_fac (f11dac)). This use of nag_sparse_nsym_precon_ilu_solve (f11dbc) is demonstrated in Section 10.
None.

## 5  Arguments

1:     transNag_TransTypeInput
On entry: specifies whether or not the matrix $M$ is transposed.
${\mathbf{trans}}=\mathrm{Nag_NoTrans}$
$Mx=y$ is solved.
${\mathbf{trans}}=\mathrm{Nag_Trans}$
${M}^{\mathrm{T}}x=y$ is solved.
Constraint: ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$ or $\mathrm{Nag_Trans}$.
2:     nIntegerInput
On entry: $n$, the order of the matrix $M$. This must be the same value as was supplied in the preceding call to nag_sparse_nsym_fac (f11dac).
Constraint: ${\mathbf{n}}\ge 1$.
3:     a[la]const doubleInput
On entry: the values returned in the array a by a previous call to nag_sparse_nsym_fac (f11dac).
4:     laIntegerInput
On entry: the dimension of the arrays a, irow and icol. This must be the same value returned by the preceding call to nag_sparse_nsym_fac (f11dac).
5:     irow[la]const IntegerInput
6:     icol[la]const IntegerInput
7:     ipivp[n]const IntegerInput
8:     ipivq[n]const IntegerInput
9:     istr[${\mathbf{n}}+1$]const IntegerInput
10:   idiag[n]const IntegerInput
On entry: the values returned in arrays irow, icol, ipivp, ipivq, istr and idiag by a previous call to nag_sparse_nsym_fac (f11dac).
11:   checkNag_SparseNsym_CheckDataInput
On entry: specifies whether or not the CS representation of the matrix $M$ should be checked.
${\mathbf{check}}=\mathrm{Nag_SparseNsym_Check}$
Checks are carried on the values of n, irow, icol, ipivp, ipivq, istr and idiag.
${\mathbf{check}}=\mathrm{Nag_SparseNsym_NoCheck}$
None of these checks are carried out.
Constraint: ${\mathbf{check}}=\mathrm{Nag_SparseNsym_Check}$ or $\mathrm{Nag_SparseNsym_NoCheck}$.
12:   y[n]const doubleInput
On entry: the right-hand side vector $y$.
13:   x[n]doubleOutput
On exit: the solution vector $x$.
14:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_INT
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 1$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_INVALID_CS
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{icol}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$, and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{icol}}\left[i-1\right]\ge 1$ and ${\mathbf{icol}}\left[i-1\right]\le {\mathbf{n}}$.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{irow}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{irow}}\left[i-1\right]\ge 1$ and ${\mathbf{irow}}\left[i-1\right]\le {\mathbf{n}}$.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
NE_INVALID_CS_PRECOND
On entry, ${\mathbf{idiag}}\left[i-1\right]$ appears to be incorrect: $i=⟨\mathit{\text{value}}⟩$.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, istr appears to be invalid.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, ${\mathbf{istr}}\left[i-1\right]$ is inconsistent with irow: $i=⟨\mathit{\text{value}}⟩$.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
NE_INVALID_ROWCOL_PIVOT
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{ipivp}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ipivp}}\left[i-1\right]\ge 1$ and ${\mathbf{ipivp}}\left[i-1\right]\le {\mathbf{n}}$.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{ipivq}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ipivq}}\left[i-1\right]\ge 1$ and ${\mathbf{ipivq}}\left[i-1\right]\le {\mathbf{n}}$.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, ${\mathbf{ipivp}}\left[i-1\right]$ is a repeated value: $i=⟨\mathit{\text{value}}⟩$.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, ${\mathbf{ipivq}}\left[i-1\right]$ is a repeated value: $i=⟨\mathit{\text{value}}⟩$.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
NE_NOT_STRICTLY_INCREASING
On entry, ${\mathbf{a}}\left[i-1\right]$ is out of order: $i=⟨\mathit{\text{value}}⟩$.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, the location (${\mathbf{irow}}\left[i-1\right],{\mathbf{icol}}\left[i-1\right]$) is a duplicate: $i=⟨\mathit{\text{value}}⟩$.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).

## 7  Accuracy

If ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$ the computed solution $x$ is the exact solution of a perturbed system of equations $\left(M+\delta M\right)x=y$, where
 $δM≤cnεPLDUQ,$
$c\left(n\right)$ is a modest linear function of $n$, and $\epsilon$ is the machine precision. An equivalent result holds when ${\mathbf{trans}}=\mathrm{Nag_Trans}$.

## 8  Parallelism and Performance

Not applicable.

### 9.1  Timing

The time taken for a call to nag_sparse_nsym_precon_ilu_solve (f11dbc) is proportional to the value of nnzc returned from nag_sparse_nsym_fac (f11dac).

### 9.2  Use of check

It is expected that a common use of nag_sparse_nsym_precon_ilu_solve (f11dbc) will be to carry out the preconditioning step required in the application of nag_sparse_nsym_basic_solver (f11bec) to sparse linear systems. In this situation nag_sparse_nsym_precon_ilu_solve (f11dbc) is likely to be called many times with the same matrix $M$. In the interests of both reliability and efficiency, you are recommended to set ${\mathbf{check}}=\mathrm{Nag_SparseNsym_Check}$ for the first of such calls, and for all subsequent calls set ${\mathbf{check}}=\mathrm{Nag_SparseNsym_NoCheck}$.

## 10  Example

This example reads in a sparse nonsymmetric matrix $A$ and a vector $y$. It then calls nag_sparse_nsym_fac (f11dac), with ${\mathbf{lfill}}=-1$ and ${\mathbf{dtol}}=0.0$, to compute the complete $LU$ decomposition
 $A=PLDUQ.$
Finally it calls nag_sparse_nsym_precon_ilu_solve (f11dbc) to solve the system
 $PLDUQx=y.$

### 10.1  Program Text

Program Text (f11dbce.c)

### 10.2  Program Data

Program Data (f11dbce.d)

### 10.3  Program Results

Program Results (f11dbce.r)