Sparse Matrix APIs¶

The NVPL Sparse helper functions for sparse matrix descriptor are described in this section.

See the COO, CSR , CSC , SELL sections for the detailed description of the storage formats.

Coordinate (COO)¶

nvpl_sparse_create_coo()¶

nvpl_sparse_status_t
nvpl_sparse_create_coo(nvpl_sparse_sp_mat_descr_t* sp_mat_descr,
                  int64_t                          rows,
                  int64_t                          cols,
                  int64_t                          nnz,
                  void*                            coo_row_ind,
                  void*                            coo_col_ind,
                  void*                            coo_values,
                  nvpl_sparse_index_type_t         coo_idx_type,
                  nvpl_sparse_index_base_t         idx_base,
                  nvpl_sparse_data_type_t          value_type)

nvpl_sparse_status_t
nvpl_sparse_create_const_coo(nvpl_sparse_const_sp_mat_descr_t* sp_mat_descr,
                       int64_t                                 rows,
                       int64_t                                 cols,
                       int64_t                                 nnz,
                       const void*                             coo_row_ind,
                       const void*                             coo_col_ind,
                       const void*                             coo_values,
                       nvpl_sparse_index_type_t                idx_type,
                       nvpl_sparse_index_base_t                idx_base,
                       nvpl_sparse_data_type_t                 value_type)

This function initializes the sparse matrix descriptor sp_mat_descr in the COO format (Structure of Arrays layout).

Param.	In/out	Meaning
`sp_mat_descr`	OUT	Sparse matrix descriptor
`rows`	IN	Number of rows of the sparse matrix
`cols`	IN	Number of columns of the sparse matrix
`nnz`	IN	Number of non-zero entries of the sparse matrix
`coo_row_ind`	IN	Row indices of the sparse matrix. Array with `nnz` elements
`coo_col_ind`	IN	Column indices of the sparse matrix. Array with `nnz` elements
`coo_values`	IN	Values of the sparse matrix. Array with `nnz` elements
`idx_type`	IN	Data type of `coo_row_ind` and `coo_col_ind`
`idx_base`	IN	Index base of `coo_row_ind` and `coo_col_ind`
`value_type`	IN	Datatype of `coo_values`

nvpl_sparse_create_coo() has the following constraints:

coo_row_ind, coo_col_ind, and coo_values must be aligned to the size of the datatypes specified by coo_idx_type, coo_idx_type, and value_type. respectively. See nvpl_sparse_data_type_t for the description of the datatypes.

See nvpl_sparse_status_t for the description of the return status.

Compressed Sparse Row (CSR)¶

nvpl_sparse_create_csr()¶

nvpl_sparse_status_t
nvpl_sparse_create_csr(nvpl_sparse_sp_mat_descr_t* sp_mat_descr,
                  int64_t                          rows,
                  int64_t                          cols,
                  int64_t                          nnz,
                  void*                            csr_row_offsets,
                  void*                            csr_col_ind,
                  void*                            csr_values,
                  nvpl_sparse_index_type_t         csr_row_offsets_type,
                  nvpl_sparse_index_type_t         csr_col_ind_type,
                  nvpl_sparse_index_base_t         idx_base,
                  nvpl_sparse_data_type_t          value_type)

nvpl_sparse_status_t
nvpl_sparse_create_const_csr(nvpl_sparse_const_sp_mat_descr_t* sp_mat_descr,
                       int64_t                                 rows,
                       int64_t                                 cols,
                       int64_t                                 nnz,
                       const void*                             csr_row_offsets,
                       const void*                             csr_col_ind,
                       const void*                             csr_values,
                       nvpl_sparse_index_type_t                csr_row_offsets_type,
                       nvpl_sparse_index_type_t                csr_col_ind_type,
                       nvpl_sparse_index_base_t                idx_base,
                       nvpl_sparse_data_type_t                 value_type)

This function initializes the sparse matrix descriptor sp_mat_descr in the CSR format.

