rocsparse_sbsrgemm Interface Reference

rocsparse_sbsrgemm Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_sbsrgemm Interface Reference

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

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_sbsrgemm_ (handle, dir, trans_a, trans_b, mb, nb, kb, block_dim, alpha, descr_a, nnzb_a, bsr_val_a, bsr_row_ptr_a, bsr_col_ind_a, descr_b, nnzb_b, bsr_val_b, bsr_row_ptr_b, bsr_col_ind_b, beta, descr_d, nnzb_d, bsr_val_d, bsr_row_ptr_d, bsr_col_ind_d, descr_c, bsr_val_c, bsr_row_ptr_c, bsr_col_ind_c, info_c, temp_buffer)

Detailed Description

Sparse matrix sparse matrix multiplication using the BSR storage format.

rocsparse_bsrgemm multiplies the scalar \(\alpha\) with the sparse \(mb \times kb\) matrix \(A\), defined in BSR storage format, and the sparse \(kb \times nb\) matrix \(B\), defined in BSR storage format, and adds the result to the sparse \(mb \times nb\) matrix \(D\) that is multiplied by \(\beta\). The final result is stored in the sparse \(mb \times nb\) matrix \(C\), defined in BSR storage format, such that

\[ C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot D, \]

with

\[ op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\% A^T, & \text{if trans_A == rocsparse_operation_transpose} \\% A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \]

and

\[ op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\% B^T, & \text{if trans_B == rocsparse_operation_transpose} \\% B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \]

Note: This function does not produce deterministic results.

It is assumed that bsr_row_ptr_C has already been filled and that bsr_val_C and bsr_col_ind_C are allocated by the user. bsr_row_ptr_C and the allocation size of bsr_col_ind_C and bsr_val_C is defined by the number of non-zero elements of the sparse BSR matrix C. Both can be obtained by rocsparse_bsrgemm_nnzb(). The required buffer size for the computation can be obtained by rocsparse_Xbsrgemm_buffer_size().

Note: If \(\alpha == 0\), then \(C = \beta \cdot D\) will be computed.; If \(\beta == 0\), then \(C = \alpha \cdot op(A) \cdot op(B)\) will be computed.; \(\alpha == beta == 0\) is invalid.; Currently, only trans_A == rocsparse_operation_none is supported.; Currently, only trans_B == rocsparse_operation_none is supported.; Currently, only rocsparse_matrix_type_general is supported.; This function is blocking with respect to the host.; This routine does not support execution in a hipGraph context.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	dir	- direction that specifies whether to count non-zero elements by `rocsparse_direction_row` or by `rocsparse_direction_column` in the BSR matrices \(A\), \(B\), \(C\), and \(D\).
[in]	trans_A	- matrix \(A\) operation type.
[in]	trans_B	- matrix \(B\) operation type.
[in]	mb	- number of block rows of the sparse BSR matrix \(op(A)\) and \(C\).
[in]	nb	- number of block columns of the sparse BSR matrix \(op(B)\) and \(C\).
[in]	kb	- number of block columns of the sparse BSR matrix \(op(A)\) and number of block rows of the sparse BSR matrix \(op(B)\).
[in]	block_dim	- the block dimension of the BSR matrix \(A\), \(B\), \(C\), and \(D\).
[in]	alpha	- scalar \(\alpha\).
[in]	descr_A	- descriptor of the sparse BSR matrix \(A\). Currently, only `rocsparse_matrix_type_general` is supported.
[in]	nnzb_A	- number of non-zero block entries of the sparse BSR matrix \(A\).
[in]	bsr_val_A	- array of `nnzb_A` block elements of the sparse BSR matrix \(A\).
[in]	bsr_row_ptr_A	- array of `mb+1` block elements ( \(op(A) == A\), `kb+1` otherwise) that point to the start of every block row of the sparse BSR matrix \(op(A)\).
[in]	bsr_col_ind_A	- array of `nnzb_A` block elements containing the block column indices of the sparse BSR matrix \(A\).
[in]	descr_B	- descriptor of the sparse BSR matrix \(B\). Currently, only `rocsparse_matrix_type_general` is supported.
[in]	nnzb_B	- number of non-zero block entries of the sparse BSR matrix \(B\).
[in]	bsr_val_B	- array of `nnzb_B` block elements of the sparse BSR matrix \(B\).
[in]	bsr_row_ptr_B	- array of `kb+1` block elements ( \(op(B) == B\), `mb+1` otherwise) that point to the start of every block row of the sparse BSR matrix \(op(B)\).
[in]	bsr_col_ind_B	- array of `nnzb_B` block elements containing the block column indices of the sparse BSR matrix \(B\).
[in]	beta	- scalar \(\beta\).
[in]	descr_D	- descriptor of the sparse BSR matrix \(D\). Currently, only `rocsparse_matrix_type_general` is supported.
[in]	nnzb_D	- number of non-zero block entries of the sparse BSR matrix \(D\).
[in]	bsr_val_D	- array of `nnzb_D` block elements of the sparse BSR matrix \(D\).
[in]	bsr_row_ptr_D	- array of `mb+1` block elements that point to the start of every block row of the sparse BSR matrix \(D\).
[in]	bsr_col_ind_D	- array of `nnzb_D` block elements containing the block column indices of the sparse BSR matrix \(D\).
[in]	descr_C	- descriptor of the sparse BSR matrix \(C\). Currently, only `rocsparse_matrix_type_general` is supported.
[out]	bsr_val_C	- array of `nnzb_C` elements of the sparse BSR matrix \(C\).
[in]	bsr_row_ptr_C	- array of `mb+1` block elements that point to the start of every block row of the sparse BSR matrix \(C\).
[out]	bsr_col_ind_C	- array of `nnzb_C` block elements containing the block column indices of the sparse BSR matrix \(C\).
[in]	info_C	- structure that holds metadata for the sparse BSR matrix \(C\).
[in]	temp_buffer	- temporary storage buffer allocated by the user. The size is returned by rocsparse_sbsrgemm_buffer_size(), rocsparse_dbsrgemm_buffer_size(), rocsparse_cbsrgemm_buffer_size(), or rocsparse_zbsrgemm_buffer_size().

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`, `kb`, `block_dim`, `nnzb_A`, `nnzb_B`, or `nnzb_D` is invalid.
rocsparse_status_invalid_pointer	`alpha` and `beta` are invalid, `descr_A`, `bsr_val_A`, `bsr_row_ptr_A`, `bsr_col_ind_A`, `descr_B`, `bsr_val_B`, `bsr_row_ptr_B`, or `bsr_col_ind_B` are invalid if `alpha` is valid, `descr_D`, `bsr_val_D`, `bsr_row_ptr_D`, or `bsr_col_ind_D` is invalid if `beta` is valid, or `bsr_val_C`, `bsr_row_ptr_C`, `bsr_col_ind_C`, or `info_C` or `temp_buffer` are invalid.
rocsparse_status_memory_error	additional buffer for long rows could not be allocated.
rocsparse_status_not_implemented	`trans_A` != `rocsparse_operation_none`, `trans_B` != `rocsparse_operation_none`, or `rocsparse_matrix_type` != `rocsparse_matrix_type_general`.

Example: This example multiplies two BSR matrices with a scalar alpha and adds the result to another BSR matrix.

Member Function/Subroutine Documentation