hipsparsesprunedense2csr Interface Reference

hipsparsesprunedense2csr Interface Reference#

HIPFORT API Reference: hipfort_hipsparse::hipsparsesprunedense2csr Interface Reference

hipsparseXpruneDense2csr converts the matrix A in dense format into a sparse matrix in CSR format, while pruning values that are less than the (non-negative) threshold. More...

Public Member Functions
integer(kind(hipsparse_status_success)) function	hipsparsesprunedense2csr_ (handle, m, n, a, lda, threshold, descr, csrval, csrrowptr, csrcolind, buffer)

integer(kind(hipsparse_status_success)) function	hipsparsesprunedense2csr_rank_0 (handle, m, n, a, lda, threshold, descr, csrval, csrrowptr, csrcolind, buffer)

integer(kind(hipsparse_status_success)) function	hipsparsesprunedense2csr_rank_1 (handle, m, n, a, lda, threshold, descr, csrval, csrrowptr, csrcolind, buffer)

integer(kind(hipsparse_status_success)) function	hipsparsesprunedense2csr_full_rank (handle, m, n, a, lda, threshold, descr, csrval, csrrowptr, csrcolind, buffer)

Detailed Description

hipsparseXpruneDense2csr converts the matrix A in dense format into a sparse matrix in CSR format, while pruning values that are less than the (non-negative) threshold.

All the parameters are assumed to have been pre-allocated by the user.

Given an input dense column ordered matrix A, with leading dimension lda, where lda>=m, the resulting pruned sparse CSR matrix C is computed using:

\[ |C(i,j)| = A(i, j) \text{ if |A(i, j)| > threshold} \]

The user first calls hipsparseSpruneDense2csr_bufferSize "hipsparseXpruneDense2csr_bufferSize()" to determine the size of the required user-allocated temporary storage buffer. The user then allocates this buffer. Next, the user allocates csrRowPtr to have m+1 elements and then calls hipsparseSpruneDense2csrNnz "hipsparseXpruneDense2csrNnz()", which fills in the csrRowPtr array and stores the number of elements that are larger than the pruning threshold in nnzTotalDevHostPtr. The user then allocates csrColInd and csrVal to have size nnzTotalDevHostPtr and completes the conversion by calling hipsparseXpruneDense2csr().

For example, performing these steps with the dense input matrix A :

\[ \begin{bmatrix} 6 & 2 & 3 & 7 \\% 5 & 6 & 7 & 8 \\% 5 & 4 & 8 & 1 \end{bmatrix} \]

and the threshold value 5, results in the pruned matrix C:

\[ \begin{bmatrix} 6 & 0 & 0 & 7 \\% 0 & 6 & 7 & 8 \\% 0 & 0 & 8 & 0 \end{bmatrix} \]

and corresponding CSR row, column, and values arrays:

\[ \begin{align} \text{csrRowPtr} &= \begin{bmatrix} 0 & 2 & 5 & 6 \end{bmatrix} \\% \text{csrColInd} &= \begin{bmatrix} 0 & 3 & 1 & 2 & 3 & 2 \end{bmatrix} \\% \text{csrVal} &= \begin{bmatrix} 6 & 7 & 6 & 7 & 8 & 8 \end{bmatrix} \\% \end{align} \]

Note: The routine hipsparseXpruneDense2csr() is executed asynchronously with respect to the host and can return control to the application on the host before the entire result is ready.

Parameters

[in]	handle	- handle to the hipSPARSE library context queue.
[in]	m	- number of rows of the dense matrix `A`.
[in]	n	- number of columns of the dense matrix `A`.
[in]	A	- array of dimensions (`lda`, `n`).
[in]	lda	- leading dimension of dense array `A`.
[in]	threshold	- pointer to the non-negative pruning threshold, which can exist in either host or device memory.
[in]	descr	- the descriptor of the dense matrix `A`. The supported matrix type is `HIPSPARSE_MATRIX_TYPE_GENERAL` and any valid value of the `hipsparseIndexBase_t`.
[out]	csrVal	- array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) non-zero elements of matrix `A`.
[in]	csrRowPtr	- integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.
[out]	csrColInd	- integer array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) column indices of the non-zero elements of matrix `A`.
[in]	buffer	- temporary storage buffer allocated by the user. The size is returned by `hipsparseSpruneDense2csr_bufferSize` "hipsparseXpruneDense2csr_bufferSize()" or `hipsparseSpruneDense2csr_bufferSizeExt` "hipsparseXpruneDense2csr_bufferSizeExt()".

Return values

HIPSPARSE_STATUS_SUCCESS	the operation completed successfully.
HIPSPARSE_STATUS_INVALID_VALUE	`handle`, `m`, `n`, `lda`, `A`, `descr`, `threshold`, `csrVal`, `csrRowPtr`, `csrColInd`, or `buffer` pointer is invalid.

Member Function/Subroutine Documentation