dcsrilut
ILUT preconditioner based on the incomplete LU factorization with a threshold of a sparse matrix.
Description
The routine dcsrilut computes a preconditioner B [Saad03] of a given sparse matrix A stored in the format accepted in the direct sparse solvers:
A~B=L*U
, where L is a lower triangular matrix with unit diagonal and U is an upper triangular matrix with nonunit diagonal.
The following threshold criteria are used to generate the incomplete factors L and U:
1) the resulting entry must be greater than the matrix current row norm multiplied by the parameter tol, and
2) the number of the nonzero elements in each row of the resulting L and U factors must not be greater than the value of the parameter maxfil.
Caution
This routine supports only onebased indexing of the array parameters.
Input Parameters
 n

INTEGER. Size (number of rows or columns) of the original square nbyn matrix A.
 a

DOUBLE PRECISION. Array containing all nonzero elements of the matrix A. The length of the array is equal to their number. Refer to values array description in the Sparse Matrix Storage Format section for more details.
 ia

INTEGER. Array of size
(n+1)
containing indices of nonzero elements in the array a.ia(i)
is the index of the first nonzero element from the row i. The value of the last elementia(n+1)
is equal to the number of nonzeros in the matrix A, plus one. Refer to the rowIndex array description in the Sparse Matrix Storage Format for more details.  ja

INTEGER. Array of size equal to the size of the array a. This array contains the column numbers for each nonzero element of the matrix A. It is important that the indices are in increasing order per row. Refer to the columns array description in the Sparse Matrix Storage Format for more details.
Caution
If column indices are not stored in ascending order for each row of matrix, the result of the routine might not be correct.
 tol

DOUBLE PRECISION. Tolerance for threshold criterion for the resulting entries of the preconditioner.
 maxfil

INTEGER. Maximum fillin, which is half of the preconditioner bandwidth. The number of nonzero elements in the rows of the preconditioner cannot exceed
(2*maxfil+1)
.  ipar

INTEGER. Array of size 128. This parameter is used to specify the integer set of data for both the ILUT and RCI FGMRES computations. Refer to the ipar array description in the FGMRES Common Parameters for more details on FGMRES parameter entries. The entries specific to ILUT are listed below.
 ipar
(31)

specifies how the routine operates if the value of the computed diagonal element is less than the current matrix row norm multiplied by the value of the parameter tol. If ipar
(31)
= 0, then the calculation is stopped and the routine returns nonzero error value. Otherwise, the value of the diagonal element is set to a value determined by dpar(31)
(see its description below), and the calculations continue. 
Note
There is no default value for ipar
(31)
even if the preconditioner is used within the RCI ISS context. Always set the value of this entry.
Note
You must declare the array ipar with length 128. While defining the array in the code as
INTEGER ipar
(31)
works, there is no guarantee of future compatibility with Intel MKL.  ipar
 dpar

DOUBLE PRECISION. Array of size 128. This parameter specifies the double precision set of data for both ILUT and RCI FGMRES computations. Refer to the dpar array description in the FGMRES Common Parameters for more details on FGMRES parameter entries. The entries that are specific to ILUT are listed below.
 dpar
(31)

used to adjust the value of small diagonal elements. Diagonal elements with a value less than the current matrix row norm multiplied by tol are replaced with the value of dpar
(31)
multiplied by the matrix row norm.Note
There is no default value for dpar
(31)
entry even if the preconditioner is used within RCI ISS context. Always set the value of this entry.
Note
You must declare the array dpar with length 128. While defining the array in the code as
DOUBLE PRECISION ipar
(31)
works, there is no guarantee of future compatibility with Intel MKL.  dpar
Output Parameters
 bilut

DOUBLE PRECISION. Array containing nonzero elements of the resulting preconditioning matrix B, stored in the format accepted in the direct sparse solvers. Refer to the values array description in the Sparse Matrix Storage Format for more details. The size of the array is equal to
(2*maxfil+1)*nmaxfil*(maxfil+1)+1
.Note
Provide enough memory for this array before calling the routine. Otherwise, the routine may fail to complete successfully with a correct result.
 ibilut

INTEGER. Array of size
(n+1)
containing indices of nonzero elements in the array bilut. ibilut(i)
is the index of the first nonzero element from the row i. The value of the last element ibilut(n+1)
is equal to the number of nonzeros in the matrix B, plus one. Refer to the rowIndex array description in the Sparse Matrix Storage Format for more details.  jbilut

INTEGER. Array, its size is equal to the size of the array bilut. This array contains the column numbers for each nonzero element of the matrix B. Refer to the columns array description in the Sparse Matrix Storage Format for more details.
 ierr

INTEGER. Error flag, gives information about the routine completion.
Return Values
ierr=0

Indicates that the task completed normally.
ierr=101

Indicates that the routine was interrupted because of an error: the number of elements in some matrix row specified in the sparse format is equal to or less than 0.
ierr=102

Indicates that the routine was interrupted because the value of the computed diagonal element is less than the product of the given tolerance and the current matrix row norm, and it cannot be replaced as
ipar
.(31)
=0 ierr=103

Indicates that the routine was interrupted because the element ia
(i + 1)
is less than or equal to the element ia(i)
(see Sparse Matrix Storage Format). ierr=104

Indicates that the routine was interrupted because the memory is insufficient for the internal work arrays.
ierr=105

Indicates that the routine was interrupted because the input value of maxfil is less than 0.
ierr=106

Indicates that the routine was interrupted because the size n of the input matrix is less than 0.
ierr=107

Indicates that the routine was interrupted because an element of the array ja is less than 1, or greater than n (see Sparse Matrix Storage Format).
ierr=101

The value of maxfil is greater than or equal to n. The calculation is performed with the value of maxfil set to
(n1)
. ierr=102

The value of tol is less than 0. The calculation is performed with the value of the parameter set to
(tol)
ierr=103

The absolute value of tol is greater than value of dpar
(31)
; it can result in instability of the calculation. ierr=104

The value of dpar
(31)
is equal to 0. It can cause calculations to fail.