hipsparsescsrsv2_solve Interface Reference

hipsparsescsrsv2_solve Interface Reference#

HIPFORT API Reference: hipfort_hipsparse::hipsparsescsrsv2_solve Interface Reference

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

Public Member Functions
integer(kind(hipsparse_status_success)) function	hipsparsescsrsv2_solve_ (handle, transa, m, nnz, alpha, descra, csrsortedvala, csrsortedrowptra, csrsortedcolinda, myinfo, f, x, policy, pbuffer)

integer(kind(hipsparse_status_success)) function	hipsparsescsrsv2_solve_rank_0 (handle, transa, m, nnz, alpha, descra, csrsortedvala, csrsortedrowptra, csrsortedcolinda, myinfo, f, x, policy, pbuffer)

integer(kind(hipsparse_status_success)) function	hipsparsescsrsv2_solve_rank_1 (handle, transa, m, nnz, alpha, descra, csrsortedvala, csrsortedrowptra, csrsortedcolinda, myinfo, f, x, policy, pbuffer)

Detailed Description

Sparse triangular solve using the CSR storage format.

hipsparseXcsrsv2_solve solves a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in CSR 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 == HIPSPARSE_OPERATION_NON_TRANSPOSE} \\% A^T, & \text{if trans == HIPSPARSE_OPERATION_TRANSPOSE} \\% A^H, & \text{if trans == HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE} \end{array} \right. \]

Performing the above operation requires three steps. First, the user calls hipsparseScsrsv2_bufferSize "hipsparseXcsrsv2_bufferSize()" (or hipsparseScsrsv2_bufferSizeExt "hipsparseXcsrsv2_bufferSizeExt()") which will determine the size of the required temporary storage buffer. The user then allocates this buffer and calls hipsparseScsrsv2_analysis "hipsparseXcsrsv2_analysis()" which will perform analysis on the sparse matrix \(op(A)\). Finally, the user completes the computation by calling hipsparseXcsrsv2_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 hipsparseXcsrsv2_solve are complete, the temporary buffer can be deallocated.

Solving a triangular system involves division by the diagonal elements. This means that if the sparse matrix is missing the diagonal entry (referred to as a structural zero) or the diagonal entry is zero (referred to as a numerical zero), then a division by zero would occur. hipsparseXcsrsv2_solve tracks the location of the first zero pivot (either numerical or structural zero). The zero pivot status can be checked by calling hipsparseXcsrsv2_zeroPivot (). If hipsparseXcsrsv2_zeroPivot () returns HIPSPARSE_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 ones on the diagonal by setting the diagonal type on the descriptor descrA to HIPSPARSE_DIAG_TYPE_UNIT using hipsparseSetMatDiagType. If hipsparseDiagType_t == HIPSPARSE_DIAG_TYPE_UNIT, no zero pivot will be reported, even if \(A_{j,j} = 0\) for some \(j\).

The sparse CSR matrix passed to hipsparseXcsrsv2_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 hipsparseFillMode_t set on the descriptor descrA. If the fill mode is set to HIPSPARSE_FILL_MODE_LOWER, then the lower triangular matrix is solved. If the fill mode is set to HIPSPARSE_FILL_MODE_UPPER, then the upper triangular matrix is solved.

Note: The sparse CSR matrix has to be sorted. This can be achieved by calling hipsparseXcsrsort().; This function is non-blocking and executed asynchronously with respect to the host. It can return before the actual computation has finished.; Currently, only transA == HIPSPARSE_OPERATION_NON_TRANSPOSE and transA == HIPSPARSE_OPERATION_TRANSPOSE is supported.

Parameters

[in]	handle	- handle to the hipSPARSE library context queue.
[in]	transA	- matrix operation type.
[in]	m	- number of rows of the sparse CSR matrix.
[in]	nnz	- number of non-zero entries of the sparse CSR matrix.
[in]	alpha	- scalar \(\alpha\).
[in]	descrA	- descriptor of the sparse CSR matrix.
[in]	csrSortedValA	- array of `nnz` elements of the sparse CSR matrix.
[in]	csrSortedRowPtrA	- array of `m+1` elements that point to the start of every row of the sparse CSR matrix.
[in]	csrSortedColIndA	- array of `nnz` elements containing the column indices of the sparse CSR matrix.
[in]	myInfo	- structure that holds the information collected during the analysis step.
[in]	f	- array of `m` elements, holding the right-hand side.
[out]	x	- array of `m` elements, holding the solution.
[in]	policy	- `HIPSPARSE_SOLVE_POLICY_NO_LEVEL` or `HIPSPARSE_SOLVE_POLICY_USE_LEVEL`.
[in]	pBuffer	- temporary storage buffer allocated by the user.

Return values

HIPSPARSE_STATUS_SUCCESS	the operation completed successfully.
HIPSPARSE_STATUS_INVALID_VALUE	`handle`, `m`, `nnz`, `descrA`, `alpha`, `csrSortedValA`, `csrSortedRowPtrA`, `csrSortedColIndA`, `f`, or `x` is invalid.
HIPSPARSE_STATUS_ARCH_MISMATCH	the device is not supported.
HIPSPARSE_STATUS_INTERNAL_ERROR	an internal error occurred.
HIPSPARSE_STATUS_NOT_SUPPORTED	`transA` == `HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE` or `hipsparseMatrixType_t` != `HIPSPARSE_MATRIX_TYPE_GENERAL`.

Member Function/Subroutine Documentation