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 \(op(A)\) and the sparse \(k \times n\) matrix \(op(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} \end{array} \right. \]

and

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

rocsparse_spgemm requires three stages to complete. First, pass the rocsparse_spgemm_stage_buffer_size stage to determine the size of the required temporary storage buffer. Next, allocate this buffer and call rocsparse_spgemm again with the rocsparse_spgemm_stage_nnz stage, which will determine the number of non-zeros in \(C\). This stage will also fill in the row pointer array of \(C\). Now that the number of non-zeros in \(C\) is known, allocate space for the column indices and values arrays of \(C\). Finally, call rocsparse_spgemm with the rocsparse_spgemm_stage_compute stage to perform the actual computation, which fills in the column indices and values arrays of \(C\). After all calls to rocsparse_spgemm are complete, the temporary buffer can be deallocated.

Alternatively, it is possible to perform sparse matrix products multiple times with matrices having the same sparsity pattern with different values. In this scenario, the process begins like before. First, call rocsparse_spgemm with stage rocsparse_spgemm_stage_buffer_size to determine the required buffer size. Then allocate this buffer and call rocsparse_spgemm with the stage rocsparse_spgemm_stage_nnz to determine the number of non-zeros in \(C\) and allocate the \(C\) column indices and values arrays. Now, however, call rocsparse_spgemm with the rocsparse_spgemm_stage_symbolic stage, which will fill in the column indices array of \(C\) but not the values array. It is then possible to repeatedly change the values of \(A\), \(B\), and \(D\) and call rocsparse_spgemm with the rocsparse_spgemm_stage_numeric stage, which fills the values array of \(C\). The use of the extra rocsparse_spgemm_stage_symbolic and rocsparse_spgemm_stage_numeric stages allows users to compute the sparsity pattern of \(C\) once, but compute the values multiple times.

rocsparse_spgemm supports multiple combinations of data types and compute types. The tables below indicate the currently supported different data types that can be used for the sparse matrices \(op(A)\), \(op(B)\), \(C\), and \(D\), and the compute type for \(\alpha\) and \(\beta\). The advantage of using different data types is to save on memory bandwidth and storage when a user application allows, while performing the actual computation in a higher precision.

Uniform Precisions:

Uniform Precisions
A / B / C / D / compute_type
rocsparse_datatype_f16_r
rocsparse_datatype_bf16_r
rocsparse_datatype_f32_r
rocsparse_datatype_f64_r
rocsparse_datatype_f32_c
rocsparse_datatype_f64_c

rocsparse_spgemm supports rocsparse_indextype_i32 and rocsparse_indextype_i64 index precisions for storing the row pointer and column indices arrays of the sparse matrices.

In general, when multiplying two sparse matrices together, it is possible that the resulting matrix will require a larger index representation to store correctly. For example, when multiplying \(A \times B\) using rocsparse_indextype_i32 index types for the row pointer and column indices arrays, it might be the case that the row pointer of the resulting \(C\) matrix would require index precision rocsparse_indextype_i64. This is currently not supported. In this scenario, the \(A\) and \(B\) matrices need to be stored using the higher index precision.

Note: This function does not produce deterministic results.; 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 \(\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.; Currently only CSR and BSR formats are supported.; If rocsparse_spgemm_stage_symbolic is selected, then only the symbolic computation is performed.; If rocsparse_spgemm_stage_numeric is selected, then only the numeric computation is performed.; For the rocsparse_spgemm_stage_symbolic and rocsparse_spgemm_stage_numeric stages, only the CSR matrix format is currently supported.; \(\alpha == beta == 0\) is invalid.; It is permissible 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 can return before the actual computation has finished.; Note that for rare matrix products with more than 4096 non-zero entries per row, an additional temporary storage buffer is allocated by the algorithm.; This routine does not support execution in a hipGraph context.; This routine does not support batched computation.

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 the 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, or the `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`.

Example

Member Function/Subroutine Documentation