# NAG CL Interfacef11dfc (real_​gen_​precon_​bdilu)

Settings help

CL Name Style:

## 1Purpose

f11dfc computes a block diagonal incomplete $LU$ factorization of a real sparse nonsymmetric matrix, represented in coordinate storage format. The diagonal blocks may be composed of arbitrary rows and the corresponding columns, and may overlap. This factorization can be used to provide a block Jacobi or additive Schwarz preconditioner, for use in combination with f11bec or f11dgc.

## 2Specification

 #include
 void f11dfc (Integer n, Integer nnz, double a[], Integer la, Integer irow[], Integer icol[], Integer nb, const Integer istb[], const Integer indb[], Integer lindb, const Integer lfill[], const double dtol[], const Nag_SparseNsym_Piv pstrat[], const Nag_SparseNsym_Fact milu[], Integer ipivp[], Integer ipivq[], Integer istr[], Integer idiag[], Integer *nnzc, Integer npivm[], NagError *fail)
The function may be called by the names: f11dfc, nag_sparse_real_gen_precon_bdilu or nag_sparse_nsym_precon_bdilu.

## 3Description

f11dfc computes an incomplete $LU$ factorization (see Meijerink and Van der Vorst (1977) and Meijerink and Van der Vorst (1981)) of the (possibly overlapping) diagonal blocks ${A}_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$, of a real sparse nonsymmetric $n×n$ matrix $A$. The factorization is intended primarily for use as a block Jacobi or additive Schwarz preconditioner (see Saad (1996)), with one of the iterative solvers f11bec and f11dgc.
The nb diagonal blocks need not consist of consecutive rows and columns of $A$, but may be composed of arbitrarily indexed rows, and the corresponding columns, as defined in the arguments indb and istb. Any given row or column index may appear in more than one diagonal block, resulting in overlap. Each diagonal block ${A}_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$, is factorized as:
 $Ab = Mb+Rb$
where
 $Mb = Pb Lb Db Ub Qb$
and ${L}_{b}$ is lower triangular with unit diagonal elements, ${D}_{b}$ is diagonal, ${U}_{b}$ is upper triangular with unit diagonals, ${P}_{b}$ and ${Q}_{b}$ are permutation matrices, and ${R}_{b}$ is a remainder matrix.
The amount of fill-in occurring in the factorization of block $b$ can vary from zero to complete fill, and can be controlled by specifying either the maximum level of fill ${\mathbf{lfill}}\left[b-1\right]$, or the drop tolerance ${\mathbf{dtol}}\left[b-1\right]$.
The parameter ${\mathbf{pstrat}}\left[b-1\right]$ defines the pivoting strategy to be used in block $b$. The options currently available are no pivoting, user-defined pivoting, partial pivoting by columns for stability, and complete pivoting by rows for sparsity and by columns for stability. The factorization may optionally be modified to preserve the row-sums of the original block matrix.
The sparse matrix $A$ is represented in coordinate storage (CS) format (see Section 2.1.1 in the F11 Chapter Introduction). The array a stores all the nonzero elements of the matrix $A$, while arrays irow and icol store the corresponding row and column indices respectively. Multiple nonzero elements may not be specified for the same row and column index.
The preconditioning matrices ${M}_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$, are returned in terms of the CS representations of the matrices
 $Cb = Lb + D-1b + Ub -2I .$

## 4References

Meijerink J and Van der Vorst H (1977) An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix Math. Comput. 31 148–162
Meijerink J and Van der Vorst H (1981) Guidelines for the usage of incomplete decompositions in solving sets of linear equations as they occur in practical problems J. Comput. Phys. 44 134–155
Saad Y (1996) Iterative Methods for Sparse Linear Systems PWS Publishing Company, Boston, MA

## 5Arguments

