hipsparsescsr2gebsr Interface Reference

hipsparsescsr2gebsr Interface Reference#

HIPFORT API Reference: hipfort_hipsparse::hipsparsescsr2gebsr Interface Reference

Convert a sparse CSR matrix into a sparse GEBSR matrix. More...

Public Member Functions
integer(kind(hipsparse_status_success)) function	hipsparsescsr2gebsr_ (handle, dir, m, n, csr_descr, csrval, csrrowptr, csrcolind, bsr_descr, bsrval, bsrrowptr, bsrcolind, rowblockdim, colblockdim, pbuffer)

integer(kind(hipsparse_status_success)) function	hipsparsescsr2gebsr_rank_0 (handle, dir, m, n, csr_descr, csrval, csrrowptr, csrcolind, bsr_descr, bsrval, bsrrowptr, bsrcolind, rowblockdim, colblockdim, pbuffer)

integer(kind(hipsparse_status_success)) function	hipsparsescsr2gebsr_rank_1 (handle, dir, m, n, csr_descr, csrval, csrrowptr, csrcolind, bsr_descr, bsrval, bsrrowptr, bsrcolind, rowblockdim, colblockdim, pbuffer)

Detailed Description

Convert a sparse CSR matrix into a sparse GEBSR matrix.

hipsparseXcsr2gebsr converts a CSR matrix into a GEBSR matrix. It is assumed that bsrVal, bsrColInd, and bsrRowPtr are allocated. Allocation size for bsrRowPtr is computed as mb+1, where mb is the number of block rows in the GEBSR matrix. The number of non-zero blocks in the resulting GEBSR matrix is computed using hipsparseXcsr2gebsrNnz, which also fills in bsrRowPtr.

In more detail, hipsparseXcsr2gebsr is the third and final step of the conversion from CSR to GEBSR. The user first determines the size of the required user-allocated temporary storage buffer using hipsparseScsr2gebsr_bufferSize "hipsparseXcsr2gebsr_bufferSize()". The user then allocates this buffer as well as the row pointer array bsrRowPtr with size mb+1, where mb is the number of block rows in the GEBSR matrix and nb is the number of block columns in GEBSR matrix:

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

Both the temporary storage buffer and the GEBSR row pointer array are then passed to hipsparseXcsr2gebsrNnz, which fills the GEBSR row pointer array bsrRowPtr and also computes the number of non-zero blocks, bsrNnzDevhost, that will exist in the GEBSR matrix. The user then allocates both the GEBSR column indices array bsrColInd with size bsrNnzDevhost as well as the GEBSR values array bsrVal with size bsrNnzDevhost*rowBlockDim*colBlockDim. Finally, with all arrays allocated, the conversion is completed by calling hipsparseXcsr2gebsr.

For example, assuming the 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} \]

then using rowBlockDim=3 and colBlockDim=2, the final GEBSR matrix is:

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

and is represented with the arrays:

\[ \begin{align} \text{bsrRowPtr} &= \begin{bmatrix} 0 & 3 \end{bmatrix} \\% \text{bsrColInd} &= \begin{bmatrix} 0 & 1 & 2 \end{bmatrix} \\% \text{bsrVal} &= \begin{bmatrix} 1 & 0 & 3 & 4 & 3 & 0 & 0 & 2 & 0 & 0 & 6 & 7 & 4 & 0 & 5 & 1 & 6 & 2 \end{bmatrix} \end{align} \]

The above example assumes that the blocks are row ordered. If instead the blocks are column ordered, the bsrVal arrays become:

\[ \begin{align} \text{bsrVal} &= \begin{bmatrix} 1 & 3 & 3 & 0 & 4 & 0 & 0 & 0 & 6 & 2 & 0 & 7 & 4 & 5 & 6 & 0 & 1 & 2 \end{bmatrix} \end{align} \]

The block order direction is determined by dir.

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 resulting GEBSR matrix would look like:

\[ \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] \]

Parameters

[in]	handle	- handle to the hipSPARSE library context queue.
[in]	dir	- the storage format of the blocks, `HIPSPARSE_DIRECTION_ROW` or `HIPSPARSE_DIRECTION_COLUMN`.
[in]	m	- number of rows in the sparse CSR matrix.
[in]	n	- number of columns in the sparse CSR matrix.
[in]	csr_descr	- descriptor of the sparse CSR matrix. Currently, only `HIPSPARSE_MATRIX_TYPE_GENERAL` is supported.
[in]	csrVal	- array of `nnz` elements containing the values of the sparse CSR matrix.
[in]	csrRowPtr	- array of `m+1` elements that point to the start of every row of the sparse CSR matrix.
[in]	csrColInd	- array of `nnz` elements containing the column indices of the sparse CSR matrix.
[in]	bsr_descr	- descriptor of the sparse BSR matrix. Currently, only `HIPSPARSE_MATRIX_TYPE_GENERAL` is supported.
[out]	bsrVal	- array of `nnzb` `rowBlockDim` `colBlockDim` containing the values of the sparse BSR matrix.
[out]	bsrRowPtr	- array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.
[out]	bsrColInd	- array of `nnzb` elements containing the block column indices of the sparse BSR matrix.
[in]	rowBlockDim	- row size of the blocks in the sparse general BSR matrix.
[in]	colBlockDim	- col size of the blocks in the sparse general BSR matrix.
[in]	pbuffer	- buffer allocated by the user. The buffer 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`, `bsrVal`, `bsrRowPtr`, `bsrColInd`, `csrVal`, `csrRowPtr`, or `csrColInd` pointer is invalid.

Member Function/Subroutine Documentation