Param.	In/out	Meaning
`sp_mat_descr`	OUT	Sparse matrix descriptor
`rows`	IN	Number of rows of the sparse matrix
`cols`	IN	Number of columns of the sparse matrix
`nnz`	IN	Number of non-zero entries of the sparse matrix
`csr_row_offsets`	IN	Row offsets of the sparse matrix. Array with `rows + 1` elements
`csr_col_ind`	IN	Column indices of the sparse matrix. Array with `nnz` elements
`csr_values`	IN	Values of the sparse matrix. Array with `nnz` elements
`csr_row_offsets_type`	IN	Data type of `csr_row_offsets`
`csr_col_ind_type`	IN	Data type of `csr_col_ind`
`idx_base`	IN	Index base of `csr_row_offsets` and `csr_col_ind`
`value_type`	IN	Datatype of `csr_values`

nvpl_sparse_create_csr() has the following constraints:

csr_row_offsets, csr_col_ind, and csr_values must be aligned to the size of the datatypes specified by csr_row_offsets_type, csr_col_ind_type, and value_type, respectively. See nvpl_sparse_data_type_t for the description of the datatypes.

See nvpl_sparse_status_t for the description of the return status.

Compressed Sparse Column (CSC)¶

nvpl_sparse_create_csc()¶

nvpl_sparse_status_t
nvpl_sparse_create_csc(nvpl_sparse_sp_mat_descr_t* sp_mat_descr,
                  int64_t                          rows,
                  int64_t                          cols,
                  int64_t                          nnz,
                  void*                            csc_col_offsets,
                  void*                            csc_row_ind,
                  void*                            csc_values,
                  nvpl_sparse_index_type_t         csc_col_offsets_type,
                  nvpl_sparse_index_type_t         csc_row_ind_type,
                  nvpl_sparse_index_base_t         idx_base,
                  nvpl_sparse_data_type_t          value_type)

nvpl_sparse_status_t
nvpl_sparse_create_const_csc(nvpl_sparse_const_sp_mat_descr_t* sp_mat_descr,
                       int64_t                                 rows,
                       int64_t                                 cols,
                       int64_t                                 nnz,
                       const void*                             csc_col_offsets,
                       const void*                             csc_row_ind,
                       const void*                             csc_values,
                       nvpl_sparse_index_type_t                csc_col_offsets_type,
                       nvpl_sparse_index_type_t                csc_row_ind_type,
                       nvpl_sparse_index_base_t                idx_base,
                       nvpl_sparse_data_type_t                 value_type)

This function initializes the sparse matrix descriptor sp_mat_descr in the CSC format.

Param.	In/out	Meaning
`sp_mat_descr`	OUT	Sparse matrix descriptor
`rows`	IN	Number of rows of the sparse matrix
`cols`	IN	Number of columns of the sparse matrix
`nnz`	IN	Number of non-zero entries of the sparse matrix
`csc_col_offsets`	IN	Column offsets of the sparse matrix. Array with `cols + 1` elements
`csc_row_ind`	IN	Row indices of the sparse matrix. Array with `nnz` elements
`csc_values`	IN	Values of the sparse matrix. Array with `nnz` elements
`csc_col_offsets_type`	IN	Data type of `csc_col_offsets`
`csc_row_ind_type`	IN	Data type of `csc_row_ind`
`idx_base`	IN	Index base of `csc_col_offsets` and `csc_row_ind`
`value_type`	IN	Datatype of `csc_values`

nvpl_sparse_create_csc() has the following constraints:

csc_col_offsets, csc_row_ind, and csc_values must be aligned to the size of the datatypes specified by csc_col_offsets_type, csc_row_ind_type, and value_type, respectively. See nvpl_sparse_data_type_t for the description of the datatypes.

See nvpl_sparse_status_t for the description of the return status.

Sliced-Ellpack (SELL)¶

nvpl_sparse_create_sliced_ell()¶

nvpl_sparse_status_t
nvpl_sparse_create_sliced_ell(nvpl_sparse_sp_mat_descr_t*   sp_mat_descr,
                        int64_t                             rows,
                        int64_t                             cols,
                        int64_t                             nnz,
                        int64_t                             sell_values_size,
                        int64_t                             slice_size,
                        void*                               sell_slice_offsets,
                        void*                               sell_col_ind,
                        void*                               sell_values,
                        nvpl_sparse_index_type_t            sell_slice_offsets_type,
                        nvpl_sparse_index_type_t            sell_col_ind_type,
                        nvpl_sparse_index_base_t            idx_base,
                        nvpl_sparse_data_type_t             value_type)

