f11 Chapter Contents
f11 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_sparse_nherm_precon_ilu_solve (f11dpc)

## 1  Purpose

nag_sparse_nherm_precon_ilu_solve (f11dpc) solves a system of complex linear equations involving the incomplete $LU$ preconditioning matrix generated by nag_sparse_nherm_fac (f11dnc).

## 2  Specification

 #include #include
 void nag_sparse_nherm_precon_ilu_solve (Nag_TransType trans, Integer n, const Complex 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 Complex y[], Complex x[], NagError *fail)

## 3  Description

nag_sparse_nherm_precon_ilu_solve (f11dpc) solves a system of complex 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 complex sparse matrix stored in coordinate storage (CS) format (see Section 2.1.1 in the f11 Chapter Introduction), as generated by nag_sparse_nherm_fac (f11dnc).
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_nherm_precon_ilu_solve (f11dpc) 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_nherm_fac (f11dnc). The permutation matrices $P$ and $Q$ are returned from nag_sparse_nherm_fac (f11dnc) via the arrays ipivp and ipivq.
It is envisaged that a common use of nag_sparse_nherm_precon_ilu_solve (f11dpc) will be to carry out the preconditioning step required in the application of nag_sparse_nherm_basic_solver (f11bsc) to sparse complex linear systems. nag_sparse_nherm_precon_ilu_solve (f11dpc) is used for this purpose by the Black Box function nag_sparse_nherm_fac_sol (f11dqc).
nag_sparse_nherm_precon_ilu_solve (f11dpc) may also be used in combination with nag_sparse_nherm_fac (f11dnc) to solve a sparse system of complex linear equations directly (see Section 8.5 in nag_sparse_nherm_fac (f11dnc)). This use of nag_sparse_nherm_precon_ilu_solve (f11dpc) is illustrated in Section 9.

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_nherm_fac (f11dnc).
Constraint: ${\mathbf{n}}\ge 1$.
3:     a[la]const ComplexInput
On entry: the values returned in the array a by a previous call to nag_sparse_nherm_fac (f11dnc).
4:     laIntegerInput
On entry: the dimension of the arrays a, irow and icol. This must be the same value supplied in the preceding call to nag_sparse_nherm_fac (f11dnc).
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_nherm_fac (f11dnc).
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 ComplexInput
On entry: the right-hand side vector $y$.
13:   x[n]ComplexOutput
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}}〉$, ${\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_nherm_fac (f11dnc) and nag_sparse_nherm_precon_ilu_solve (f11dpc).
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_nherm_fac (f11dnc) and nag_sparse_nherm_precon_ilu_solve (f11dpc).
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_nherm_fac (f11dnc) and nag_sparse_nherm_precon_ilu_solve (f11dpc).
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_nherm_fac (f11dnc) and nag_sparse_nherm_precon_ilu_solve (f11dpc).
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_nherm_fac (f11dnc) and nag_sparse_nherm_precon_ilu_solve (f11dpc).
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_nherm_fac (f11dnc) and nag_sparse_nherm_precon_ilu_solve (f11dpc).
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_nherm_fac (f11dnc) and nag_sparse_nherm_precon_ilu_solve (f11dpc).
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_nherm_fac (f11dnc) and nag_sparse_nherm_precon_ilu_solve (f11dpc).
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_nherm_fac (f11dnc) and nag_sparse_nherm_precon_ilu_solve (f11dpc).
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_nherm_fac (f11dnc) and nag_sparse_nherm_precon_ilu_solve (f11dpc).
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_nherm_fac (f11dnc) and nag_sparse_nherm_precon_ilu_solve (f11dpc).

## 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.1  Timing

The time taken for a call to nag_sparse_nherm_precon_ilu_solve (f11dpc) is proportional to the value of nnzc returned from nag_sparse_nherm_fac (f11dnc).

### 8.2  Use of check

It is expected that a common use of nag_sparse_nherm_precon_ilu_solve (f11dpc) will be to carry out the preconditioning step required in the application of nag_sparse_nherm_basic_solver (f11bsc) to sparse complex linear systems. In this situation nag_sparse_nherm_precon_ilu_solve (f11dpc) 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 to set ${\mathbf{check}}=\mathrm{Nag_SparseNsym_NoCheck}$ for all subsequent calls.

## 9  Example

This example reads in a complex sparse non-Hermitian matrix $A$ and a vector $y$. It then calls nag_sparse_nherm_fac (f11dnc), with ${\mathbf{lfill}}=-1$ and ${\mathbf{dtol}}=0.0$, to compute the complete $LU$ decomposition
 $A=PLDUQ.$
Finally it calls nag_sparse_nherm_precon_ilu_solve (f11dpc) to solve the system
 $PLDUQx=y.$

### 9.1  Program Text

Program Text (f11dpce.c)

### 9.2  Program Data

Program Data (f11dpce.d)

### 9.3  Program Results

Program Results (f11dpce.r)