hipsparsescsric02 Interface Reference

hipsparsescsric02 Interface Reference#

HIPFORT API Reference: hipfort_hipsparse::hipsparsescsric02 Interface Reference

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

Public Member Functions
integer(kind(hipsparse_status_success)) function	hipsparsescsric02_ (handle, m, nnz, descra, csrsortedvala_valm, csrsortedrowptra, csrsortedcolinda, myinfo, policy, pbuffer)

integer(kind(hipsparse_status_success)) function	hipsparsescsric02_rank_0 (handle, m, nnz, descra, csrsortedvala_valm, csrsortedrowptra, csrsortedcolinda, myinfo, policy, pbuffer)

integer(kind(hipsparse_status_success)) function	hipsparsescsric02_rank_1 (handle, m, nnz, descra, csrsortedvala_valm, csrsortedrowptra, csrsortedcolinda, myinfo, policy, pbuffer)

Detailed Description

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

hipsparseXcsric02 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_{jj} - \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, the user determines the size of the required temporary storage buffer by calling hipsparseScsric02_bufferSize "hipsparseXcsric02_bufferSize()". After this buffer size has been determined, the user allocates the buffer and passes it to hipsparseScsric02_analysis "hipsparseXcsric02_analysis()". This will perform analysis on the sparsity pattern of the matrix. Finally, the user calls hipsparseScsric02, hipsparseDcsric02, hipsparseCcsric02, or hipsparseZcsric02 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 hipsparseScsric02 "hipsparseXcsric02()" 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 hipsparseXcsric02_zeroPivot () after hipsparseScsric02_analysis "hipsparseXcsric02_analysis()" and/or the presence of a structural or numerical zero by calling hipsparseXcsric02_zeroPivot () after hipsparseScsric02 "hipsparseXcsric02()":

hipsparseDcsric02(handle,
                  m,
                  nnz,
                  descrM,
                  csrVal,
                  csrRowPtr,
                  csrColInd,
                  info,
                  HIPSPARSE_SOLVE_POLICY_USE_LEVEL,
                  buffer);
 
// Check for zero pivot
if(CUSPARSE_STATUS_ZERO_PIVOT == hipsparseXcsric02_zeroPivot(handle, info, &position))
{
    printf("L has structural and/or numerical zero at L(%d,%d)", position, position);
}

In both cases, hipsparseXcsric02_zeroPivot () 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 hipsparseSetMatDiagType (), which will interpret the matrix \(A\) as having ones on its diagonal (even if no non-zero exists in the sparsity pattern).

hipsparseXcsric02 computes the Cholesky factorization inplace meaning that the values array csrSortedValA_valM 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 csrSortedRowPtrA and the column indices array csrSortedColIndA 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 Cholesky factorization with hipSPARSE greatly depends on the sparsity pattern the the matrix \(A\), because this is what determines the amount of parallelism available.

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

Parameters

[in]	handle	- handle to the hipSPARSE 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]	descrA	- descriptor of the sparse CSR matrix.
[in,out]	csrSortedValA_valM	- array of `nnz` elements of the sparse CSR matrix.
[in]	csrSortedRowPtrA	- array of `m+1` elements that point to the start of every row of the sparse CSR matrix.
[in]	csrSortedColIndA	- 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	- `HIPSPARSE_SOLVE_POLICY_NO_LEVEL` or `HIPSPARSE_SOLVE_POLICY_USE_LEVEL`.
[in]	pBuffer	- temporary storage buffer allocated by the user.

Return values

HIPSPARSE_STATUS_SUCCESS	the operation completed successfully.
HIPSPARSE_STATUS_INVALID_VALUE	`handle`, `m`, `nnz`, `descrA`, `csrSortedValA_valM`, `csrSortedRowPtrA`, or `csrSortedColIndA` pointer is invalid.
HIPSPARSE_STATUS_ARCH_MISMATCH	the device is not supported.
HIPSPARSE_STATUS_INTERNAL_ERROR	an internal error occurred.
HIPSPARSE_STATUS_NOT_SUPPORTED	`hipsparseMatrixType_t` != `HIPSPARSE_MATRIX_TYPE_GENERAL`.

Member Function/Subroutine Documentation