nvpl_sparse_status_t
nvpl_sparse_create_const_sliced_ell(nvpl_sparse_const_sp_mat_descr_t*   sp_mat_descr,
                             int64_t                                    rows,
                             int64_t                                    cols,
                             int64_t                                    nnz,
                             int64_t                                    sell_values_size,
                             int64_t                                    slice_size,
                             const void*                                sell_slice_offsets,
                             const void*                                sell_col_ind,
                             const void*                                sell_values,
                             nvpl_sparse_index_type_t                   sell_slice_offsets_type,
                             nvpl_sparse_index_type_t                   sell_col_ind_type,
                             nvpl_sparse_index_base_t                   idx_base,
                             nvpl_sparse_data_type_t                    value_type)

This function initializes the sparse matrix descriptor sp_mat_descr for the Sliced Ellpack (SELL) format.

Param.	In/out	Meaning
`sp_mat_descr`	OUT	Sparse matrix descriptor
`rows`	IN	Number of rows of the sparse matrix
`cols`	IN	Number of columns of the sparse matrix
`nnz`	IN	Number of nonzero elements in the sparse matrix
`sell_values_size`	IN	Total number of elements in `sell_values` array (nonzero and padding)
`slice_size`	IN	The number of rows per slice
`sell_slice_offsets`	IN	Slice offsets of the sparse matrix. Array of size \(\left \lceil{\frac{rows}{slice_size}}\right \rceil + 1\)
`sell_col_ind`	IN	Column indexes of the sparse matrix. Array of size `sell_values_size`
`sell_values`	IN	Values of the sparse matrix. Array of size `sell_values_size` elements
`sell_slice_offsets_type`	IN	Data type of `sell_slice_offsets`
`sell_col_ind_type`	IN	Data type of `sell_col_ind`
`idx_base`	IN	Index base of `sell_col_ind`
`value_type`	IN	Data type of `sell_values`

Note

Sliced Ellpack Column array sell_col_ind contains -1 values for indicating padded entries.

nvpl_sparse_create_sliced_ell() has the following constraints:

sell_slice_offsets, sell_col_ind, and sell_values must be aligned to the size of the datatypes specified by sell_slice_offsets_type, sell_col_ind_type, and value_type, respectively. See nvpl_sparse_data_type_t for the description of the datatypes.

See nvpl_sparse_status_t for the description of the return status.

All Sparse Formats¶

nvpl_sparse_destroy_sp_mat()¶

nvpl_sparse_status_t
nvpl_sparse_destroy_sp_mat(nvpl_sparse_const_sp_mat_descr_t sp_mat_descr) // non-const descriptor supported

This function releases the memory allocated for the sparse matrix descriptor sp_mat_descr.

Param.	In/out	Meaning
`sp_mat_descr`	IN	Sparse matrix descriptor

See nvpl_sparse_status_t for the description of the return status.

nvpl_sparse_sp_mat_get_size()¶

nvpl_sparse_status_t
nvpl_sparse_sp_mat_get_size(nvpl_sparse_const_sp_mat_descr_t  sp_mat_descr,  // non-const descriptor supported
                            int64_t*                          rows,
                            int64_t*                          cols,
                            int64_t*                          nnz)

This function returns the sizes of the sparse matrix sp_mat_descr.

Param.	In/out	Meaning
`sp_mat_descr`	IN	Sparse matrix descriptor
`rows`	OUT	Number of rows of the sparse matrix
`cols`	OUT	Number of columns of the sparse matrix
`nnz`	OUT	Number of non-zero entries of the sparse matrix

See nvpl_sparse_status_t for the description of the return status.

nvpl_sparse_sp_mat_get_format()¶

nvpl_sparse_status_t
nvpl_sparse_sp_mat_get_format(nvpl_sparse_const_sp_mat_descr_t sp_mat_descr, // non-const descriptor supported
                              nvpl_sparse_format_t*            format)

This function returns the format field of the sparse matrix descriptor sp_mat_descr.

Param.	In/out	Meaning
`sp_mat_descr`	IN	Sparse matrix descriptor
`format`	OUT	Storage format of the sparse matrix

See nvpl_sparse_status_t for the description of the return status.

nvpl_sparse_sp_mat_get_index_base()¶

nvpl_sparse_status_t
nvpl_sparse_sp_mat_get_index_base(nvpl_sparse_const_sp_mat_descr_t sp_mat_descr, // non-const descriptor supported
                                  nvpl_sparse_index_base_t*        idx_base)

