Generic API Functions¶

nvpl_sparse_spmv()¶

nvpl_sparse_status_t
nvpl_sparse_spmv_buffer_size(nvpl_sparse_handle_t        handle,
                     nvpl_sparse_operation_t             op_A,
                     const void*                         alpha,
                     nvpl_sparse_const_sp_mat_descr_t    mat_A,
                     nvpl_sparse_const_dn_vec_descr_t    vec_X,
                     const void*                         beta,
                     nvpl_sparse_dn_vec_descr_t          vec_Y,
                     nvpl_sparse_dn_vec_descr_t          vec_Z,
                     nvpl_sparse_data_type_t             compute_type,
                     nvpl_sparse_spmv_alg_t              alg,
                     nvpl_sparse_spmv_descr_t            spmv_descr,
                     size_t*                             buffer_size)

nvpl_sparse_status_t
nvpl_sparse_spmv_analysis(nvpl_sparse_handle_t           handle,
                     nvpl_sparse_operation_t             op_A,
                     const void*                         alpha,
                     nvpl_sparse_const_sp_mat_descr_t    mat_A,
                     nvpl_sparse_const_dn_vec_descr_t    vec_X,
                     const void*                         beta,
                     nvpl_sparse_dn_vec_descr_t          vec_Y,
                     nvpl_sparse_dn_vec_descr_t          vec_Z,
                     nvpl_sparse_data_type_t             compute_type,
                     nvpl_sparse_spmv_alg_t              alg,
                     nvpl_sparse_spmv_descr_t            spmv_descr,
                     void*                               external_buffer)

nvpl_sparse_status_t
nvpl_sparse_spmv(nvpl_sparse_handle_t        handle,
          nvpl_sparse_operation_t            op_A,
          const void*                        alpha,
          nvpl_sparse_const_sp_mat_descr_t   mat_A,
          nvpl_sparse_const_dn_vec_descr_t   vec_X,
          const void*                        beta,
          nvpl_sparse_dn_vec_descr_t         vec_Y,
          nvpl_sparse_dn_vec_descr_t         vec_Z,
          nvpl_sparse_data_type_t            compute_type,
          nvpl_sparse_spmv_alg_t             alg,
          nvpl_sparse_spmv_descr_t           spmv_descr)

This function performs the multiplication of a sparse matrix mat_A and a dense vector vec_X

\(\mathbf{Z} = \alpha op\left( \mathbf{A} \right) \cdot \mathbf{X} + \beta\mathbf{Y}\)

where

op(A) is a sparse matrix of size \(m \times k\)
X is a dense vector of size \(k\)
Y is a dense vector of size \(m\)
Z is a dense vector of size \(m\)
\(\alpha\) and \(\beta\) are scalars

Also, for matrix A

\(\text{op}(A) == \begin{cases} A & \text{if op(A) == NVPL_SPARSE_OPERATION_NON_TRANSPOSE} \\ A^{T} & \text{if op(A) == NVPL_SPARSE_OPERATION_TRANSPOSE} \\ A^{H} & \text{if op(A) ==NVPL_SPARSE_OPERATION_CONJUGATE_TRANSPOSE} \\ \end{cases}\)

The function nvpl_sparse_spmv_buffer_size() returns the size of the workspace needed by nvpl_sparse_spmv_analysis()

Param.	In/out	Meaning
`handle`	IN	Handle to the NVPL Sparse library context
`op_A`	IN	Operation `op(A)`
`alpha`	IN	\(\alpha\) scalar used for multiplication of type `compute_type`
`mat_A`	IN	Sparse matrix `A`
`vec_X`	IN	Dense vector `X`
`beta`	IN	\(\beta\) scalar used for multiplication of type `compute_type`
`vec_Y`	IN	Dense vector `Y`
`vec_Z`	OUT	Dense vector `Z`
`compute_type`	IN	Datatype in which the computation is executed
`alg`	IN	Algorithm for the computation
`buffer_size`	OUT	Number of bytes of workspace needed by `nvpl_sparse_spmv_analysis` and `nvpl_sparse_spmv`
`external_buffer`	IN/OUT	Pointer to a workspace buffer of at least `buffer_size` bytes used by `nvpl_sparse_spmv_analysis` and `nvpl_sparse_spmv()`
`spmv_descr`	IN/OUT	Opaque descriptor for storing internal data used across the three steps

The sparse matrix formats currently supported are listed below:

NVPL_SPARSE_FORMAT_COO
NVPL_SPARSE_FORMAT_CSR
NVPL_SPARSE_FORMAT_CSC
NVPL_SPARSE_FORMAT_SLICED_ELL

