Is this page helpful?

Getting Started#

In this section, we show the simplest workflow for using cuDSS to solve a linear system with a sparse system matrix. We first describe the main steps to set up the computation. Then, we describe how to install the library and how to compile an example which uses cuDSS. Lastly, we present a step by step code example with additional comments.

Note: the code snippet does not use many of the available features of cuDSS, please refer to the rest of the documentation for more details.

cuDSS Workflow#

cuDSS is following a commonly used multi-stage approach in sparse direct solvers. The process of solving a linear system is split into several phases: reordering and symbolic factorization, numerical factorization (and, optionally, refactorization) and solving (with optional iterative refinement).
However, before calling the main cuDSS API cudssExecute(), a setup is necessary.

One of the simplest yet complete workflow consists of the following steps:

0. Prerequisites: User-allocated device memory buffers for the sparse matrix of the linear system, values of dense right-hand side matrix and solution.
1. Initialize the library handle: cudssCreate().
2. Create the matrix wrappers for the sparse matrix of the system, solution and right-hand side matrices: cudssMatrixCreateDn(), cudssMatrixCreateCsr().
3. Create the opaque cuDSS objects for the solver settings (cudssConfig_t) and data (cudssData_t): cudssConfigCreate(), cudssDataCreate().
4. Apply any extra settings (like setting CUDA stream to execute with, solver settings and data parameters): cudssSetStream(), cudssConfigSet(), cudssDataSet().
5. Execute the reordering/symbolic factorization step: cudssExecute() with CUDSS_PHASE_ANALYSIS.
6. Execute the factorization step: cudssExecute() with CUDSS_PHASE_FACTORIZATION.
7. Execute the solving step: cudssExecute() with CUDSS_PHASE_SOLVE.
8. Destroy the opaque objects (cuDSS matrices, configs and data): cudssMatrixDestroy(), cudssConfigDestroy(), cudssDataDestroy().
9. Destroy the library handle: cudssDestroy().

For further details, see cuDSS Types and cuDSS Functions.

Installation and Compilation#

Download the cuDSS package from developer.nvidia.com/cudss-downloads

Prerequisites#

Linux#

For an archive installation, set CUDSS_DIR to the extracted cuDSS prefix containing include/ and lib/. Set CTK_DIR to the matching CUDA Toolkit installation.

For a pip installation, use the cuDSS wheel matching your CUDA major version: nvidia-cudss-cu12 or nvidia-cudss-cu13. Pip installs the matching cuBLAS and NVRTC dependencies automatically. For example, for CUDA 12:

python3 -m pip install nvidia-cudss-cu12
export CUDSS_DIR="$(python3 -c 'from importlib.metadata import distribution; print(distribution("nvidia-cudss-cu12").locate_file("nvidia/cu12"))')"

For CUDA 13, replace cu12 with cu13 in both commands. A CUDA Toolkit installation providing nvcc is still required to compile the example.

For either installation method, update the runtime library path:

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

To compile the sample code we will discuss below (cudss_simple.cpp),

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

For pip installations, replace -lcudss above with -l:libcudss.so.1: the wheel does not contain an unversioned library symlink. The static-link example below requires the cuDSS archive, since the wheel contains only the shared library.

The previous command links cuDSS as a shared library. Linking the code with the static version of the library requires additional flags:

nvcc cudss_simple.cpp -I${CUDSS_DIR}/include                           \
                      -Xlinker=${CUDSS_DIR}/lib/libcudss_static.a      \
                      -Xlinker=${CTK_DIR}/lib64/libcublas_static.a     \
                      -Xlinker=${CTK_DIR}/lib64/libcublasLt_static.a   \
                      -Xlinker=${CTK_DIR}/lib64/libculibos.a           \
                      -L${CTK_DIR}/lib64 -lnvrtc                       \
                      -o cudss_simple_static

Windows#

Assuming cuDSS has been extracted to CUDSS_DIR and CUDA Toolkit (CTK) is in CTK_DIR, we update the library path accordingly:

set "PATH=%CUDSS_DIR%\bin;%CTK_DIR%\bin;%CTK_DIR%\bin\x64;%PATH%"

Note: the cuDSS DLL is in %CUDSS_DIR%\bin; %CUDSS_DIR%\lib holds the import library cudss.lib used at link time, not the DLL. CUDA Toolkit 12 installs its DLLs in %CTK_DIR%\bin, CUDA Toolkit 13 in %CTK_DIR%\bin\x64.

To compile the sample code we will discuss below (cudss_simple.cpp),

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

Note that on Windows cuDSS is shipped only as a DLL with its import library cudss.lib; there is no static version of the library.

Selecting the CUDA Toolkit version with system package installs#

cuDSS is available in builds for CUDA Toolkit 12 and CUDA Toolkit 13. Select the build matching your application’s CUDA major version. System packages can use CUDA-major-specific library and CMake configuration directories, while conda selects the matching build for the environment.

The two builds are not interchangeable: an application built against CUDA Toolkit 12 must use the CTK 12 build of cuDSS (which links libcublas.so.12), and an application built against CUDA Toolkit 13 must use the CTK 13 build (which links libcublas.so.13). Mixing them leads to link- or run-time errors such as:

undefined reference to cublasDestroy_v2@libcublas.so.13

To select the build that matches your CUDA Toolkit:

  • Debian/Ubuntu: install/select the package for the CUDA major version you need. When both variants are installed, use update-alternatives to choose the system default or point CMake at the desired variant explicitly.

  • conda: pin the cuda-version metapackage to the CUDA major version you are building against (for example cuda-version=12) so that the matching cuDSS build is selected.

  • CMake: when both variants are installed, which cudss-config.cmake is found first by find_package(cudss) is not guaranteed. Point CMake at the matching build explicitly with -Dcudss_DIR=<prefix>/lib/cmake/cudss (using the path under the CUDA major version you are building against).

As an additional safeguard, the cuDSS CMake package configuration checks whether the selected cuDSS build matches the CUDA Toolkit used by the consuming project, and reports an error at configuration time on a mismatch. This check can be relaxed to a warning by configuring with -DCUDSS_ALLOW_CTK_MISMATCH=ON.

Code Example#

The following code example shows the common steps to use cuDSS and solve a sparse linear system.
The full code can be found in cuDSS Example 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
cudssReorderingAlg_t reorder_alg = CUDSS_REORDERING_ALG_DEFAULT;
cudssConfigSet(config, CUDSS_CONFIG_REORDERING_ALG, &reorder_alg, sizeof(cudssReorderingAlg_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

// ...