This function returns the idx_base field of the sparse matrix descriptor sp_mat_descr.

Param.	In/out	Meaning
`sp_mat_descr`	IN	Sparse matrix descriptor
`idx_base`	OUT	Index base of the sparse matrix

See nvpl_sparse_status_t for the description of the return status.

nvpl_sparse_sp_mat_get_values()¶

nvpl_sparse_status_t
nvpl_sparse_sp_mat_get_values(nvpl_sparse_sp_mat_descr_t sp_mat_descr,
                              void**                     values)

This function returns the values field of the sparse matrix descriptor sp_mat_descr.

Param.	In/out	Meaning
`sp_mat_descr`	IN	Sparse matrix descriptor
`values`	OUT	Values of the sparse matrix. Array with `nnz` elements

See nvpl_sparse_status_t for the description of the return status.

nvpl_sparse_sp_mat_set_values()¶

nvpl_sparse_status_t
nvpl_sparse_sp_mat_set_values(nvpl_sparse_sp_mat_descr_t sp_mat_descr,
                              void*                      values)

This function sets the values field of the sparse matrix descriptor sp_mat_descr.

Param.	In/out	Meaning
`sp_mat_descr`	IN	Sparse matrix descriptor
`values`	IN	Values of the sparse matrix. Array with `nnz` elements

nvpl_sparse_sp_mat_set_values() has the following constraints:

values must be aligned to the size of its corresponding datatype specified in sp_mat_descr. See nvpl_sparse_data_type_t for the description of the datatypes.

See nvpl_sparse_status_t for the description of the return status.

nvpl_sparse_sp_mat_get_attribute()¶

nvpl_sparse_status_t
nvpl_sparse_sp_mat_get_attribute(nvpl_sparse_const_sp_mat_descr_t sp_mat_descr, // non-const descriptor supported
                                 nvpl_sparse_sp_mat_attribute_t   attribute,
                                 void*                            data,
                                 size_t                           dataSize)

The function gets the attributes of the sparse matrix descriptor sp_mat_descr.

Param.	In/out	Meaning
`sp_mat_descr`	IN	Sparse matrix descriptor
`attribute`	IN	Attribute enumerator
`data`	OUT	Attribute value
`dataSize`	IN	Size of the attribute in bytes for safety

Attribute	Meaning	Possible Values
`NVPL_SPARSE_SPMAT_FILL_MODE`	Indicates if the lower or upper part of a matrix is stored in sparse storage	`NVPL_SPARSE_FILL_MODE_LOWER` `NVPL_SPARSE_FILL_MODE_UPPER`
`NVPL_SPARSE_SPMAT_DIAG_TYPE`	Indicates if the matrix diagonal entries are unity	`NVPL_SPARSE_DIAG_TYPE_NON_UNIT` `NVPL_SPARSE_DIAG_TYPE_UNIT`

See nvpl_sparse_status_t for the description of the return status.

nvpl_sparse_sp_mat_set_attribute()¶

nvpl_sparse_status_t
nvpl_sparse_sp_mat_set_attribute(nvpl_sparse_sp_mat_descr_t     sp_mat_descr,
                                 nvpl_sparse_sp_mat_attribute_t attribute,
                                 const void*                    data,
                                 size_t                         dataSize)

The function sets the attributes of the sparse matrix descriptor sp_mat_descr

Param.	In/out	Meaning
`sp_mat_descr`	OUT	Sparse matrix descriptor
`attribute`	IN	Attribute enumerator
`data`	IN	Attribute value
`dataSize`	IN	Size of the attribute in bytes for safety

Attribute	Meaning	Possible Values
`NVPL_SPARSE_SPMAT_FILL_MODE`	Indicates if the lower or upper part of a matrix is stored in sparse storage	`NVPL_SPARSE_FILL_MODE_LOWER` `NVPL_SPARSE_FILL_MODE_UPPER`
`NVPL_SPARSE_SPMAT_DIAG_TYPE`	Indicates if the matrix diagonal entries are unity	`NVPL_SPARSE_DIAG_TYPE_NON_UNIT` `NVPL_SPARSE_DIAG_TYPE_UNIT`

See nvpl_sparse_status_t for the description of the return status.