1: $\mathbf{n}$Integer Input
On entry: $n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 1$.
2: $\mathbf{nnz}$Integer Input
On entry: the number of nonzero elements in the matrix $A$.
Constraint: $1\le {\mathbf{nnz}}\le {{\mathbf{n}}}^{2}$.
3: $\mathbf{a}\left[{\mathbf{la}}\right]$double Input/Output
On entry: the nonzero elements in the matrix $A$, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function f11zac may be used to order the elements in this way.
On exit: the first nnz entries of a contain the nonzero elements of $A$ and the next nnzc entries contain the elements of the matrices ${C}_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$ stored consecutively. Within each block the matrix elements are ordered by increasing row index, and by increasing column index within each row.
4: $\mathbf{la}$Integer Input
On entry: the dimension of the arrays a, irow and icol. These arrays must be of sufficient size to store both $A$ (nnz elements) and $C$ (nnzc elements).
Note: the minimum value for la is only appropriate if lfill and dtol are set such that minimal fill-in occurs. If this is not the case then we recommend that la is set much larger than the minimum value indicated in the constraint.
Constraint: ${\mathbf{la}}\ge 2×{\mathbf{nnz}}$.
5: $\mathbf{irow}\left[{\mathbf{la}}\right]$Integer Input/Output
6: $\mathbf{icol}\left[{\mathbf{la}}\right]$Integer Input/Output
On entry: the row and column indices of the nonzero elements supplied in a.
Constraints:
irow and icol must satisfy these constraints (which may be imposed by a call to f11zac):
• $1\le {\mathbf{irow}}\left[\mathit{i}-1\right]\le {\mathbf{n}}$ and $1\le {\mathbf{icol}}\left[\mathit{i}-1\right]\le {\mathbf{n}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{nnz}}$;
• either ${\mathbf{irow}}\left[\mathit{i}-1\right]<{\mathbf{irow}}\left[\mathit{i}\right]$ or both ${\mathbf{irow}}\left[\mathit{i}-1\right]={\mathbf{irow}}\left[\mathit{i}\right]$ and ${\mathbf{icol}}\left[\mathit{i}-1\right]<{\mathbf{icol}}\left[\mathit{i}\right]$, for $\mathit{i}=1,2,\dots ,{\mathbf{nnz}}$.
On exit: the row and column indices of the nonzero elements returned in a.
7: $\mathbf{nb}$Integer Input
On entry: the number of diagonal blocks to factorize.
Constraint: $1\le {\mathbf{nb}}\le {\mathbf{n}}$.
8: $\mathbf{istb}\left[{\mathbf{nb}}+1\right]$const Integer Input
On entry: ${\mathbf{istb}}\left[\mathit{b}-1\right]$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$, holds the indices in arrays indb, ipivp, ipivq and idiag that, on successful exit from this function, define block $\mathit{b}$. Let ${r}_{\mathit{b}}$ denote the number of rows in block $\mathit{b}$; then ${\mathbf{istb}}\left[\mathit{b}\right]={\mathbf{istb}}\left[\mathit{b}-1\right]+{r}_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$. Thus, ${\mathbf{istb}}\left[{\mathbf{nb}}\right]$ holds the sum of the number of rows in all blocks plus ${\mathbf{istb}}\left[0\right]$.
Constraint: ${\mathbf{istb}}\left[0\right]\ge 1,{\mathbf{istb}}\left[\mathit{b}-1\right]<{\mathbf{istb}}\left[\mathit{b}\right]$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$.
9: $\mathbf{indb}\left[{\mathbf{lindb}}\right]$const Integer Input
On entry: indb must hold the row indices appearing in each diagonal block, stored consecutively. Thus the elements ${\mathbf{indb}}\left[{k}_{b}-1\right]$, for ${k}_{b}={\mathbf{istb}}\left[b-1\right],{\mathbf{istb}}\left[b-1\right]+1,\dots ,{\mathbf{istb}}\left[b\right]-2,{\mathbf{istb}}\left[b\right]-1$, are the row indices in the $\mathit{b}$th block, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$.
Constraint: $1\le {\mathbf{indb}}\left[\mathit{m}-1\right]\le {\mathbf{n}}$, for $m={\mathbf{istb}}\left[0\right],{\mathbf{istb}}\left[0\right]+1,\dots ,{\mathbf{istb}}\left[{\mathbf{nb}}\right]-1$.
10: $\mathbf{lindb}$Integer Input
On entry: the dimension of the arrays indb, ipivp, ipivq and idiag.
Constraint: ${\mathbf{lindb}}\ge {\mathbf{istb}}\left[{\mathbf{nb}}\right]-1$.
11: $\mathbf{lfill}\left[{\mathbf{nb}}\right]$const Integer Input
On entry: if ${\mathbf{lfill}}\left[b-1\right]\ge 0$ its value is the maximum level of fill allowed in the decomposition of the block (see Section 9.2 in f11dac). A negative value of ${\mathbf{lfill}}\left[b-1\right]$ indicates that ${\mathbf{dtol}}\left[b-1\right]$ will be used to control the fill in the block instead.
12: $\mathbf{dtol}\left[{\mathbf{nb}}\right]$const double Input
On entry: if ${\mathbf{lfill}}\left[b-1\right]<0$ then ${\mathbf{dtol}}\left[b-1\right]$ is used as a drop tolerance in the block to control the fill-in (see Section 9.2 in f11dac); otherwise ${\mathbf{dtol}}\left[b-1\right]$ is not referenced.
Constraint: if ${\mathbf{lfill}}\left[b-1\right]<0$, ${\mathbf{dtol}}\left[\mathit{b}-1\right]\ge 0.0$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$.
13: $\mathbf{pstrat}\left[{\mathbf{nb}}\right]$const Nag_SparseNsym_Piv Input
On entry: ${\mathbf{pstrat}}\left[\mathit{b}-1\right]$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$, specifies the pivoting strategy to be adopted in the block as follows:
${\mathbf{pstrat}}\left[b-1\right]=\mathrm{Nag_SparseNsym_NoPiv}$
No pivoting is carried out.
${\mathbf{pstrat}}\left[b-1\right]=\mathrm{Nag_SparseNsym_UserPiv}$
Pivoting is carried out according to the user-defined input values of ipivp and ipivq.
${\mathbf{pstrat}}\left[b-1\right]=\mathrm{Nag_SparseNsym_PartialPiv}$
Partial pivoting by columns for stability is carried out.
${\mathbf{pstrat}}\left[b-1\right]=\mathrm{Nag_SparseNsym_CompletePiv}$
Complete pivoting by rows for sparsity, and by columns for stability, is carried out.
Suggested value: ${\mathbf{pstrat}}\left[\mathit{b}-1\right]=\mathrm{Nag_SparseNsym_CompletePiv}$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$.
Constraint: ${\mathbf{pstrat}}\left[\mathit{b}-1\right]=\mathrm{Nag_SparseNsym_NoPiv}$, $\mathrm{Nag_SparseNsym_UserPiv}$, $\mathrm{Nag_SparseNsym_PartialPiv}$ or $\mathrm{Nag_SparseNsym_CompletePiv}$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$.
14: $\mathbf{milu}\left[{\mathbf{nb}}\right]$const Nag_SparseNsym_Fact Input
On entry: ${\mathbf{milu}}\left[\mathit{b}-1\right]$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$, indicates whether or not the factorization in the block should be modified to preserve row-sums (see Section 9.4 in f11dac).
${\mathbf{milu}}\left[b-1\right]=\mathrm{Nag_SparseNsym_ModFact}$
The factorization is modified.
${\mathbf{milu}}\left[b-1\right]=\mathrm{Nag_SparseNsym_UnModFact}$
The factorization is not modified.
Constraint: ${\mathbf{milu}}\left[\mathit{b}-1\right]=\mathrm{Nag_SparseNsym_ModFact}$ or $\mathrm{Nag_SparseNsym_UnModFact}$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$.
15: $\mathbf{ipivp}\left[{\mathbf{lindb}}\right]$Integer Input/Output
16: $\mathbf{ipivq}\left[{\mathbf{lindb}}\right]$Integer Input/Output
On entry: if ${\mathbf{pstrat}}\left[b-1\right]=\mathrm{Nag_SparseNsym_UserPiv}$, ${\mathbf{ipivp}}\left[{\mathbf{istb}}\left[b-1\right]+k-2\right]$ and ${\mathbf{ipivq}}\left[{\mathbf{istb}}\left[b-1\right]+k-2\right]$ must specify the row and column indices of the element used as a pivot at elimination stage $k$ of the factorization of the block. Otherwise ipivp and ipivq need not be initialized.
Constraint: if ${\mathbf{pstrat}}\left[b-1\right]=\mathrm{Nag_SparseNsym_UserPiv}$, the elements ${\mathbf{istb}}\left[b-1\right]-1$ to ${\mathbf{istb}}\left[b\right]-2$ of ipivp and ipivq must both hold valid permutations of the integers on $\left[1,{\mathbf{istb}}\left[b\right]-{\mathbf{istb}}\left[b-1\right]\right]$.
On exit: the row and column indices of the pivot elements, arranged consecutively for each block, as for indb. If ${\mathbf{ipivp}}\left[{\mathbf{istb}}\left[b-1\right]+k-2\right]=i$ and ${\mathbf{ipivq}}\left[{\mathbf{istb}}\left[b-1\right]+k-2\right]=j$, the element in row $i$ and column $j$ of ${A}_{b}$ was used as the pivot at elimination stage $k$.
17: $\mathbf{istr}\left[{\mathbf{lindb}}+1\right]$Integer Output
On exit: ${\mathbf{istr}}\left[{\mathbf{istb}}\left[\mathit{b}-1\right]+\mathit{k}-2\right]$, gives the index in the arrays a, irow and icol of row $\mathit{k}$ of the matrix ${C}_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$ and $\mathit{k}=1,2,\dots ,{\mathbf{istb}}\left[\mathit{b}\right]-{\mathbf{istb}}\left[\mathit{b}-1\right]$.
${\mathbf{istr}}\left[{\mathbf{istb}}\left[{\mathbf{nb}}\right]-1\right]$ contains ${\mathbf{nnz}}+{\mathbf{nnzc}}+1$.
18: $\mathbf{idiag}\left[{\mathbf{lindb}}\right]$Integer Output
On exit: ${\mathbf{idiag}}\left[{\mathbf{istb}}\left[\mathit{b}-1\right]+\mathit{k}-2\right]$, gives the index in the arrays a, irow and icol of the diagonal element in row $\mathit{k}$ of the matrix ${C}_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$ and $\mathit{k}=1,2,\dots ,{\mathbf{istb}}\left[\mathit{b}\right]-{\mathbf{istb}}\left[\mathit{b}-1\right]$.
19: $\mathbf{nnzc}$Integer * Output
On exit: the sum total number of nonzero elements in the matrices ${C}_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$.
20: $\mathbf{npivm}\left[{\mathbf{nb}}\right]$Integer Output
On exit: if ${\mathbf{npivm}}\left[b-1\right]>0$ it gives the number of pivots which were modified during the factorization to ensure that ${M}_{b}$ exists.
If ${\mathbf{npivm}}\left[\mathit{b}-1\right]=-1$ no pivot modifications were required, but a local restart occurred (see Section 9.3 in f11dac). The quality of the preconditioner will generally depend on the returned values of ${\mathbf{npivm}}\left[\mathit{b}-1\right]$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$.
If ${\mathbf{npivm}}\left[b-1\right]$ is large, for some block, the preconditioner may not be satisfactory. In this case it may be advantageous to call f11dfc again with an increased value of ${\mathbf{lfill}}\left[b-1\right]$, a reduced value of ${\mathbf{dtol}}\left[b-1\right]$, or ${\mathbf{pstrat}}\left[b-1\right]=\mathrm{Nag_SparseNsym_CompletePiv}$.
21: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_INT
On entry, ${\mathbf{istb}}\left[0\right]=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{istb}}\left[0\right]\ge 1$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 1$.
On entry, ${\mathbf{nnz}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nnz}}\ge 1$.
NE_INT_2
On entry, ${\mathbf{la}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{nnz}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{la}}\ge 2×{\mathbf{nnz}}$.
On entry, ${\mathbf{nb}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{nb}}\le {\mathbf{n}}$.
On entry, ${\mathbf{nnz}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nnz}}\le {{\mathbf{n}}}^{2}$.
NE_INT_3
On entry, ${\mathbf{lindb}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{istb}}\left[{\mathbf{nb}}\right]-1=⟨\mathit{\text{value}}⟩$ and ${\mathbf{nb}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{lindb}}\ge {\mathbf{istb}}\left[{\mathbf{nb}}\right]-1$.
NE_INT_ARRAY
On entry, ${\mathbf{indb}}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{indb}}\left[m-1\right]\le {\mathbf{n}}$, for $m={\mathbf{istb}}\left[0\right],{\mathbf{istb}}\left[0\right]+1,\dots ,{\mathbf{istb}}\left[{\mathbf{nb}}\right]-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.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_INVALID_CS
On entry, ${\mathbf{icol}}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{icol}}\left[\mathit{j}-1\right]\le {\mathbf{n}}$, for $\mathit{j}=1,2,\dots ,{\mathbf{nnz}}$.
On entry, ${\mathbf{irow}}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{irow}}\left[\mathit{i}-1\right]\le {\mathbf{n}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{nnz}}$.
NE_INVALID_ROWCOL_PIVOT
On entry, the user-supplied value of ipivp for block $⟨\mathit{\text{value}}⟩$ lies outside its range.
On entry, the user-supplied value of ipivp for block $⟨\mathit{\text{value}}⟩$ was repeated.
On entry, the user-supplied value of ipivq for block $⟨\mathit{\text{value}}⟩$ lies outside its range.
On entry, the user-supplied value of ipivq for block $⟨\mathit{\text{value}}⟩$ was repeated.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_NOT_STRICTLY_INCREASING
On entry, element $⟨\mathit{\text{value}}⟩$ of a was out of order.
On entry, for $b=⟨\mathit{\text{value}}⟩$, ${\mathbf{istb}}\left[b\right]=⟨\mathit{\text{value}}⟩$ and ${\mathbf{istb}}\left[b-1\right]=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{istb}}\left[\mathit{b}\right]>{\mathbf{istb}}\left[\mathit{b}-1\right]$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$.
On entry, location $⟨\mathit{\text{value}}⟩$ of $\left({\mathbf{irow}},{\mathbf{icol}}\right)$ was a duplicate.
NE_REAL_ARRAY
On entry, ${\mathbf{dtol}}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{dtol}}\left[\mathit{b}-1\right]\ge 0.0$, for $\mathit{b}=1,2,\dots ,{\mathbf{nb}}$.
NE_TOO_SMALL
The number of nonzero entries in the decomposition is too large.
The decomposition has been terminated before completion.
Either increase la, or reduce the fill by reducing lfill, or increasing dtol.

