通用 API 函数#

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)

此函数执行稀疏矩阵 mat_A 和稠密向量 vec_X 的乘法运算

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

其中

  • op(A) 是大小为 \(m \times k\) 的稀疏矩阵

  • X 是大小为 \(k\) 的稠密向量

  • Y 是大小为 \(m\) 的稠密向量

  • Z 是大小为 \(m\) 的稠密向量

  • \(\alpha\) 和 \(\beta\) 是标量

此外，对于矩阵 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}\)

函数 nvpl_sparse_spmv_buffer_size() 返回 nvpl_sparse_spmv_analysis() 所需的工作空间大小

参数。

输入/输出

含义

handle

输入

NVPL Sparse 库上下文的句柄

op_A

输入

操作 op(A)

alpha

输入

用于乘法的 \(\alpha\) 标量，类型为 compute_type

mat_A

输入

稀疏矩阵 A

vec_X

输入

稠密向量 X

beta

输入

用于乘法的 \(\beta\) 标量，类型为 compute_type

vec_Y

输入

稠密向量 Y

vec_Z

输出

稠密向量 Z

compute_type

输入

执行计算的数据类型

alg

输入

计算的算法

buffer_size

输出

nvpl_sparse_spmv_analysis 和 nvpl_sparse_spmv 所需的工作空间字节数

external_buffer

输入/输出

指向工作区缓冲区的指针，该缓冲区至少为 buffer_size 字节，供 nvpl_sparse_spmv_analysis 和 nvpl_sparse_spmv() 使用

spmv_descr

输入/输出

用于存储跨三个步骤使用的内部数据的不透明描述符

下面列出了当前支持的稀疏矩阵格式

  • NVPL_SPARSE_FORMAT_COO

  • NVPL_SPARSE_FORMAT_CSR

  • NVPL_SPARSE_FORMAT_CSC

  • NVPL_SPARSE_FORMAT_SLICED_ELL

nvpl_sparse_spmv 支持以下索引类型来表示稀疏矩阵 mat_A

  • 32 位索引 (NVPL_SPARSE_INDEX_32I)

  • 64 位索引 (NVPL_SPARSE_INDEX_64I)

nvpl_sparse_spmv() 支持以下数据类型

单精度计算

A/X/Y/Z/computeType

NVPL_SPARSE_R_32F

NVPL_SPARSE_R_64F

NVPL_SPARSE_C_32F

NVPL_SPARSE_C_64F

nvpl_sparse_spmv() 支持以下算法

算法

注释

NVPL_SPARSE_SPMV_ALG_DEFAULT

任何稀疏矩阵格式的默认算法。

NVPL_SPARSE_SPMV_COO_ALG1

COO 稀疏矩阵格式的默认算法。在使用相同输入参数的不同运行中，可能会产生略有不同的结果。

NVPL_SPARSE_SPMV_CSR_ALG1

CSR/CSC 稀疏矩阵格式的默认算法。在使用相同输入参数的不同运行中，可能会产生略有不同的结果。

NVPL_SPARSE_SPMV_SELL_ALG1

Sliced Ellpack 稀疏矩阵格式的默认算法。为每次运行提供确定性（按位）结果。

性能说明

  • NVPL_SPARSE_SPMV_CSR_ALG1 比 NVPL_SPARSE_SPMV_COO_ALG1 提供更高的性能。

nvpl_sparse_spmv() 具有以下属性

  • 该例程需要额外的存储空间用于 CSR/CSC 格式。

  • 该例程允许 matA 的索引是未排序的。

有关返回状态的描述，请参阅 nvpl_sparse_status_t。

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)

此函数求解线性方程组，其系数以稀疏三角矩阵表示

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

其中

  • op(A) 是大小为 \(m \times m\) 的稀疏方阵

  • X 是大小为 \(m\) 的稠密向量

  • Y 是大小为 \(m\) 的稠密向量

  • \(\alpha\) 是标量

此外，对于矩阵 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}\)

