稀疏矩阵 API#
本节介绍用于稀疏矩阵描述符的 NVPL Sparse 辅助函数。
有关存储格式的详细描述，请参阅 COO、CSR 、CSC 和 SELL 章节。
坐标 (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)
此函数以 COO 格式（结构数组布局）初始化稀疏矩阵描述符 sp_mat_descr。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输出 |
稀疏矩阵描述符 |
|
输入 |
稀疏矩阵的行数 |
|
输入 |
稀疏矩阵的列数 |
|
输入 |
稀疏矩阵的非零条目数 |
|
输入 |
稀疏矩阵的行索引。包含 |
|
输入 |
稀疏矩阵的列索引。包含 |
|
输入 |
稀疏矩阵的值。包含 |
|
输入 |
|
|
输入 |
|
|
输入 |
|
nvpl_sparse_create_coo() 具有以下约束
coo_row_ind、coo_col_ind和coo_values必须与coo_idx_type、coo_idx_type和value_type指定的数据类型的大小对齐。有关数据类型的描述，请参阅 nvpl_sparse_data_type_t。
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
nvpl_sparse_coo_get()#
nvpl_sparse_status_t
nvpl_sparse_coo_get(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* idx_type,
nvpl_sparse_index_base_t* idx_base,
nvpl_sparse_data_type_t* value_type)
nvpl_sparse_status_t
nvpl_sparse_const_coo_get(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)
此函数返回以 COO 格式（结构数组布局）存储的稀疏矩阵描述符 sp_mat_descr 的字段。
参数。 |
输入/输出 |
含义 |
|
|---|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
|
输出 |
稀疏矩阵的行数 |
|
|
输出 |
稀疏矩阵的列数 |
|
|
输出 |
稀疏矩阵的非零条目数 |
|
|
输出 |
稀疏矩阵的行索引。包含 |
|
|
输出 |
稀疏矩阵的列索引。包含 |
|
|
输出 |
稀疏矩阵的值。包含 |
|
|
输出 |
|
|
|
输出 |
|
|
|
输出 |
|
|
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
nvpl_sparse_coo_set_pointers()#
nvpl_sparse_status_t
nvpl_sparse_coo_set_pointers(nvpl_sparse_sp_mat_descr_t sp_mat_descr,
void* coo_rows,
void* coo_columns,
void* coo_values)
此函数设置稀疏矩阵描述符 sp_mat_descr 的指针。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
输入 |
稀疏矩阵的行索引。包含 |
|
输入 |
稀疏矩阵的列索引。包含 |
|
输入 |
稀疏矩阵的值。包含 |
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
压缩稀疏行 (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)
此函数以 CSR 格式初始化稀疏矩阵描述符 sp_mat_descr。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输出 |
稀疏矩阵描述符 |
|
输入 |
稀疏矩阵的行数 |
|
输入 |
稀疏矩阵的列数 |
|
输入 |
稀疏矩阵的非零条目数 |
|
输入 |
稀疏矩阵的行偏移量。包含 |
|
输入 |
稀疏矩阵的列索引。包含 |
|
输入 |
稀疏矩阵的值。包含 |
|
输入 |
|
|
输入 |
|
|
输入 |
|
|
输入 |
|
nvpl_sparse_create_csr() 具有以下约束
csr_row_offsets、csr_col_ind和csr_values必须与csr_row_offsets_type、csr_col_ind_type和value_type指定的数据类型的大小对齐。有关数据类型的描述，请参阅 nvpl_sparse_data_type_t。
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
nvpl_sparse_csr_get()#
nvpl_sparse_status_t
nvpl_sparse_csr_get(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_const_csr_get(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)
此函数返回以 CSR 格式存储的稀疏矩阵描述符 sp_mat_descr 的字段。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
输出 |
稀疏矩阵的行数 |
|
输出 |
稀疏矩阵的列数 |
|
输出 |
稀疏矩阵的非零条目数 |
|
输出 |
稀疏矩阵的行偏移量。包含 |
|
输出 |
稀疏矩阵的列索引。包含 |
|
输出 |
稀疏矩阵的值。包含 |
|
输出 |
|
|
输出 |
|
|
输出 |
|
|
输出 |
|
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
nvpl_sparse_csr_set_pointers()#
nvpl_sparse_status_t
nvpl_sparse_csr_set_pointers(nvpl_sparse_sp_mat_descr_t sp_mat_descr,
void* csr_row_offsets,
void* csr_col_ind,
void* csr_values)
此函数设置稀疏矩阵描述符 sp_mat_descr 的指针。
参数。 |
输入/输出 |
含义 |
|
|---|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
|
输入 |
稀疏矩阵的行偏移量。包含 |
|
|
输入 |
稀疏矩阵的列索引。包含 |
|
|
输入 |
稀疏矩阵的值。包含 |
|
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
压缩稀疏列 (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)
此函数以 CSC 格式初始化稀疏矩阵描述符 sp_mat_descr。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输出 |
稀疏矩阵描述符 |
|
输入 |
稀疏矩阵的行数 |
|
输入 |
稀疏矩阵的列数 |
|
输入 |
稀疏矩阵的非零条目数 |
|
输入 |
稀疏矩阵的列偏移量。包含 |
|
输入 |
稀疏矩阵的行索引。包含 |
|
输入 |
稀疏矩阵的值。包含 |
|
输入 |
|
|
输入 |
|
|
输入 |
|
|
输入 |
|
nvpl_sparse_create_csc() 具有以下约束
csc_col_offsets、csc_row_ind和csc_values必须与csc_col_offsets_type、csc_row_ind_type和value_type指定的数据类型的大小对齐。有关数据类型的描述，请参阅 nvpl_sparse_data_type_t。
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
nvpl_sparse_csc_get()#
nvpl_sparse_status_t
nvpl_sparse_csc_get(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_const_csc_get(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)
此函数返回以 CSC 格式存储的稀疏矩阵描述符 sp_mat_descr 的字段。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
输出 |
稀疏矩阵的行数 |
|
输出 |
稀疏矩阵的列数 |
|
输出 |
稀疏矩阵的非零条目数 |
|
输出 |
稀疏矩阵的列偏移量。包含 |
|
输出 |
稀疏矩阵的行索引。包含 |
|
输出 |
稀疏矩阵的值。包含 |
|
输出 |
|
|
输出 |
|
|
输出 |
|
|
输出 |
|
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
nvpl_sparse_csc_set_pointers()#
nvpl_sparse_status_t
nvpl_sparse_csc_set_pointers(nvpl_sparse_sp_mat_descr_t sp_mat_descr,
void* csc_col_offsets,
void* csc_row_ind,
void* csc_values)
此函数设置稀疏矩阵描述符 sp_mat_descr 的指针。
参数。 |
输入/输出 |
含义 |
|
|---|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
|
输入 |
稀疏矩阵的列偏移量。包含 |
|
|
输入 |
稀疏矩阵的行索引。包含 |
|
|
输入 |
稀疏矩阵的值。包含 |
|
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
分片 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)
此函数为分片 Ellpack (SELL) 格式初始化稀疏矩阵描述符 sp_mat_descr。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输出 |
稀疏矩阵描述符 |
|
输入 |
稀疏矩阵的行数 |
|
输入 |
稀疏矩阵的列数 |
|
输入 |
稀疏矩阵中非零元素的数量 |
|
输入 |
|
|
输入 |
每个切片的行数 |
|
输入 |
稀疏矩阵的切片偏移量。大小为 \(\left \lceil{\frac{rows}{slice_size}}\right \rceil + 1\) 的数组 |
|
输入 |
稀疏矩阵的列索引。大小为 |
|
输入 |
稀疏矩阵的值。大小为 |
|
输入 |
|
|
输入 |
|
|
输入 |
|
|
输入 |
|
注意
分片 Ellpack 列数组 sell_col_ind 包含 -1 值，用于指示填充条目。
nvpl_sparse_create_sliced_ell() 具有以下约束
sell_slice_offsets、sell_col_ind和sell_values必须与sell_slice_offsets_type、sell_col_ind_type和value_type指定的数据类型的大小对齐。有关数据类型的描述，请参阅 nvpl_sparse_data_type_t。
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
所有稀疏格式#
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
此函数释放为稀疏矩阵描述符 sp_mat_descr 分配的内存。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输入 |
稀疏矩阵描述符 |
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
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)
此函数返回稀疏矩阵 sp_mat_descr 的大小。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
输出 |
稀疏矩阵的行数 |
|
输出 |
稀疏矩阵的列数 |
|
输出 |
稀疏矩阵的非零条目数 |
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
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)
此函数返回稀疏矩阵描述符 sp_mat_descr 的 format 字段。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
输出 |
稀疏矩阵的存储格式 |
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
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)
此函数返回稀疏矩阵描述符 sp_mat_descr 的 idx_base 字段。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
输出 |
稀疏矩阵的索引基数 |
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
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)
nvpl_sparse_status_t
nvpl_sparse_const_sp_mat_get_values(nvpl_sparse_const_sp_mat_descr_t sp_mat_descr,
const void** values)
此函数返回稀疏矩阵描述符 sp_mat_descr 的 values 字段。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
输出 |
稀疏矩阵的值。包含 |
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
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)
此函数设置稀疏矩阵描述符 sp_mat_descr 的 values 字段。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
输入 |
稀疏矩阵的值。包含 |
nvpl_sparse_sp_mat_set_values() 具有以下约束
values必须与其在sp_mat_descr中指定的对应数据类型的大小对齐。有关数据类型的描述，请参阅 nvpl_sparse_data_type_t。
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
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)
此函数获取稀疏矩阵描述符 sp_mat_descr 的属性。
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输入 |
稀疏矩阵描述符 |
|
输入 |
属性枚举器 |
|
输出 |
属性值 |
|
输入 |
属性大小（字节），用于安全 |
属性 |
含义 |
可能的值 |
|---|---|---|
|
指示矩阵的下三角部分或上三角部分是否存储在稀疏存储中 |
|
|
指示矩阵对角线项是否为单位值 |
|
有关返回状态的描述，请参阅 nvpl_sparse_status_t。
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)
此函数设置稀疏矩阵描述符 sp_mat_descr 的属性
参数。 |
输入/输出 |
含义 |
|---|---|---|
|
输出 |
稀疏矩阵描述符 |
|
输入 |
属性枚举器 |
|
输入 |
属性值 |
|
输入 |
属性大小（字节），用于安全 |
属性 |
含义 |
可能的值 |
|---|---|---|
|
指示矩阵的下三角部分或上三角部分是否存储在稀疏存储中 |
|
|
指示矩阵对角线项是否为单位值 |
|
有关返回状态的描述，请参阅 nvpl_sparse_status_t。