Developer Reference for Intel® oneAPI Math Kernel Library for Fortran
dcsrilut
ILUT preconditioner based on the incomplete LU factorization with a threshold of a sparse matrix.
Syntax
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(*), tolInclude Files
Fortran: mkl_rci.fi , mkl_rci.f90
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\approx B=L\cdot U,\]
where L is a lower triangular matrix with unit diagonal and U is an upper triangular matrix with non-unit diagonal.
The following threshold criteria are used to generate the incomplete factors L and U :
the resulting entry must be greater than the matrix current row norm multiplied by the parameter tol , and
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 the set of elements of the matrix A . Its length is equal to the number of non-zero elements in the matrix A . Refer to the values array description in the Sparse Matrix Storage Format for more details.
ia
INTEGER. Array of size (n+1) containing begin indices of rows of the matrix A such that ia(i) is the index in the array a of the first non-zero element from the row i . The value of the last element minus one ia(n+1)-1, is equal to the number of non-zero elements in the matrix A. (Owing to the API only supporting one-based indexing.)
Refer to the rowIndex array description in the Sparse Matrix Storage Format for more details.
ja
INTEGER.
Array containing the column indices for each non-zero element of the matrix A . It is important that the indices are in increasing order per row. The matrix size is equal to the size of the array a . Refer to the columns array description in the Sparse Matrix Storage Format for more details.
tol
DOUBLE PRECISION.
Tolerance for threshold criterion for the resulting entries of the preconditioner.
maxfil
INTEGER.
Maximum fill-in, which is half of the preconditioner bandwidth. The number of non-zero elements in the rows of the preconditioner cannot exceed (2*maxfil+1) .
ipar
INTEGER.
Array of size 128 . This parameter specifies 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 that are specific to ILUT are listed below.
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® oneMKL.
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.
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® oneMKL.
Output Parameters
bilut
DOUBLE PRECISION.
Array containing non-zero 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)*n-maxfil*(maxfil+1)+1 .
ibilut
INTEGER. Array of size (n+1) containing indices of non-zero elements in the array bilut. ibilut(i) is the index of the first non-zero element from the row i. The value of the last element minus one, ibilut(n+1)-1, is equal to the number of non-zeros in the matrix B.
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 non-zero 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 (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 calculations to fail.