# dcsrilut

ILUT preconditioner based on the incomplete LU factorization with a threshold of a sparse matrix.

## Syntax

Fortran:

call dcsrilut(n, a, ia, ja, bilut, bilut, ibilut, jbilut, tol, maxfil, ipar, dpar, ierr)

C:

dcsrilut(&n, a, ia, ja, bilut, bilut, ibilut, jbilut, &tol, &maxfil, ipar, dpar, &ierr);

## 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 low triangular matrix with unit diagonal, U is an upper triangular matrix with non-unit 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 non-zero elements in each row of the resulting L and U factors must not be greater than the value of the parameter maxfil.

## Input Parameters

n

  INTEGER. Size (number of rows or columns) of the original square n-by-n matrix A.

a

  DOUBLE PRECISION. Array containing all non-zero 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 non-zero elements in the array A. `ia(I)`is the index of the first non-zero element from the row `I`. The value of the last element `ia(n+1)` is equal to the number of non-zeros in the matrix A plus one. Refer to the rowIndex array description in the Sparse Matrix Storage Format section for more details.

ja

  INTEGER. Array of size equal to the size of the array a. This array contains the column numbers for each non-zero element of the matrix A. Refer to the columns array description in the Sparse Matrix Storage Format section for more details.

  ### Note

  Column numbers must be in increasing order for each row of matrix.

tol

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

maxfil

  INTEGER. Maximum fill-in, half of the preconditioner bandwidth. The number of non-zero elements in the rows of the preconditioner can not 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 non-zero error value. Otherwise, the value of the diagonal element is set to the certain value (see description of the parameter dpar(31) below), and the calculation continues.

    ### Note

    There is no default value for `ipar(31)` entry even if the preconditioner is used within the RCI ISS context. Always set the value of this entry.

  ### Note

  Advanced users can define this array in the code as `INTEGER ipar(31)`. However, to guarantee the compatibility with the future releases of the Intel MKL, declare the array ipar of length 128.

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)

    - specifies the value that being multiplied by the matrix row norm is assigned to those diagonal elements whose value is less than the matrix row norm multiplied by the value of the parameter tol, if the calculation is not stopped in accordance with ipar(31).

    ### 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

  Advanced users can define this array in the code as `DOUBLE PRECISION dpar(31)`. However, to guarantee the compatibility with the future releases of the Intel MKL, declare the array dpar of length 128.

## Output Parameters

bilut

  DOUBLE PRECISION. Array B containing non-zero elements of the resulting preconditioning matrix, stored format accepted in the direct sparse solvers. Refer to the values array description in the Sparse Matrix Storage Format section for more details. The size of the array is equal to `(2*maxfil+1)*n-maxfil*(maxfil+1)+1`.

  ### Note

  Provide enough memory for this array before calling the roitune. Otherwise, the routine may fail to complete successfully with a correct result.

ibilut

  INTEGER. Array of size `(n+1)` containing indices of non-zero elements in the array B. `ibilut(I)` is the index of the first non-zero element from the row `I`. The value of the last element `ibilut(n+1)` is equal to the number of non-zeros in the matrix B plus one. Refer to the rowIndex array description in the Sparse Matrix Storage Format section 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 non-zero element of the matrix B. Refer to the columns array description in the Sparse Matrix Storage Format section for more details.

ierr

  INTEGER. Error flag, informs about the routine completion.

## Return Values

`ierr=0`

  The routine completes the task normally.

`ierr=-101`

  The routine is interrupted, the error occurs: the number of elements in some matrix row specified in the sparse format is equal to or less than 0.

`ierr=-102`

  The routine is 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`

  The routine is interrupted, the error occurs: the element `ia(I+1)` is less than or equal to the element `ia(I)` (see Sparse Matrix Storage Format section).

`ierr=-104`

  The routine is interrupted because the memory is insufficient for the internal work arrays.

`ierr=-105`

  The routine is interrupted because the input value of maxfil is less than 0.

`ierr=-106`

  The routine is interrupted because the size n of the input matrix is less than 0.

`ierr=-107`

  The routine is interrupted, the error occurs: an element of the array ja is less than 0, or greater than n (see Sparse Matrix Storage Format section).

`ierr=101`

  The value of maxfil is greater than or equal to n. The calculation is performed with the value of maxfil set to `(n-1)`.

`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 the fail of the calculations.

## Interfaces

## FORTRAN 77 and Fortran 95:

SUBROUTINE dcsrilut (n, a, ia, ja, bilut, ibilut, jbilut, tol, maxfil, ipar, dpar, ierr)

INTEGER n, ierr, ipar(*), maxfil

INTEGER ia(*), ja(*), ibilut(*), jbilut(*)

DOUBLE PRECISION a(*), bilut(*), dpar(*), tol

## C:

`void dcsrilut (int *n, double *a, int *ia, int *ja, double *bilut, int *ibilut, int *jbilut, double *tol, int *maxfil, int *ipar, double *dpar, int *ierr);`
Parent topic: Preconditioners based on Incomplete LU Factorization Technique