rocsparse_scsrilu0 Interface Reference

rocsparse_scsrilu0 Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_scsrilu0 Interface Reference

Incomplete LU factorization with 0 fill-ins and no pivoting using the CSR storage format. More...

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_scsrilu0_ (handle, m, nnz, descr, csr_val, csr_row_ptr, csr_col_ind, myinfo, policy, temp_buffer)

integer(kind(rocsparse_status_success)) function	rocsparse_scsrilu0_rank_0 (handle, m, nnz, descr, csr_val, csr_row_ptr, csr_col_ind, myinfo, policy, temp_buffer)

integer(kind(rocsparse_status_success)) function	rocsparse_scsrilu0_rank_1 (handle, m, nnz, descr, csr_val, csr_row_ptr, csr_col_ind, myinfo, policy, temp_buffer)

Detailed Description

Incomplete LU factorization with 0 fill-ins and no pivoting using the CSR storage format.

rocsparse_csrilu0 computes the incomplete LU factorization with 0 fill-ins and no pivoting of a sparse \(m \times m\) CSR matrix \(A\), such that

\[ A \approx LU \]

where the lower triangular matrix \(L\) and the upper triangular matrix \(U\) are computed using:

\[ \begin{array}{ll} L_{ij} = \frac{1}{U_{jj}}(A_{ij} - \sum_{k=0}^{j-1}L_{ik} \times U_{kj}), & \text{if i > j} \\% U_{ij} = (A_{ij} - \sum_{k=0}^{j-1}L_{ik} \times U_{kj}), & \text{if i <= j} \end{array} \]

for each entry found in the CSR matrix \(A\).

Computing the above incomplete \(LU\) factorization requires three steps to complete. First, determine the size of the required temporary storage buffer by calling rocsparse_Xcsrilu0_buffer_size(). After this buffer size has been determined, allocate the buffer and pass it to rocsparse_Xcsrilu0_analysis(). This will perform analysis on the sparsity pattern of the matrix. Finally, call rocsparse_scsrilu0, rocsparse_dcsrilu0, rocsparse_ccsrilu0, or rocsparse_zcsrilu0 to perform the actual factorization. The calculation of the buffer size and the analysis of the sparse matrix only need to be performed once for a given sparsity pattern while the factorization can be repeatedly applied to multiple matrices having the same sparsity pattern. After all calls to rocsparse_Xcsrilu0() are complete, the temporary buffer can be deallocated.

When computing the \(LU\) factorization, it is possible that \(U_{jj} == 0\), which would result in a division by zero. This could occur from either \(A_{jj}\) not existing in the sparse CSR matrix (referred to as a structural zero) or because \(A_{ij} - \sum_{k=0}^{j-1}L_{ik} \times U_{kj} == 0\) (referred to as a numerical zero). For example, running the \(LU\) factorization on the following matrix:

\[ \begin{bmatrix} 2 & 1 & 0 \\% 1 & 2 & 1 \\% 0 & 1 & 2 \end{bmatrix} \]

results in a successful \(LU\) factorization. However, running with the matrix:

\[ \begin{bmatrix} 2 & 1 & 0 \\% 1 & 1/2 & 1 \\% 0 & 1 & 2 \end{bmatrix} \]

results in a numerical zero because:

\[ \begin{array}{ll} U_{00} &= 2 \\% U_{01} &= 1 \\% L_{10} &= \frac{1}{2} \\% U_{11} &= \frac{1}{2} - \frac{1}{2} &= 0 \end{array} \]

The user can detect the presence of a structural zero by calling rocsparse_csrilu0_zero_pivot () after rocsparse_Xcsrilu0_analysis() and/or the presence of a structural or numerical zero by calling rocsparse_csrilu0_zero_pivot () after rocsparse_Xcsric0(). In both cases, rocsparse_csrilu0_zero_pivot () will report the first zero pivot (either numerical or structural) found. See the example below. The user can also set the diagonal type to be \(1\) using rocsparse_set_mat_diag_type (), which will interpret the matrix \(A\) as having ones on its diagonal (even if no non-zero exists in the sparsity pattern).

rocsparse_csrilu0 computes the \(LU\) factorization inplace, meaning that the values array csr_val of the \(A\) matrix is overwritten with the \(L\) matrix stored in the strictly lower triangular part of \(A\) and the \(U\) matrix stored in the upper part of \(A\):

\[ \begin{align} \begin{bmatrix} a_{00} & a_{01} & a_{02} \\% a_{10} & a_{11} & a_{12} \\% a_{20} & a_{21} & a_{22} \end{bmatrix} \rightarrow \begin{bmatrix} u_{00} & u_{01} & u_{02} \\% l_{10} & u_{11} & u_{12} \\% l_{20} & l_{21} & u_{22} \end{bmatrix} \end{align} \]

The row pointer array csr_row_ptr and the column indices array csr_col_ind remain the same for \(A\) and \(LU\), as the incomplete factorization does not generate new non-zeros in \(LU\) which do not already exist in \(A\).

The performance of computing \(LU\) factorization with rocSPARSE greatly depends on the sparsity pattern the the matrix \(A\), as this is what determines the amount of parallelism available.

Note: The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().; This function is non-blocking and executed asynchronously with respect to the host. It can return before the actual computation has finished.; This routine supports execution in a hipGraph context.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	m	- number of rows of the sparse CSR matrix.
[in]	nnz	- number of non-zero entries of the sparse CSR matrix.
[in]	descr	- descriptor of the sparse CSR matrix.
[in,out]	csr_val	- array of `nnz` elements of the sparse CSR matrix.
[in]	csr_row_ptr	- array of `m+1` elements that point to the start of every row of the sparse CSR matrix.
[in]	csr_col_ind	- array of `nnz` elements containing the column indices of the sparse CSR matrix.
[in]	myInfo	- structure that holds the information collected during the analysis step.
[in]	policy	- `rocsparse_solve_policy_auto`.
[in]	temp_buffer	- temporary storage buffer allocated by the user.

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_handle	the library context was not initialized.
rocsparse_status_invalid_size	`m` or `nnz` is invalid.
rocsparse_status_invalid_pointer	`descr`, `csr_val`, `csr_row_ptr`, or `csr_col_ind` pointer is invalid.
rocsparse_status_arch_mismatch	the device is not supported.
rocsparse_status_internal_error	an internal error occurred.
rocsparse_status_not_implemented	`rocsparse_matrix_type` != `rocsparse_matrix_type_general`.

Example: Consider the sparse \(m \times m\) matrix \(A\), stored in CSR storage format. The following example computes the incomplete LU factorization \(M \approx LU\) and solves the preconditioned system \(My = x\).

Member Function/Subroutine Documentation