hipsparsexcsr2gebsrnnz Interface Reference

hipsparsexcsr2gebsrnnz Interface Reference#

HIPFORT API Reference: hipfort_hipsparse::hipsparsexcsr2gebsrnnz Interface Reference

This function computes the number of non-zero block columns per row and the total number of non-zero blocks in a sparse GEBSR matrix given a sparse CSR matrix as input. More...

Public Member Functions
integer(kind(hipsparse_status_success)) function	hipsparsexcsr2gebsrnnz_ (handle, dir, m, n, csr_descr, csrrowptr, csrcolind, bsr_descr, bsrrowptr, rowblockdim, colblockdim, bsrnnzdevhost, pbuffer)

integer(kind(hipsparse_status_success)) function	hipsparsexcsr2gebsrnnz_rank_0 (handle, dir, m, n, csr_descr, csrrowptr, csrcolind, bsr_descr, bsrrowptr, rowblockdim, colblockdim, bsrnnzdevhost, pbuffer)

integer(kind(hipsparse_status_success)) function	hipsparsexcsr2gebsrnnz_rank_1 (handle, dir, m, n, csr_descr, csrrowptr, csrcolind, bsr_descr, bsrrowptr, rowblockdim, colblockdim, bsrnnzdevhost, pbuffer)

Detailed Description

This function computes the number of non-zero block columns per row and the total number of non-zero blocks in a sparse GEBSR matrix given a sparse CSR matrix as input.

This is the second step in converting a CSR matrix to a GEBSR matrix. The user must first call hipsparseScsr2gebsr_bufferSize "hipsparseXcsr2gebsr_bufferSize()" to determine the size of the required temporary storage buffer. The user then allocates this buffer as well as the bsrRowPtr array ( size mb+1 ) and passes both to `hipsparseXcsr2gebsrNnz()`. This second step then computes the number of non-zero block columns per row and the total number of non-zero blocks.

In general, when converting a CSR matrix of size m x n to a GEBSR matrix, the resulting GEBSR matrix will have size mb x nb, where mb and nb equal:

\[ \begin{align} \text{mb} &= \text{(m - 1) / rowBlockDim + 1} \\% \text{nb} &= \text{(n - 1) / colBlockDim + 1} \end{align} \]

For example, given a matrix:

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

represented in CSR format with the arrays:

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

the bsrRowPtr array and total non-zero block count will be filled with:

\[ \begin{align} \text{bsrRowPtr} &= \begin{bmatrix} 0 & 3 \end{bmatrix} \\% \text{*bsrNnzDevhost} &= 3 \end{align} \]

after calling hipsparseXcsr2gebsrNnz with rowBlockDim=3 and colBlockDim=2.

Note: As indicated, bsrNnzDevhost can point either to host or device memory. This is controlled by setting the pointer mode. See hipsparseSetPointerMode().

It might be the case that rowBlockDim does not divide evenly into m and/or that colBlockDim does not divide evenly into n. In these cases, the CSR matrix is expanded in size to fit full GEBSR blocks. For example, using the original CSR matrix but this time with rowBlockDim=2 and colBlockDim=3, the function hipsparseXcsr2gebsrNnz computes the GEBSR row pointer array and total number of non-zero blocks for the GEBSR matrix:

\[ \left[ \begin{array}{c | c} \begin{array}{c c c} 1 & 0 & 0 \\% 3 & 4 & 0 \end{array} & \begin{array}{c c c} 2 & 4 & 0 \\% 0 & 5 & 1 \end{array} \\% \hline \begin{array}{c c c} 5 & 0 & 6 \\% 0 & 0 & 0 \end{array} & \begin{array}{c c c} 7 & 6 & 2 \\% 0 & 0 & 0 \end{array} \end{array} \right] \]

See hipsparseScsr2gebsr() for a full code example.

Parameters

[in]	handle	- handle to the hipSPARSE library context queue.
[in]	dir	- direction that specifies whether to count non-zero elements by `HIPSPARSE_DIRECTION_ROW` or by `HIPSPARSE_DIRECTION_COLUMN`.
[in]	m	- number of rows of the sparse CSR matrix.
[in]	n	- number of columns of the sparse CSR matrix.
[in]	csr_descr	- descriptor of the sparse CSR matrix. Currently, only `HIPSPARSE_MATRIX_TYPE_GENERAL` is supported.
[in]	csrRowPtr	- integer array containing `m+1` elements that point to the start of each row of the CSR matrix.
[in]	csrColInd	- integer array of the column indices for each non-zero element in the CSR matrix.
[in]	bsr_descr	- descriptor of the sparse general BSR matrix. Currently, only `HIPSPARSE_MATRIX_TYPE_GENERAL` is supported.
[out]	bsrRowPtr	- integer array containing `mb+1` elements that point to the start of each block row of the general BSR matrix.
[in]	rowBlockDim	- the row block dimension of the general BSR matrix, which is between \(1\) and \(\min(m, n)\).
[in]	colBlockDim	- the col block dimension of the general BSR matrix, which is between \(1\) and \(\min(m, n)\).
[out]	bsrNnzDevhost	- total number of non-zero elements in device or host memory.
[in]	pbuffer	- buffer allocated by the user whose size is determined by calling `hipsparseScsr2gebsr_bufferSize` "hipsparseXcsr2gebsr_bufferSize()".

Return values

HIPSPARSE_STATUS_SUCCESS	the operation completed successfully.
HIPSPARSE_STATUS_INVALID_VALUE	`handle`, `m`, `n`, `rowBlockDim`, `colBlockDim`, `csrRowPtr`, `csrColInd`, `bsrRowPtr`, or `bsrNnzDevhost` pointer is invalid.

Member Function/Subroutine Documentation