rocsparse_spgeam Interface Reference

rocsparse_spgeam Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_spgeam Interface Reference

Sparse matrix sparse matrix addition. More...

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_spgeam_ (handle, descr, mat_a, mat_b, mat_c, stage, buffer_size, temp_buffer, error)

Detailed Description

Sparse matrix sparse matrix addition.

rocsparse_spgeam multiplies the scalar \(\alpha\) with the sparse \(m \times n\) CSR matrix \(op(A)\) and adds it to \(\beta\) multiplied by the sparse \(m \times n\) matrix \(op(B)\). The final result is stored in the sparse \(m \times n\) matrix \(C\), such that

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

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_spgeam requires multiple steps to complete. First, create a rocsparse_spgeam_descr by calling rocsparse_create_spgeam_descr. Set the SpGEAM algorithm (currently only rocsparse_spgeam_alg_default supported) as well as the compute type and the transpose operation type for the sparse matrices \(op(A)\) and \(op(B)\) using rocsparse_spgeam_set_input. Next, calculate the total non-zeros that will exist in the sparse matrix \(C\). To do so, call rocsparse_spgeam_buffer_size with the stage set to rocsparse_spgeam_stage_analysis. This will fill the buffer_size parameter, allowing allocation of this buffer. After the buffer has been allocated, call rocsparse_spgeam with the same stage rocsparse_spgeam_stage_analysis. The total non-zeros and the row offset array for \(C\) have now been calculated and are stored internally in the rocsparse_spgeam_descr. Now, retrieve the non-zero count using rocsparse_spgeam_get_output and then allocate the \(C\) matrix. To complete the computation, repeat the process (this time passing the stage rocsparse_spgeam_stage_compute ) by calling rocsparse_spgeam_buffer_size to determine the required buffer size, then allocate the buffer, and finally call rocsparse_spgeam. The user-allocated buffers can be freed after each call to rocsparse_spgeam. After the computation is complete and the SpGEAM descriptor is no longer needed, call rocsparse_destroy_spgeam_descr. See the full code example below.

The stage rocsparse_spgeam_stage_compute computes the symbolic part and the numeric of the resulting matrix C. To perform multiple operations involving matrices of same sparsity patterns but with different numerical values, the symbolic stages (rocsparse_spgeam_stage_symbolic_analysis and rocsparse_spgeam_stage_symbolic_compute ) and the numeric stages (rocsparse_spgeam_stage_numeric_analysis and rocsparse_spgeam_stage_numeric_compute ) can be used to separate the symbolic calculation from the numeric calculation.

Note: The stages rocsparse_spgeam_stage_analysis and rocsparse_spgeam_stage_compute cannot be mixed with the stages rocsparse_spgeam_stage_symbolic_analysis, rocsparse_spgeam_stage_symbolic_compute, rocsparse_spgeam_stage_numeric_analysis, and rocsparse_spgeam_stage_numeric_compute.; The stage rocsparse_spgeam_stage_analysis must precede the stage rocsparse_spgeam_stage_compute.; The stage rocsparse_spgeam_stage_symbolic_analysis must precede the stage rocsparse_spgeam_stage_symbolic_compute.; The stage rocsparse_spgeam_stage_numeric_analysis must precede the stage rocsparse_spgeam_stage_numeric_compute.; The symbolic stages are not required to perform the numeric stages.; The stage rocsparse_spgeam_stage_numeric_analysis must be reapplied if the numeric values of the input matrices mat_A and mat_B have changed between subsequent calls of the stage rocsparse_spgeam_stage_numeric_compute.

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

Note: This routine does not support batched computation.

Uniform Precisions:

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

Uniform Index Types:

CSR Uniform Index Types
CSR Row offset	CSR Column indices
rocsparse_indextype_i32	rocsparse_indextype_i32
rocsparse_indextype_i64	rocsparse_indextype_i64

Mixed Index Types:

CSR Mixed Index Types
CSR Row offset	CSR Column indices
rocsparse_indextype_i64	rocsparse_indextype_i32

In general, when adding two sparse matrices together, it is possible that the resulting matrix will require a larger index representation to store correctly. For example, when adding \(A + 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 type rocsparse_indextype_i64. This is currently not supported. In this scenario, store the \(A\), \(B\), and \(C\) matrices using the higher index precision.

Additionally, all three matrices \(A\), \(B\), and \(C\) must use the same index types. For example, if \(A\) uses the index type rocsparse_indextype_i32 for the row offset array and the index type rocsparse_indextype_i32 for the column indices array, then both \(B\) and \(C\) must also use these same index types for their respective row offset and column index arrays. In the scenario where \(C\) requires a larger index type for the row offset array, store all three matrices using the larger index type rocsparse_indextype_i64 for the row offsets array.

Note: Currently only CSR format is supported.; Currently, only trans_A == rocsparse_operation_none is supported.; Currently, only trans_B == rocsparse_operation_none is supported.; This routine does not support execution in a hipGraph context.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	descr	- SpGEAM descriptor.
[in]	mat_A	- sparse matrix \(A\) descriptor.
[in]	mat_B	- sparse matrix \(B\) descriptor.
[out]	mat_C	- sparse matrix \(C\) descriptor.
[in]	stage	- SpGEAM stage for the SpGEAM computation.
[out]	buffer_size	- number of bytes of the temporary storage buffer. `buffer_size` is determined by calling rocsparse_spgeam_buffer_size.
[in]	temp_buffer	- temporary storage buffer allocated by the user.
[out]	error	- error descriptor created if the returned status is not `rocsparse_status_success`. A null pointer can be passed if an error descriptor is not required.

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_handle	the library context was not initialized.
rocsparse_status_invalid_pointer	`mat_A`, `mat_B`, `mat_C`, `descr`, or `buffer_size` pointer is invalid.

First Example

Second Example

Member Function/Subroutine Documentation