函数 nvpl_sparse_spsv_buffer_size() 返回 nvpl_sparse_spsv_analysis() 和 nvpl_sparse_spsv_solve() 所需的工作空间大小。函数 nvpl_sparse_spsv_analysis() 执行分析阶段，而 nvpl_sparse_spsv_solve() 执行稀疏三角线性系统的求解阶段。不透明数据结构 spsv_descr 用于在所有函数之间共享信息。函数 nvpl_sparse_spsv_update_matrix() 使用新的矩阵值更新 spsv_descr。

该例程支持输入矩阵的任意稀疏性，但在计算中仅考虑上三角或下三角部分。

注意： 所有参数在 nvpl_sparse_spsv API 调用中必须保持一致，并且矩阵描述和 external_buffer 在 nvpl_sparse_spsv_analysis() 和 nvpl_sparse_spsv_solve() 之间不得修改。函数 nvpl_sparse_spsv_update_matrix() 可用于更新存储在不透明数据结构 spsv_descr 内的稀疏矩阵上的值

参数。

内存

含义

handle

输入

NVPL Sparse 库上下文的句柄

op_A

输入

操作 op(A)

alpha

输入

用于乘法的 \(\alpha\) 标量，类型为 compute_type

mat_A

输入

稀疏矩阵 A

vec_X

输入

稠密向量 X

vec_Y

输入/输出

稠密向量 Y

compute_type

输入

执行计算的数据类型

alg

输入

计算的算法

buffer_size

输出

nvpl_sparse_spsv_analysis() 和 nvpl_sparse_spsv_solve() 所需的工作空间字节数

external_buffer

输入/输出

指向工作区缓冲区的指针，该缓冲区至少为 bufferSize 字节。它由 nvpl_sparse_spsv_analysis 和 nvpl_sparse_spsv_solve() 使用

spsv_descr

输入/输出

用于存储跨三个步骤使用的内部数据的不透明描述符

下面列出了当前支持的稀疏矩阵格式

  • NVPL_SPARSE_FORMAT_CSR

  • NVPL_SPARSE_FORMAT_COO

  • NVPL_SPARSE_FORMAT_SLICED_ELL

nvpl_sparse_spsv 支持以下形状和属性

  • NVPL_SPARSE_FILL_MODE_LOWER 和 NVPL_SPARSE_FILL_MODE_UPPER 填充模式

  • NVPL_SPARSE_DIAG_TYPE_NON_UNIT 和 NVPL_SPARSE_DIAG_TYPE_UNIT 对角线类型

nvpl_sparse_spsv 支持以下索引类型来表示稀疏矩阵 mat_A

  • 32 位索引 (NVPL_SPARSE_INDEX_32I)

  • 64 位索引 (NVPL_SPARSE_INDEX_64I)

nvpl_sparse_spsv 支持以下数据类型

单精度计算

A/X/ Y/computeType

NVPL_SPARSE_R_32F

NVPL_SPARSE_R_64F

NVPL_SPARSE_C_32F

NVPL_SPARSE_C_64F

nvpl_sparse_spsv 支持以下算法

算法

注释

NVPL_SPARSE_SPSV_ALG_DEFAULT

默认算法

nvpl_sparse_spsv 具有以下属性

  • 该例程的分析阶段需要额外的存储空间，该空间与稀疏矩阵的非零条目数成正比

  • 为求解阶段 nvpl_sparse_spsv_solve() 的每次运行提供确定性（按位）结果

  • 该例程支持就地操作

  • nvpl_sparse_spsv_buffer_size() 和 nvpl_sparse_spsv_analysis() 例程接受 NULL 作为 vec_X 和 vec_Y

  • 该例程允许 mat_A 的索引是未排序的

nvpl_sparse_spsv_update_matrix() 在调用分析阶段后更新稀疏矩阵。此函数支持以下更新策略 (update_part)

策略

注释

NVPL_SPARSE_SPSV_UPDATE_GENERAL

使用 new_values 数组的值更新稀疏矩阵值

NVPL_SPARSE_SPSV_UPDATE_DIAGONAL

使用存储在 new_values 数组中的对角线值更新矩阵的对角线部分。也就是说，new_values 仅包含新的对角线值

有关返回状态的描述，请参阅 nvpl_sparse_status_t。