dcsrilut

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 11/07/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-77769EA3-8A8C-4DD8-BC0F-B07D59563BAA

View Details

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.

CAUTION:

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.

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

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.
: NOTE:

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.

NOTE:

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 (oneMKL).

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.

NOTE:

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.

NOTE:

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 (oneMKL).

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.

NOTE:

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.

Parent topic: Preconditioners based on Incomplete LU Factorization Technique

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

dcsrilut

Syntax

Include Files

Description

Input Parameters

Output Parameters

Return Values