## 7Accuracy

The accuracy of the factorization of each block ${A}_{b}$ will be determined by the size of the elements that are dropped and the size of any modifications made to the pivot elements. If these sizes are small then the computed factors will correspond to a matrix close to ${A}_{b}$. The factorization can generally be made more accurate by increasing the level of fill ${\mathbf{lfill}}\left[b-1\right]$, or by reducing the drop tolerance ${\mathbf{dtol}}\left[b-1\right]$ with ${\mathbf{lfill}}\left[b-1\right]<0$.
If f11dfc is used in combination with f11bec or f11dgc, the more accurate the factorization the fewer iterations will be required. However, the cost of the decomposition will also generally increase.

## 8Parallelism and Performance

f11dfc is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

f11dfc calls f11dac internally for each block ${A}_{b}$. The comments and advice provided in Section 9 in f11dac on timing, control of fill, algorithmic details, and choice of parameters, are all therefore, relevant to f11dfc, if interpreted blockwise.

## 10Example

This example program reads in a sparse matrix $A$ and then defines a block partitioning of the row indices with a user-supplied overlap and computes an overlapping incomplete $LU$ factorization suitable for use as an additive Schwarz preconditioner. Such a factorization is used for this purpose in the example program of f11dgc.

### 10.1Program Text

Program Text (f11dfce.c)

### 10.2Program Data

Program Data (f11dfce.d)

### 10.3Program Results

Program Results (f11dfce.r)