rocsparse_spitsv Interface Reference

rocsparse_spitsv Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_spitsv Interface Reference

Sparse iterative triangular solve. More...

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_spitsv_ (handle, host_nmaxiter, host_tol, host_history, trans, alpha, mat, x, y, compute_type, alg, stage, buffer_size, temp_buffer)

Detailed Description

Sparse iterative triangular solve.

rocsparse_spitsv solves, using the Jacobi iterative method, a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in CSR format, a dense solution vector \(y\) and the right-hand side \(x\) that is multiplied by \(\alpha\), such that

\[ op(A) y = \alpha x, \]

with

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

The Jacobi method applied to the sparse triangular linear system above gives

\[ y_{k+1} = y_{k} + D^{-1} ( \alpha x - (D + T) y_{k} ) \]

with \(A = D + T\), \(D\) the diagonal of \(A\) and \(T\) the strict triangular part of \(A\).

The above equation can be also written as

\[ y_{k+1} = y_{k} + D^{-1} r_k \]

where

\[ r_k = \alpha x - (D + T) y_k. \]

Starting with \(y_0 = \) y, the method iterates while \( k \lt \) host_nmaxiter and until

\[ \Vert r_k \Vert_{\infty} ≤ \epsilon, \]

with \(\epsilon\) = host_tol.

rocsparse_spitsv requires three stages to complete. First, pass the rocsparse_spitsv_stage_buffer_size stage to determine the size of the required temporary storage buffer. Next, allocate this buffer and call rocsparse_spitsv again with the rocsparse_spitsv_stage_preprocess stage, which will preprocess data and store it in the temporary buffer. Finally, call rocsparse_spitsv with the rocsparse_spitsv_stage_compute stage to perform the actual computation. After all calls to rocsparse_spitsv are complete, the temporary buffer can be deallocated.

rocsparse_spitsv supports rocsparse_indextype_i32 and rocsparse_indextype_i64 index precisions for storing the row pointer and column indices arrays of the sparse matrix. rocsparse_spitsv supports the following data types for \(op(A)\), \(x\), \(y\), and compute types for \(\alpha\):

Uniform Precisions:

Uniform Precisions
A / X / Y / compute_type
rocsparse_datatype_f32_r
rocsparse_datatype_f64_r
rocsparse_datatype_f32_c
rocsparse_datatype_f64_c

Note: 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,out]	host_nmaxiter	- maximum number of iteration on input and number of iteration on output. If the output number of iterations is strictly less than the input maximum number of iterations, then the algorithm converged.
[in]	host_tol	- if the pointer is null, then the loop will execute `nmaxiter`[0] iterations. The precision is float for f32-based calculations (including the complex case) and double for f64-based calculations (including the complex case).
[out]	host_history	- Optional array to record the norm of the residual before each iteration. The precision is float for f32-based calculations (including the complex case) and double for f64-based calculations (including the complex case).
[in]	trans	- matrix operation type.
[in]	alpha	- scalar \(\alpha\).
[in]	mat	- matrix descriptor.
[in]	x	- vector descriptor.
[in,out]	y	- vector descriptor.
[in]	compute_type	- floating point precision for the SpITSV computation.
[in]	alg	- SpITSV algorithm for the SpITSV computation.
[in]	stage	- SpITSV stage for the SpITSV computation.
[out]	buffer_size	- number of bytes of the temporary storage buffer.
[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 SpITSV 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`, `mat`, `x`, `y`, `descr`, or `buffer_size` pointer is invalid.
rocsparse_status_not_implemented	`trans`, `compute_type`, `stage`, or `alg` is currently not supported.

Example

Member Function/Subroutine Documentation