rocsparse_sbsrsv_solve Interface Reference

rocsparse_sbsrsv_solve Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_sbsrsv_solve Interface Reference

Sparse triangular solve using the BSR storage format. More...

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_sbsrsv_solve_ (handle, dir, trans, mb, nnzb, alpha, descr, bsr_val, bsr_row_ptr, bsr_col_ind, block_dim, myinfo, x, y, policy, temp_buffer)

integer(kind(rocsparse_status_success)) function	rocsparse_sbsrsv_solve_rank_0 (handle, dir, trans, mb, nnzb, alpha, descr, bsr_val, bsr_row_ptr, bsr_col_ind, block_dim, myinfo, x, y, policy, temp_buffer)

integer(kind(rocsparse_status_success)) function	rocsparse_sbsrsv_solve_rank_1 (handle, dir, trans, mb, nnzb, alpha, descr, bsr_val, bsr_row_ptr, bsr_col_ind, block_dim, myinfo, x, y, policy, temp_buffer)

Detailed Description

Sparse triangular solve using the BSR storage format.

rocsparse_bsrsv_solve solves a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in BSR storage format, a dense solution vector \(y\), and the right-hand side \(x\) that is multiplied by \(\alpha\), such that

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

with

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

Performing the above operation requires three steps. First, call rocsparse_Xbsrsv_buffer_size(), which will determine the size of the required temporary storage buffer. Then allocate this buffer and call rocsparse_Xbsrsv_analysis(), which will perform analysis on the sparse matrix \(op(A)\). Finally, complete the computation by calling rocsparse_bsrsv_solve. The buffer size, buffer allocation, and analysis only need to be called once for a given sparse matrix \(op(A)\), while the computation stage can be repeatedly used with different \(x\) and \(y\) vectors. After all calls to rocsparse_bsrsv_solve are complete, the temporary buffer can be deallocated.

Solving a triangular system involves inverting the diagonal blocks. This means that if the sparse matrix is missing the diagonal block (referred to as a structural zero) or the diagonal block is not invertible (referred to as a numerical zero), then a solution is not possible. rocsparse_bsrsv_solve tracks the location of the first zero pivot (either numerical or structural zero). The zero pivot status can be checked by calling rocsparse_bsrsv_zero_pivot (). If rocsparse_bsrsv_zero_pivot () returns rocsparse_status_success, then no zero pivot was found and therefore the matrix does not have a structural or numerical zero.

The user can specify that the sparse matrix should be interpreted as having identity blocks on the diagonal by setting the diagonal type on the descriptor descr to rocsparse_diag_type_unit using rocsparse_set_mat_diag_type. If rocsparse_diag_type == rocsparse_diag_type_unit, no zero pivot will be reported, even if the diagonal block \(A_{j,j}\) for some \(j\) is not invertible.

The sparse CSR matrix passed to rocsparse_bsrsv_solve does not actually have to be a triangular matrix. Instead, the triangular upper or lower part of the sparse matrix is solved based on rocsparse_fill_mode set on the descriptor descr. If the fill mode is set to rocsparse_fill_mode_lower, then the lower triangular matrix is solved. If the fill mode is set to rocsparse_fill_mode_upper, then the upper triangular matrix is solved.

Note: The sparse BSR matrix has to be sorted.; This function is non-blocking and executed asynchronously with respect to the host. It can return before the actual computation has finished.; Currently, only trans == rocsparse_operation_none and trans == rocsparse_operation_transpose are supported.; This routine supports execution in a hipGraph context.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	dir	- matrix storage of BSR blocks.
[in]	trans	- matrix operation type.
[in]	mb	- number of block rows of the sparse BSR matrix.
[in]	nnzb	- number of non-zero blocks of the sparse BSR matrix.
[in]	alpha	- scalar \(\alpha\).
[in]	descr	- descriptor of the sparse BSR matrix.
[in]	bsr_val	- array of `nnzb` blocks of the sparse BSR matrix.
[in]	bsr_row_ptr	- array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.
[in]	bsr_col_ind	- array of `nnz` containing the block column indices of the sparse BSR matrix.
[in]	block_dim	- block dimension of the sparse BSR matrix.
[in]	myInfo	- structure that holds the information collected during the analysis step.
[in]	x	- array of `m` elements, holding the right-hand side.
[out]	y	- array of `m` elements, holding the solution.
[in]	policy	- `rocsparse_solve_policy_auto`.
[in]	temp_buffer	- temporary storage buffer allocated by the user.

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_handle	the library context was not initialized.
rocsparse_status_invalid_size	`mb`, `nnzb`, or `block_dim` is invalid.
rocsparse_status_invalid_pointer	`descr`, `alpha`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `x`, or `y` pointer is invalid.
rocsparse_status_arch_mismatch	the device is not supported.
rocsparse_status_internal_error	an internal error occurred.
rocsparse_status_not_implemented	`trans` == `rocsparse_operation_conjugate_transpose` or `rocsparse_matrix_type` != `rocsparse_matrix_type_general`.

Example: Consider the lower triangular \(m \times m\) matrix \(L\), stored in BSR storage format with unit diagonal. The following example solves \(L \cdot y = x\).

Member Function/Subroutine Documentation