rocsparse_scsritsv_solve Interface Reference

rocsparse_scsritsv_solve Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_scsritsv_solve Interface Reference

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

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_scsritsv_solve_ (handle, host_nmaxiter, host_tol, host_history, trans, m, nnz, alpha, descr, csr_val, csr_row_ptr, csr_col_ind, myinfo, x, y, policy, temp_buffer)

Detailed Description

Sparse iterative triangular solve using the CSR storage format.

rocsparse_csritsv_solve solves iteratively, with the use of the Jacobi method, 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) 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 if \( 0 ≤ k \lt \) host_nmaxiter and if

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

with \(\epsilon\) = host_tol.

rocsparse_csritsv_solve requires a user allocated temporary buffer. Its size is returned by rocsparse_Xcsritsv_buffer_size(). In addition, analysis metadata is required. It can be obtained by rocsparse_Xcsritsv_analysis(). rocsparse_csritsv_solve reports the first zero pivot (either numerical or structural zero). The zero pivot status can be checked by calling rocsparse_csritsv_zero_pivot(). If rocsparse_diag_type == rocsparse_diag_type_unit, no zero pivot will be reported, even if \(A_{j,j} = 0\) for some \(j\).

Note: The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().; This function is blocking with respect to the host.; This routine does not support execution in a hipGraph context.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in,out]	host_nmaxiter	- maximum number of iterations on input and number of iterations 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 loop will execute `nmaxiter`[0] iterations.
[out]	host_history	- optional array to record the norm of the residual before each iteration.
[in]	trans	- 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]	descr	- descriptor of the sparse CSR matrix.
[in]	csr_val	- array of `nnz` elements of the sparse CSR matrix.
[in]	csr_row_ptr	- array of `m+1` elements that point to the start of every row of the sparse CSR matrix.
[in]	csr_col_ind	- 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]	x	- array of `m` elements, holding the right-hand side.
[in,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	`m` or `nnz` is invalid.
rocsparse_status_invalid_pointer	`descr`, `alpha`, `csr_val`, `csr_row_ptr`, `csr_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	`rocsparse_matrix_type` != `rocsparse_matrix_type_general` and `rocsparse_matrix_type` != `rocsparse_matrix_type_triangular`.

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

rocsparse_handle handle;

rocsparse_create_handle(&handle);

// Create matrix descriptor

rocsparse_mat_descr descr;

rocsparse_create_mat_descr(&descr);

rocsparse_set_mat_fill_mode(descr, rocsparse_fill_mode_lower);

rocsparse_set_mat_diag_type(descr, rocsparse_diag_type_unit);

// Create matrix info structure

rocsparse_mat_info info;

rocsparse_create_mat_info(&info);

// Obtain required buffer size

size_t buffer_size;

rocsparse_dcsritsv_buffer_size(handle,

rocsparse_operation_none,

m,

nnz,

descr,

csr_val,

csr_row_ptr,

csr_col_ind,

info,

&buffer_size);

// Allocate temporary buffer

void* temp_buffer;

hipMalloc(&temp_buffer, buffer_size);

// Perform analysis step

rocsparse_dcsritsv_analysis(handle,

rocsparse_operation_none,

m,

nnz,

descr,

csr_val,

csr_row_ptr,

csr_col_ind,

info,

rocsparse_analysis_policy_reuse,

rocsparse_solve_policy_auto,

temp_buffer);

// Solve Ly = x

rocsparse_int nmaxiter = 200;

rocsparse_int host_maxiter = nmaxiter;

double host_tol = 1.0e-4;

double host_history[200];

// Initialization of y

hipMemset(y, 0, sizeof(double) * m);

rocsparse_dcsritsv_solve(handle,

&host_maxiter,

&host_tol,

host_history,

rocsparse_operation_none,

m,

nnz,

&alpha,

descr,

csr_val,

csr_row_ptr,

csr_col_ind,

info,

x,

y,

rocsparse_solve_policy_auto,

temp_buffer);

if (host_maxiter < nmaxiter)

{

printf("convergence");

}

else

{

printf("no convergence");

}

for (int i=0;i<=host_maxiter;++i)

{

printf("iter = %d, nrm inf residual=%e", i, host_history[i]);

}

// No zero pivot should be found, with L having unit diagonal

// Clean up

hipFree(temp_buffer);

rocsparse_destroy_mat_info(info);

rocsparse_destroy_mat_descr(descr);

rocsparse_destroy_handle(handle);

hipfort_rocsparse::rocsparse_create_handle
Create a rocSPARSE handle.
Definition hipfort_rocsparse.F90:47

hipfort_rocsparse::rocsparse_create_mat_descr
Create a matrix descriptor.
Definition hipfort_rocsparse.F90:436

hipfort_rocsparse::rocsparse_create_mat_info
Create a matrix info structure.
Definition hipfort_rocsparse.F90:795

hipfort_rocsparse::rocsparse_dcsritsv_analysis
Definition hipfort_rocsparse.F90:20994

hipfort_rocsparse::rocsparse_dcsritsv_buffer_size
Definition hipfort_rocsparse.F90:20859

hipfort_rocsparse::rocsparse_dcsritsv_solve
Definition hipfort_rocsparse.F90:21322

hipfort_rocsparse::rocsparse_set_mat_diag_type
Specify the matrix diagonal type of a matrix descriptor.
Definition hipfort_rocsparse.F90:640

hipfort_rocsparse::rocsparse_set_mat_fill_mode
Specify the matrix fill mode of a matrix descriptor.
Definition hipfort_rocsparse.F90:595

hipfort_rocsparse_enums::rocsparse_diag_type_unit
@ rocsparse_diag_type_unit
Definition hipfort_rocsparse_enums.F90:57

hipfort_rocsparse_enums::rocsparse_solve_policy_auto
@ rocsparse_solve_policy_auto
Definition hipfort_rocsparse_enums.F90:99

hipfort_rocsparse_enums::rocsparse_analysis_policy_reuse
@ rocsparse_analysis_policy_reuse
Definition hipfort_rocsparse_enums.F90:93

hipfort_rocsparse_enums::rocsparse_operation_none
@ rocsparse_operation_none
Definition hipfort_rocsparse_enums.F90:35

hipfort_rocsparse_enums::rocsparse_fill_mode_lower
@ rocsparse_fill_mode_lower
Definition hipfort_rocsparse_enums.F90:62

Member Function/Subroutine Documentation