入门指南#

在本节中，我们将展示如何使用 cuDSS 求解具有稀疏系统矩阵的线性系统。我们首先概述工作流程，展示设置计算的主要步骤。然后，我们描述如何安装库以及如何编译使用 cuDSS 的示例。最后，我们提供一个逐步代码示例（不包含带有附加注释的 MGMN 模式）。

cuDSS 工作流程#

cuDSS 在稀疏直接求解器中遵循常用的多阶段方法。求解线性系统的过程分为几个阶段：重排序和符号分解、数值分解（以及可选的重分解）和求解（带有可选的迭代细化）。
但是，在调用主要的 cuDSS API cudssExecute() 之前，需要进行设置。

一个最简单但完整的工作流程包含以下步骤

0. 前提条件：用户分配的设备内存缓冲区，用于线性系统的稀疏矩阵、稠密右手边矩阵和解的值。
1. 初始化库句柄：cudssCreate()。
2. 为系统、解和右手边矩阵的稀疏矩阵创建矩阵包装器：cudssCreateMatrixDn(), cudssCreateMatrixCsr()。
3. 为求解器设置 (cudssConfig_t) 和数据 (cudssData_t) 创建不透明的 cuDSS 对象：cudssConfigCreate(), cudssDataCreate()。
4. 应用任何额外的设置（例如设置要执行的 CUDA 流、求解器设置和数据参数）：cudssSetStream(), cudssConfigSet(), cudssDataSet。
5. 执行重排序/符号分解步骤：cudssExecute()，使用 CUDSS_PHASE_ANALYSIS。
6. 执行分解步骤：cudssExecute()，使用 CUDSS_PHASE_FACTORIZATION。
7. 执行求解步骤：cudssExecute()，使用 CUDSS_PHASE_SOLVE。
8. 销毁不透明对象（cuDSS 矩阵、配置和数据）：cudssMatrixDestroy(), cudssConfigDestroy(), cudssDataDestroy()。
9. 销毁库句柄：cudssDestroy()。

有关更多详细信息，请参阅 cuDSS 数据类型 和 cuDSS 函数。

安装与编译#

从 developer.nvidia.com/cudss-downloads 下载 cuDSS 软件包

前提条件#

Linux#

假设 cuDSS 已解压到 CUDSS_DIR，并且 CUDA Toolkit (CTK) 位于 CTK_DIR，我们相应地更新库路径

export LD_LIBRARY_PATH=${CUDSS_DIR}/lib:${CTK_DIR}/lib64:${LD_LIBRARY_PATH}

要编译我们将在下面讨论的示例代码 (cudss_simple.cpp)，

nvcc cudss_simple.cpp -I${CUDSS_DIR}/include -L${CUDSS_DIR}/lib -lcudss -o cudss_simple

注意：如果使用 pip wheels 安装 cudss，由于 wheels 不支持符号链接，则应将上面的 -lcudss 替换为 -l:libcudss.so.0。

之前的命令将 cuDSS 链接为共享库。将代码与库的静态版本链接需要额外的标志

nvcc cudss_simple.cpp -I${CUDSS_DIR}/include                               \
                      -Xlinker=${CUDSS_DIR}/lib/libcudss_static.a   \
                      -o cudss_simple_static

Windows#

假设 cuDSS 已解压到 CUDSS_DIR，并且 CUDA Toolkit (CTK) 位于 CTK_DIR，我们相应地更新库路径

setx PATH "%CUDSS_DIR%\lib:%CTK_DIR%\lib64:%PATH%"

要编译我们将在下面讨论的示例代码 (cudss_simple.cpp)，

nvcc.exe cudss_simple.cpp -I "%CUDSS_DIR%\include" -lcudss -o cudss_simple.exe

请注意，之前的命令将 cuDSS 链接为共享库。将代码与库的静态版本链接需要额外的标志

nvcc.exe cudss_simple.cpp -I %CUDSS_DIR%\include                                         \
                          -Xlinker=/WHOLEARCHIVE:"%CUDSS_DIR%\lib\cudss.lib" \
                          -Xlinker=/FORCE -o cudss_simple_static.exe

代码示例#

以下代码示例展示了使用 cuDSS 并求解稀疏线性系统的常用步骤。
完整代码可以在 cuDSS 示例 1 中找到。
#include <cudss.h> // cuDSS header

// Device pointers and scalar shape parameters, matrix properties
int*    rowOffsets = ...
int*    colIndices = ...
double* values     = ...
double* bvalues    = ...
double* xvalues    = ...

//---------------------------------------------------------------------------------
// cuDSS data structures and handle initialization
cudssHandle_t             handle;
cudssConfig_t             config;
cudssData_t               data;
cudssMatrix_t             A;
cudssMatrix_t             b;
cudssMatrix_t             x;

cudssCreate(&handle);

cudssConfigCreate(&config);
cudssDataCreate(handle, &data);
cudssMatrixCreateCsr(&A, ... rowOffsets, colIndices, values, ...);
cudssMatrixCreateDn(&b, ... bvalues, ...);
cudssMatrixCreateDn(&x, ... xvalues, ...);

//---------------------------------------------------------------------------------
// (optional) Modifying solver settings, e.g., reordering algorithm
cudssAlgType_t reorder_alg = CUDSS_ALG_DEFAULT;
cudssConfigSet(config, CUDSS_REORDERING_ALG, &reorder_alg, sizeof(cudssAlgType_t));

//---------------------------------------------------------------------------------
// Reordering & symbolic factorization
cudssExecute(handle, CUDSS_PHASE_ANALYSIS, config, data, A, x, b);

//---------------------------------------------------------------------------------
// Numerical factorization
cudssExecute(handle, CUDSS_PHASE_FACTORIZATION, config, data, A, x, b);

//---------------------------------------------------------------------------------
// Solving the system
cudssExecute(handle, CUDSS_PHASE_SOLVE, config, data, A, x, b);

//---------------------------------------------------------------------------------
// (optional) Extra data can be retrieved from the cudssData_t object
// For example, diagonal of the factorized matrix or the reordering permutation

//---------------------------------------------------------------------------------
// Destroy the opaque objects
cudssConfigDestroy(config);
cudssDataDestroy(handle, data);
cudssMatrixDestroy(A);
cudssMatrixDestroy(x);
cudssMatrixDestroy(b);
cudssDestroy(handle);

//---------------------------------------------------------------------------------
// The solution of the system can now be accessed via the user-allocated device pointer xvalues

// ...