nvpl_sparse_spmv supports the following index type for representing the sparse matrix mat_A:

32-bit indices (NVPL_SPARSE_INDEX_32I)
64-bit indices (NVPL_SPARSE_INDEX_64I)

nvpl_sparse_spmv() supports the following data types:

Uniform-precision computation:

`A`/`X`/`Y`/`Z`/`computeType`
`NVPL_SPARSE_R_32F`
`NVPL_SPARSE_R_64F`
`NVPL_SPARSE_C_32F`
`NVPL_SPARSE_C_64F`

nvpl_sparse_spmv() supports the following algorithms:

Algorithm	Notes
`NVPL_SPARSE_SPMV_ALG_DEFAULT`	Default algorithm for any sparse matrix format.
`NVPL_SPARSE_SPMV_COO_ALG1`	Default algorithm for COO sparse matrix format. May produce slightly different results during different runs with the same input parameters.
`NVPL_SPARSE_SPMV_CSR_ALG1`	Default algorithm for CSR/CSC sparse matrix format. May produce slightly different results during different runs with the same input parameters.
`NVPL_SPARSE_SPMV_SELL_ALG1`	Default algorithm for Sliced Ellpack sparse matrix format. Provides deterministic (bit-wise) results for each run.

Performance notes:

NVPL_SPARSE_SPMV_CSR_ALG1 provide higher performance than NVPL_SPARSE_SPMV_COO_ALG1.

nvpl_sparse_spmv() has the following properties:

The routine requires extra storage for CSR/CSC format.
The routine allows the indices of matA to be unsorted.

See nvpl_sparse_status_t for the description of the return status.

nvpl_sparse_spsv()¶

nvpl_sparse_status_t
nvpl_sparse_spsv_create_descr(nvpl_sparse_spsv_descr_t* descr)

nvpl_sparse_status_t
nvpl_sparse_spsv_destroy_descr(nvpl_sparse_spsv_descr_t descr)

nvpl_sparse_status_t
nvpl_sparse_spsv_buffer_size(nvpl_sparse_handle_t        handle,
                     nvpl_sparse_operation_t             op_A,
                     const void*                         alpha,
                     nvpl_sparse_const_sp_mat_descr_t    mat_A,
                     nvpl_sparse_const_dn_vec_descr_t    vec_X,
                     nvpl_sparse_dn_vec_descr_t          vec_Y,
                     nvpl_sparse_data_type_t             compute_type,
                     nvpl_sparse_spsv_alg_t              alg,
                     nvpl_sparse_spsv_descr_t            spsv_descr,
                     size_t*                             buffer_size)

nvpl_sparse_status_t
nvpl_sparse_spsv_analysis(nvpl_sparse_handle_t           handle,
                   nvpl_sparse_operation_t               op_A,
                   const void*                           alpha,
                   nvpl_sparse_const_sp_mat_descr_t      mat_A,
                   nvpl_sparse_const_dn_vec_descr_t      vec_X,
                   nvpl_sparse_dn_vec_descr_t            vec_Y,
                   nvpl_sparse_data_type_t               compute_type,
                   nvpl_sparse_spsv_alg_t                alg,
                   nvpl_sparse_spsv_descr_t              spsv_descr,
                   void*                                 external_buffer)

nvpl_sparse_status_t
nvpl_sparse_spsv_solve(nvpl_sparse_handle_t              handle,
                nvpl_sparse_operation_t                  op_A,
                const void*                              alpha,
                nvpl_sparse_const_sp_mat_descr_t         mat_A,
                nvpl_sparse_const_dn_vec_descr_t         vec_X,
                nvpl_sparse_dn_vec_descr_t               vec_Y,
                nvpl_sparse_data_type_t                  compute_type,
                nvpl_sparse_spsv_alg_t                   alg,
                nvpl_sparse_spsv_descr_t                 spsv_descr)

nvpl_sparse_status_t
nvpl_sparse_spsv_update_matrix(nvpl_sparse_handle_t       handle,
                                            nvpl_sparse_spsv_descr_t          spsv_descr,
                        void*                             new_values,
                        nvpl_sparse_spsv_update_t         update_part)

The function solves a system of linear equations whose coefficients are represented in a sparse triangular matrix:

\(op\left( \mathbf{A} \right) \cdot \mathbf{Y} = \alpha\mathbf{X}\)

where

op(A) is a sparse square matrix of size \(m \times m\)
X is a dense vector of size \(m\)
Y is a dense vector of size \(m\)
\(\alpha\) is a scalar

Also, for matrix A

