rocsparse_sbsrmv Interface Reference

rocsparse_sbsrmv Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_sbsrmv Interface Reference

Sparse matrix vector multiplication using the BSR storage format. More...

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_sbsrmv_ (handle, dir, trans, mb, nb, nnzb, alpha, descr, bsr_val, bsr_row_ptr, bsr_col_ind, block_dim, myinfo, x, beta, y)

integer(kind(rocsparse_status_success)) function	rocsparse_sbsrmv_rank_0 (handle, dir, trans, mb, nb, nnzb, alpha, descr, bsr_val, bsr_row_ptr, bsr_col_ind, block_dim, myinfo, x, beta, y)

integer(kind(rocsparse_status_success)) function	rocsparse_sbsrmv_rank_1 (handle, dir, trans, mb, nb, nnzb, alpha, descr, bsr_val, bsr_row_ptr, bsr_col_ind, block_dim, myinfo, x, beta, y)

Detailed Description

Sparse matrix vector multiplication using the BSR storage format.

rocsparse_bsrmv multiplies the scalar \(\alpha\) with a sparse \(m \times n\) matrix, defined in BSR storage format, and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

\[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]

with

\[ op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \end{array} \right. \]

and where \(m = mb \times block\_dim\) and \(n= nb \times block\_dim\).

The operation above can be done with or without analysis. Running with analysis might result in better performance when computing the matrix vector product but will also incur a performance cost attributed to the additional analysis step. For this reason, running with analysis makes sense when a user plans on computing the matrix vector product many times and therefore can amortize the analysis cost.

To run the operation above without analysis, call the rocsparse_bsrmv routine while passing NULL for the info parameter.

Running the operation with analysis involves two steps. First, create a rocsparse_mat_info object by calling rocsparse_create_mat_info and then pass this to rocsparse_Xbsrmv_analysis(), which will perform analysis on the sparsity pattern of the matrix \(op(A)\). Then complete the operation by calling rocsparse_bsrmv. The creation of the info object and the call to the analysis routine only need to be performed once for a given sparsity pattern, while the computation can be performed repeatedly as long as the sparsity pattern has not changed. After all calls to rocsparse_bsrmv have been made, the info object can be destroyed with a call to rocsparse_destroy_mat_info.

When running with analysis, users might want to perform multiple sparse matrix multiplications, with each sparse matrix having a different sparsity pattern. Instead of creating and destroying multiple rocsparse_mat_info objects for each unique sparsity pattern, the user can instead create the info object once and then call rocsparse_bsrmv_clear, followed by re-running the analysis in between each sparse matrix multiplication.

Note: This function is non-blocking and executed asynchronously with respect to the host. It can return before the actual computation has finished.; Currently, only trans == rocsparse_operation_none is supported.; This routine supports execution in a hipGraph context.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	dir	- matrix storage of BSR blocks.
[in]	trans	- matrix operation type.
[in]	mb	- number of block rows of the sparse BSR matrix.
[in]	nb	- number of block columns of the sparse BSR matrix.
[in]	nnzb	- number of non-zero blocks of the sparse BSR matrix.
[in]	alpha	- scalar \(\alpha\).
[in]	descr	- descriptor of the sparse BSR matrix. Currently, only `rocsparse_matrix_type_general` is supported.
[in]	bsr_val	- array of `nnzb` blocks of the sparse BSR matrix.
[in]	bsr_row_ptr	- array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.
[in]	bsr_col_ind	- array of `nnzb` elements containing the block column indices of the sparse BSR matrix.
[in]	block_dim	- block dimension of the sparse BSR matrix.
[in]	x	- array of `nbblock_dim` elements ( \(op(A) = A\)) or `mbblock_dim` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).
[in]	beta	- scalar \(\beta\).
[in,out]	y	- array of `mbblock_dim` elements ( \(op(A) = A\)) or `nbblock_dim` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).
[out]	myInfo	- structure that holds the information collected during the analysis step.

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_handle	the library context was not initialized.
rocsparse_status_invalid_size	`mb`, `nb`, `nnzb`, or `block_dim` is invalid.
rocsparse_status_invalid_pointer	`descr`, `alpha`, `bsr_val`, `bsr_row_ind`, `bsr_col_ind`, `x`, `beta`, or `y` pointer is invalid.
rocsparse_status_arch_mismatch	the device is not supported.
rocsparse_status_not_implemented	`trans` != `rocsparse_operation_none` or `rocsparse_matrix_type` != `rocsparse_matrix_type_general`.

Example: This example performs a sparse matrix vector multiplication in BSR format.

Member Function/Subroutine Documentation