rocsparse_spgemm Interface Reference

rocsparse_spgemm Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_spgemm Interface 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, \]


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


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

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.
[in]handlehandle to the rocsparse library context queue.
[in]trans_Asparse matrix \(A\) operation type.
[in]trans_Bsparse matrix \(B\) operation type.
[in]alphascalar \(\alpha\).
[in]Asparse matrix \(A\) descriptor.
[in]Bsparse matrix \(B\) descriptor.
[in]betascalar \(\beta\).
[in]Dsparse matrix \(D\) descriptor.
[out]Csparse matrix \(C\) descriptor.
[in]compute_typefloating point precision for the SpGEMM computation.
[in]algSpGEMM algorithm for the SpGEMM computation.
[in]stageSpGEMM stage for the SpGEMM computation.
[out]buffer_sizenumber of bytes of the temporary storage buffer. buffer_size is set when temp_buffer is nullptr.
[in]temp_buffertemporary 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_successthe operation completed successfully.
rocsparse_status_invalid_handlethe library context was not initialized.
rocsparse_status_invalid_pointeralpha and beta are invalid, A, B, D, C or buffer_size pointer is invalid.
rocsparse_status_memory_erroradditional buffer for long rows could not be allocated.
rocsparse_status_not_implementedtrans_A != rocsparse_operation_none or trans_B != rocsparse_operation_none.

Member Function/Subroutine Documentation

◆ rocsparse_spgemm_()

integer(kind(rocsparse_status_success)) function hipfort_rocsparse::rocsparse_spgemm::rocsparse_spgemm_ ( type(c_ptr), value  handle,
integer(kind(rocsparse_operation_none)), value  trans_A,
integer(kind(rocsparse_operation_none)), value  trans_B,
type(c_ptr), value  alpha,
type(c_ptr), value  A,
type(c_ptr), value  B,
type(c_ptr), value  beta,
type(c_ptr), value  D,
type(c_ptr), value  C,
integer(kind(rocsparse_datatype_f32_r)), value  compute_type,
integer(kind(rocsparse_spgemm_alg_default)), value  alg,
integer(kind(rocsparse_spgemm_stage_auto)), value  stage,
integer(c_size_t)  buffer_size,
type(c_ptr), value  temp_buffer 

The documentation for this interface was generated from the following file: