rocsparse_scsric0 Interface Reference

rocsparse_scsric0 Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_scsric0 Interface Reference

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

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

integer(kind(rocsparse_status_success)) function	rocsparse_scsric0_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_scsric0_rank_1 (handle, m, nnz, descr, csr_val, csr_row_ptr, csr_col_ind, myinfo, policy, temp_buffer)

Detailed Description

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

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

\[ A \approx LL^T \]

where the lower triangular matrix \(L\) is computed using:

\[ L_{ij} = \left\{ \begin{array}{ll} \sqrt{A_{jj} - \sum_{k=0}^{j-1}(L_{jk})^{2}}, & \text{if i == j} \\% \frac{1}{L_{jj}}(A_{ij} - \sum_{k=0}^{j-1}L_{ik} \times L_{jk}), & \text{if i > j} \end{array} \right. \]

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

Computing the above incomplete Cholesky factorization requires three steps to complete. First, determine the size of the required temporary storage buffer by calling rocsparse_Xcsric0_buffer_size(). After this buffer size has been determined, allocate the buffer and pass it to rocsparse_Xcsric0_analysis(). This will perform analysis on the sparsity pattern of the matrix. Finally, call rocsparse_scsric0, rocsparse_dcsric0, rocsparse_ccsric0, or rocsparse_zcsric0 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_Xcsric0() are complete, the temporary buffer can be deallocated.

When computing the Cholesky factorization, it is possible that \(L_{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_{jj} - \sum_{k=0}^{j-1}(L_{jk})^{2} == 0\) (referred to as a numerical zero). For example, running the Cholesky factorization on the following matrix:

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

results in a successful Cholesky 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} L_{00} &= \sqrt{2} \\% L_{10} &= \frac{1}{\sqrt{2}} \\% L_{11} &= \sqrt{\frac{1}{2} - (\frac{1}{\sqrt{2}})^2} &= 0 \end{array} \]

The user can detect the presence of a structural zero by calling rocsparse_csric0_zero_pivot () after rocsparse_Xcsric0_analysis() and/or the presence of a structural or numerical zero by calling rocsparse_csric0_zero_pivot () after rocsparse_Xcsric0():

rocsparse_dcsric0(handle,
                m,
                nnz,
                descr_M,
                csr_val,
                csr_row_ptr,
                csr_col_ind,
                info,
                rocsparse_solve_policy_auto,
                temp_buffer);
 
// Check for zero pivot
if(rocsparse_status_zero_pivot == rocsparse_csric0_zero_pivot(handle,
                                                              info,
                                                              &position))
{
    printf("L has structural and/or numerical zero at L(%d,%d)", position, position);
}

In both cases, rocsparse_csric0_zero_pivot () will report the first zero pivot (either numerical or structural) found. See the full 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_csric0 computes the Cholesky factorization inplace, meaning that the values array csr_val of the \(A\) matrix is overwritten with the \(L\) matrix stored in the lower triangular 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} l_{00} & a_{01} & a_{02} \\% l_{10} & l_{11} & a_{12} \\% l_{20} & l_{21} & l_{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 the output, as the incomplete factorization does not generate new non-zeros in the output which do not already exist in \(A\).

The performance of computing the Cholesky factorization with rocSPARSE greatly depends on the sparsity pattern of 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 the CSR storage format. The following example computes the incomplete Cholesky factorization \(M \approx LL^T\) and solves the preconditioned system \(My = x\).

Member Function/Subroutine Documentation