\(\text{op}(A) = \begin{cases} A & \text{if op(A) == NVPL_SPARSE_OPERATION_NON_TRANSPOSE} \\ A^{T} & \text{if op(A) == NVPL_SPARSE_OPERATION_TRANSPOSE} \\ A^{H} & \text{if op(A) == NVPL_SPARSE_OPERATION_CONJUGATE_TRANSPOSE} \\ \end{cases}\)

The function nvpl_sparse_spsv_buffer_size() returns the size of the workspace needed by nvpl_sparse_spsv_analysis() and nvpl_sparse_spsv_solve(). The function nvpl_sparse_spsv_analysis() performs the analysis phase, while nvpl_sparse_spsv_solve() executes the solve phase for a sparse triangular linear system. The opaque data structure spsv_descr is used to share information among all functions. The function nvpl_sparse_spsv_update_matrix() updates spsv_descr with new matrix values.

The routine supports arbitrary sparsity for the input matrix, but only the upper or lower triangular part is taken into account in the computation.

NOTE: all parameters must be consistent across nvpl_sparse_spsv API calls and the matrix descriptions and external_buffer must not be modified between nvpl_sparse_spsv_analysis() and nvpl_sparse_spsv_solve(). The function nvpl_sparse_spsv_update_matrix() can be used to update the values on the sparse matrix stored inside the opaque data structure spsv_descr

Param.	Memory	Meaning
`handle`	IN	Handle to the NVPL Sparse library context
`op_A`	IN	Operation `op(A)`
`alpha`	IN	\(\alpha\) scalar used for multiplication of type `compute_type`
`mat_A`	IN	Sparse matrix `A`
`vec_X`	IN	Dense vector `X`
`vec_Y`	IN/OUT	Dense vector `Y`
`compute_type`	IN	Datatype in which the computation is executed
`alg`	IN	Algorithm for the computation
`buffer_size`	OUT	Number of bytes of workspace needed by `nvpl_sparse_spsv_analysis()` and `nvpl_sparse_spsv_solve()`
`external_buffer`	IN/OUT	Pointer to a workspace buffer of at least `bufferSize` bytes. It is used by `nvpl_sparse_spsv_analysis` and `nvpl_sparse_spsv_solve()`
`spsv_descr`	IN/OUT	Opaque descriptor for storing internal data used across the three steps

The sparse matrix formats currently supported are listed below:

NVPL_SPARSE_FORMAT_CSR
NVPL_SPARSE_FORMAT_COO
NVPL_SPARSE_FORMAT_SLICED_ELL

The nvpl_sparse_spsv supports the following shapes and properties:

NVPL_SPARSE_FILL_MODE_LOWER and NVPL_SPARSE_FILL_MODE_UPPER fill modes
NVPL_SPARSE_DIAG_TYPE_NON_UNIT and NVPL_SPARSE_DIAG_TYPE_UNIT diagonal types

nvpl_sparse_spsv supports the following index type for representing the sparse matrix mat_A:

32-bit indices (NVPL_SPARSE_INDEX_32I)
64-bit indices (NVPL_SPARSE_INDEX_64I)

nvpl_sparse_spsv supports the following data types:

Uniform-precision computation:

`A`/`X`/ `Y`/`computeType`
`NVPL_SPARSE_R_32F`
`NVPL_SPARSE_R_64F`
`NVPL_SPARSE_C_32F`
`NVPL_SPARSE_C_64F`

nvpl_sparse_spsv supports the following algorithms:

Algorithm	Notes
`NVPL_SPARSE_SPSV_ALG_DEFAULT`	Default algorithm

nvpl_sparse_spsv has the following properties:

The routine requires extra storage for the analysis phase which is proportional to number of non-zero entries of the sparse matrix
Provides deterministic (bit-wise) results for each run for the solving phase nvpl_sparse_spsv_solve()
The routine supports in-place operation
nvpl_sparse_spsv_buffer_size() and nvpl_sparse_spsv_analysis() routines accept NULL for vec_X and vec_Y
The routine allows the indices of mat_A to be unsorted

nvpl_sparse_spsv_update_matrix() updates the sparse matrix after calling the analysis phase. This functions supports the following update strategies (update_part):

Strategy	Notes
`NVPL_SPARSE_SPSV_UPDATE_GENERAL`	Updates the sparse matrix values with values of `new_values` array
`NVPL_SPARSE_SPSV_UPDATE_DIAGONAL`	Updates the diagonal part of the matrix with diagonal values stored in `new_values` array. That is, `new_values` has the new diagonal values only

See nvpl_sparse_status_t for the description of the return status.