rocsparse_scsritilu0_compute Interface Reference

rocsparse_scsritilu0_compute Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_scsritilu0_compute Interface Reference

Iterative 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_scsritilu0_compute_ (handle, alg, option, nmaxiter, tol, m, nnz, csr_row_ptr, csr_col_ind, csr_val, ilu0, idx_base, buffer_size, buffer)

Detailed Description

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

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

\[ A \approx (L + Id)(D + U) \]

The following notation applies for the equations below: diag is the diagonal part, lower is the strict lower triangular part, and upper is the strict upper triangular part of a given matrix. Starting with \(L_{0} = lower(\) ilu0 \()\) and \(U_{0} = upper(\) ilu0 \()\), the method iterates with

\[ \begin{eqnarray} R_k &=& A - L_{k} U_{k},\\% D_{k+1} &=& diag(R_k),\\% L_{k+1} &=& lower(R_k) D_{k+1}^{-1},\\% U_{k+1} &=& upper(R_k), \end{eqnarray} \]

if \( 0 ≤ k \lt \) nmaxiter and if

\[ \Vert R_k \Vert_{\infty} \gt \epsilon \Vert A \Vert_{\infty}, \]

with \(\epsilon\) = tol. Note that the calculation of \(R_k\) is performed with no fill-in.

Computing the above iterative incomplete LU factorization requires three steps to complete. First, determine the size of the required temporary storage buffer by calling rocsparse_csritilu0_buffer_size. After this buffer size has been determined, allocate the buffer and pass it to rocsparse_csritilu0_preprocess. This will perform analysis on the sparsity pattern of the matrix. Finally, call rocsparse_scsritilu0_compute, rocsparse_dcsritilu0_compute, rocsparse_ccsritilu0_compute, or rocsparse_zcsritilu0_compute 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_Xcsritilu0_compute() are complete, the temporary buffer can be deallocated.

rocsparse_csritilu0 has a number of options that can be useful for examining the convergence history, easily printing debug information, and using the COO internal format.

Options
Option	Notes
rocsparse_itilu0_option_verbose	Print to stdout convergence data as the routine runs. Useful for debugging.
rocsparse_itilu0_option_stopping_criteria	Enable stopping criteria.
rocsparse_itilu0_option_compute_nrm_correction	Compute and store normalized correction. The stored data can then be queried later with rocsparse_Xcsritilu0_history.
rocsparse_itilu0_option_compute_nrm_residual	Compute and store the normalized residual of the between the approximate solution and the exact solution per iteration. The stored data can then be queried later with rocsparse_Xcsritilu0_history.
rocsparse_itilu0_option_convergence_history	Enable collecting convergence history data with rocsparse_Xcsritilu0_history.
rocsparse_itilu0_option_coo_format	Use COO format internally.

Note: The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().; This function is blocking with respect to the host.; This routine does not support execution in a hipGraph context.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	alg	- algorithm to use, `rocsparse_itilu0_alg`
[in]	option	- combination of enumeration values from `rocsparse_itilu0_option`.
[in,out]	nmaxiter	- maximum number of iterations on input and number of iterations on output. If the output number of iterations is strictly less than the input maximum number of iterations, then the algorithm converged.
[in]	tol	- tolerance to use for stopping criteria.
[in]	m	- number of rows of the sparse CSR matrix.
[in]	nnz	- number of non-zero entries 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,out]	csr_val	- array of `nnz` elements of the sparse CSR matrix.
[out]	ilu0	- incomplete factorization.
[in]	idx_base	- `rocsparse_index_base_zero` or `rocsparse_index_base_one`.
[in]	buffer_size	- size of the storage buffer allocated by the user.
[in]	buffer	- storage buffer allocated by the user.

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_value	`alg` or `base` is invalid.
rocsparse_status_invalid_handle	the library context was not initialized.
rocsparse_status_invalid_size	`m` or `nnz` is invalid.
rocsparse_status_invalid_pointer	`csr_row_ptr` or `csr_col_ind` pointer is invalid.
rocsparse_status_internal_error	an internal error occurred.

Example

Member Function/Subroutine Documentation