rocsparse_spgemm Interface Reference

rocsparse_spgemm Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_spgemm Interface Reference

Sparse matrix sparse matrix multiplication. More...

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_spgemm_ (handle, trans_A, trans_B, alpha, A, B, beta, D, C, compute_type, alg, stage, buffer_size, temp_buffer)

Detailed Description

Sparse matrix sparse matrix multiplication.

rocsparse_spgemm multiplies the scalar \(\alpha\) with the sparse \(m \times k\) matrix \(A\) and the sparse \(k \times n\) matrix \(B\) and adds the result to the sparse \(m \times n\) matrix \(D\) that is multiplied by \(\beta\). The final result is stored in the sparse \(m \times n\) matrix \(C\), 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} \newline A^T, & \text{if trans_A == rocsparse_operation_transpose} \newline 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} \newline B^T, & \text{if trans_B == rocsparse_operation_transpose} \newline B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \]

Note: SpGEMM requires three stages to complete. The first stage rocsparse_spgemm_stage_buffer_size will return the size of the temporary storage buffer that is required for subsequent calls to rocsparse_spgemm. The second stage rocsparse_spgemm_stage_nnz will determine the number of non-zero elements of the resulting \(C\) matrix. If the sparsity pattern of \(C\) is already known, this stage can be skipped. In the final stage rocsparse_spgemm_stage_compute, the actual computation is performed.; If rocsparse_spgemm_stage_auto is selected, rocSPARSE will automatically detect which stage is required based on the following indicators: If temp_buffer is equal to nullptr, the required buffer size will be returned. Else, if the number of non-zeros of \(C\) is zero, the number of non-zero entries will be computed. Else, the SpGEMM algorithm will be executed.; 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.; It is allowed to pass the same sparse matrix for \(C\) and \(D\), if both matrices have the same sparsity pattern.; Currently, only trans_A == rocsparse_operation_none is supported.; Currently, only trans_B == rocsparse_operation_none is supported.; This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.; Please note, that for rare matrix products with more than 4096 non-zero entries per row, additional temporary storage buffer is allocated by the algorithm.

Parameters

[in]	handle	handle to the rocsparse library context queue.
[in]	trans_A	sparse matrix \(A\) operation type.
[in]	trans_B	sparse matrix \(B\) operation type.
[in]	alpha	scalar \(\alpha\).
[in]	A	sparse matrix \(A\) descriptor.
[in]	B	sparse matrix \(B\) descriptor.
[in]	beta	scalar \(\beta\).
[in]	D	sparse matrix \(D\) descriptor.
[out]	C	sparse matrix \(C\) descriptor.
[in]	compute_type	floating point precision for the SpGEMM computation.
[in]	alg	SpGEMM algorithm for the SpGEMM computation.
[in]	stage	SpGEMM stage for the SpGEMM computation.
[out]	buffer_size	number of bytes of the temporary storage buffer. buffer_size is set when `temp_buffer` is nullptr.
[in]	temp_buffer	temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to `buffer_size` and function returns without performing the SpGEMM operation.

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_handle	the library context was not initialized.
rocsparse_status_invalid_pointer	`alpha` and `beta` are invalid, `A`, `B`, `D`, `C` or `buffer_size` pointer is invalid.
rocsparse_status_memory_error	additional buffer for long rows could not be allocated.
rocsparse_status_not_implemented	`trans_A` != `rocsparse_operation_none` or `trans_B` != `rocsparse_operation_none`.

Member Function/Subroutine Documentation