Developer Reference

  • 0.10
  • 10/21/2020
  • Public Content
Contents

dcsrilut

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

Syntax

void
dcsrilut
(
const
MKL_INT
*n
,
const
double
*a
,
const
MKL_INT
*ia
,
const
MKL_INT
*ja
,
double
*bilut
,
MKL_INT
*ibilut
,
MKL_INT
*jbilut
,
const
double
*tol
,
const
MKL_INT
*maxfil
,
const
MKL_INT
*ipar
,
const
double
*dpar
,
MKL_INT
*ierr
);
Include Files
  • mkl.h
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 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
.
This routine supports only one-based indexing of the array parameters.
Input Parameters
n
Size (number of rows or columns) of the original square
n
-by-
n
matrix
A
.
a
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
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
]
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 for more details.
ja
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
. 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.
If column indices are not stored in ascending order for each row of matrix, the result of the routine might not be correct.
tol
Tolerance for threshold criterion for the resulting entries of the preconditioner.
maxfil
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
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
[30]
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
[30]
= 0, then the calculation is stopped and the routine returns non-zero error value. Otherwise, the value of the diagonal element is set to a value determined by
dpar
[30]
(see its description below), and the calculations continue.
There is no default value for
ipar
[30]
even if the preconditioner is used within the RCI ISS context. Always set the value of this entry.
You must declare the array
ipar
with length 128. While defining the array in the code as
ipar
[30]
works, there is no guarantee of future compatibility with
Intel® oneAPI Math Kernel Library
.
dpar
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
[30]
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
[30]
multiplied by the matrix row norm.
There is no default value for
dpar
[30]
entry even if the preconditioner is used within RCI ISS context. Always set the value of this entry.
You must declare the array
dpar
with length 128. While defining the array in the code as
ipar
[30]
works, there is no guarantee of future compatibility with
Intel® oneAPI Math Kernel Library
.
Output Parameters
bilut
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
.
Provide enough memory for this array before calling the routine. Otherwise, the routine may fail to complete successfully with a correct result.
ibilut
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
ibilut
[
n
]
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 for more details.
jbilut
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
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
[30]
=0
.
ierr
=-103
Indicates that the routine was interrupted because the element
ia
[
i
]
is less than or equal to the element
ia
[
i
- 1]
(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
[30]
; it can result in instability of the calculation.
ierr
=104
The value of
dpar
[30]
is equal to 0. It can cause calculations to fail.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804