rocsparse_sddmm Interface Reference

rocsparse_sddmm Interface Reference#

hipFORT API Reference: hipfort_rocsparse::rocsparse_sddmm Interface Reference

Sampled Dense-Dense Matrix Multiplication. More...

Public Member Functions
integer(c_int) function	rocsparse_sddmm_ (handle, opa, opb, alpha, mat_a, mat_b, beta, mat_c, compute_type, alg, temp_buffer)

Detailed Description

Sampled Dense-Dense Matrix Multiplication.

rocsparse_sddmm multiplies the scalar \(\alpha\) with the dense \(m \times k\) matrix \(op(A)\), the dense \(k \times n\) matrix \(op(B)\), filtered by the sparsity pattern of the \(m \times n\) sparse matrix \(C\) and adds the result to \(C\) scaled by \(\beta\). The final result is stored in the sparse \(m \times n\) matrix \(C\), such that

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

with

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

,

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

and

\[ spy(C)_{ij} = \left\{ \begin{array}{ll} 1, & \text{ if C_{ij} != 0} \\% 0, & \text{ otherwise} \\% \end{array} \right. \]

Computing the above sampled dense-dense multiplication requires three steps to complete. First, call rocsparse_sddmm_buffer_size to determine the size of the required temporary storage buffer. Next, allocate this buffer and call rocsparse_sddmm_preprocess, which performs any analysis of the input matrices that might be required. Finally, call rocsparse_sddmm to complete the computation. After all calls to rocsparse_sddmm are complete, the temporary buffer can be deallocated.

rocsparse_sddmm supports different algorithms which can provide better performance for different matrices.

Algorithms
Algorithms	Deterministic	Preprocessing	Notes
rocsparse_sddmm_alg_default	Yes	No	Uses the sparsity pattern of matrix C to perform a limited set of dot products.
rocsparse_sddmm_alg_dense	Yes	No	Explicitly converts the matrix C into a dense matrix to perform a dense matrix multiply and add.

Currently, rocsparse_sddmm only supports the uniform precisions indicated in the table below. For the sparse matrix \(C\), rocsparse_sddmm supports the index types rocsparse_indextype_i32 and rocsparse_indextype_i64.

Uniform Precisions:

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

Mixed Precisions:

Mixed Precisions
A / B	C	compute_type
rocsparse_datatype_f16_r	rocsparse_datatype_f32_r	rocsparse_datatype_f32_r
rocsparse_datatype_f16_r	rocsparse_datatype_f16_r	rocsparse_datatype_f32_r
rocsparse_datatype_bf16_r	rocsparse_datatype_f32_r	rocsparse_datatype_f32_r
rocsparse_datatype_bf16_r	rocsparse_datatype_bf16_r	rocsparse_datatype_f32_r

Note: The sparse matrix formats currently supported are: rocsparse_format_csr, rocsparse_format_csc, rocsparse_format_coo, rocsparse_format_coo_aos, and rocsparse_format_ell.; opA == rocsparse_operation_conjugate_transpose is not supported.; opB == rocsparse_operation_conjugate_transpose is not supported.; This routine supports execution in a hipGraph context only when alg == rocsparse_sddmm_alg_default.; Batched computation is supported for the rocsparse_format_csr, rocsparse_format_csc, rocsparse_format_coo, rocsparse_format_coo_aos and rocsparse_format_ell formats when alg == rocsparse_sddmm_alg_default. The batch count is taken from the sparse matrix \(C\). Each of the dense matrices \(A\) and \(B\) must either use the same batch count as \(C\), or be configured with batch count 1 and batch stride 0 in order to broadcast that operand across all batches of \(C\). Concretely, the following four configurations are accepted:
\[ \begin{aligned} &C_i = (A \cdot B ) \circ C_i, &&\text{(both A and B broadcast)} \\% &C_i = (A \cdot B_i) \circ C_i, &&\text{(A broadcast)} \\% &C_i = (A_i \cdot B ) \circ C_i, &&\text{(B broadcast)} \\% &C_i = (A_i \cdot B_i) \circ C_i, &&\text{(fully batched)} \end{aligned} \]
Per-batch strides for the dense operands are configured via rocsparse_dnmat_set_strided_batch, while the per-batch strides for the sparse output \(C\) are configured with the format-specific routine: rocsparse_coo_set_strided_batch for rocsparse_format_coo, rocsparse_csr_set_strided_batch for rocsparse_format_csr, rocsparse_csc_set_strided_batch for rocsparse_format_csc and rocsparse_format_coo_aos, and rocsparse_ell_set_strided_batch for rocsparse_format_ell.

For COO, rocsparse_coo_set_strided_batch sets a single per-batch stride that applies to all three COO buffers (row indices, column indices and values); i.e. the row-index, column-index and value buffers of batch \(i\) are obtained from the base pointers by adding i * batch_stride, and must therefore be laid out with the same stride. The stride must be at least the per-batch nnz of \(C\), and may be larger to allow padding.

For CSR, rocsparse_csr_set_strided_batch sets two independent per-batch strides: offsets_batch_stride for the row offset buffer and columns_values_batch_stride for the column-index and value buffers. The row offset buffer of batch \(i\) is obtained from the base pointer by adding i * offsets_batch_stride, and the column-index and value buffers of batch \(i\) by adding i * columns_values_batch_stride. The offsets stride must be at least \(m + 1\), and the columns/values stride must be at least the per-batch nnz of \(C\); both may be larger to allow padding.

For CSC, rocsparse_csc_set_strided_batch sets two independent per-batch strides: offsets_batch_stride for the column offset buffer and rows_values_batch_stride for the row-index and value buffers. The column offset buffer of batch \(i\) is obtained from the base pointer by adding i * offsets_batch_stride, and the row-index and value buffers of batch \(i\) by adding i * rows_values_batch_stride. The offsets stride must be at least \(n + 1\), and the rows/values stride must be at least the per-batch nnz of \(C\); both may be larger to allow padding.

For COO AoS, rocsparse_coo_set_strided_batch sets a single per-batch stride batch_stride that is interpreted as the per-batch nnz stride of the value buffer. Because the row and column indices are stored interleaved in a single buffer (two index entries per nonzero), the interleaved index buffer of batch \(i\) is obtained from the base pointer by adding i * (2 * batch_stride), while the value buffer of batch \(i\) is obtained by adding i * batch_stride. The stride must be at least the per-batch nnz of \(C\), and can be larger to allow padding.

For ELL, rocsparse_ell_set_strided_batch sets a single per-batch stride that applies to both ELL buffers (column indices and values); i.e. the column-index and value buffers of batch \(i\) are obtained from the base pointers by adding i * batch_stride, and must therefore be laid out with the same stride. The stride must be at least the per-batch nnz of \(C\), and may be larger to allow padding.

All other formats and algorithms currently return rocsparse_status_not_implemented when the batch count is greater than one.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	opA	- dense matrix \(A\) operation type.
[in]	opB	- dense matrix \(B\) operation type.
[in]	alpha	- scalar \(\alpha\).
[in]	mat_A	- dense matrix \(A\) descriptor.
[in]	mat_B	- dense matrix \(B\) descriptor.
[in]	beta	- scalar \(\beta\).
[in,out]	mat_C	- sparse matrix \(C\) descriptor.
[in]	compute_type	- floating point precision for the SDDMM computation.
[in]	alg	- specification of the algorithm to use.
[in]	temp_buffer	- temporary storage buffer allocated by the user. The size must be greater or equal to the size obtained with rocsparse_sddmm_buffer_size.

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_value	the value of `opA`, `opB`, `compute_type`, or `alg` is incorrect.
rocsparse_status_invalid_handle	the library context was not initialized.
rocsparse_status_invalid_pointer	`alpha` and `beta` are invalid, or the `mat_A`, `mat_B`, `mat_C`, or `temp_buffer` pointer is invalid.
rocsparse_status_not_implemented	`opA` == `rocsparse_operation_conjugate_transpose` or `opB` == `rocsparse_operation_conjugate_transpose`.

Example: This example performs a sampled dense-dense matrix product, \(C := \alpha ( A \cdot B ) \circ spy(C) + \beta C\) where \(\circ\) is the Hadamard product.

Member Function/Subroutine Documentation

◆ rocsparse_sddmm_()

integer(c_int) function hipfort_rocsparse::rocsparse_sddmm::rocsparse_sddmm_	(	type(c_ptr), value	handle,
		integer(c_int), value	opa,
		integer(c_int), value	opb,
		type(c_ptr), value	alpha,
		type(c_ptr), value	mat_a,
		type(c_ptr), value	mat_b,
		type(c_ptr), value	beta,
		type(c_ptr), value	mat_c,
		integer(c_int), value	compute_type,
		integer(c_int), value	alg,
		type(c_ptr), value	temp_buffer
	)

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

hipfort_rocsparse.F90

rocsparse_sddmm Interface Reference

rocsparse_sddmm Interface Reference#

Public Member Functions

Detailed Description

Member Function/Subroutine Documentation

◆ rocsparse_sddmm_()