Installation Guide#

cuSolverDx is distributed as a part of the MathDx package. To download the most recent release of the MathDx package including cuSolverDx, go to the https://developer.nvidia.com/cusolverdx-downloads website.

Note

MathDx package contains:

  • cuBLASDx for selected linear algebra functions like General Matrix Multiplication (GEMM),

  • cuFFTDx for FFT calculations,

  • cuSolverDx for selected dense matrix factorization and solve routines,

  • cuRANDDx for random number generation.

MathDx libraries are designed to work together in a single project.

Note that for a project where multiple device extensions libraries are used all the libraries must come from the same MathDx release. Examples of such fusion are included in the package.

cuSolverDx In Your Project#

To use cuSolverDx library, users need to include the directories with cusolverdx.hpp and its dependencies commonDx and CUTLASS, which are shipped with the MathDx package, as well as link with cuSolverDx LTO library (Link Time Optimization). cuSolverDx provides its library in two forms: static library libcusolverdx.a, and fatbin library libcusolverdx.fatbin.

libcusolverdx.fatbin library contains only device code and thus is host platform agnostic. For example, it can be safely used on AARCH64 platform, whereas libcusolverdx.a can only be used for x86_64 Linux builds.

Important

libcusolverdx.fatbin can only be used with NVCC 12.8 or newer. This limitation doesn’t apply to NVRTC and nvJitLink.

// When using libcusolverdx.a
nvcc -dlto -std=c++17 -arch sm_XY (...) -I<mathdx_include_dir> <your_source_file>.cu -o <your_binary> -lcusolverdx

// When using libcusolverdx.fatbin
nvcc -dlto -std=c++17 -arch sm_XY (...) -I<mathdx_include_dir> <your_source_file>.cu -o <your_binary> libcusolverdx.fatbin

The -dlto option at link time instructs the linker to retrieve the LTO IR from the library object and perform optimization on the resulting IR for code generation.

When using NVRTC and nvJitLink for runtime kernel compilation and linking it’s possible to use either fatbin file libcusolverdx.fatbin or libcusolverdx.a. Fatbin has to be used for platforms other than x86_64 Linux.

When you unpack MathDx YY.MM package tarball into <your_directory>, cusolverdx.hpp file will be available at the following location:

  • <your_directory>/nvidia/mathdx/yy.mm/include/

The library files libcusolverdx.a and libcusolverdx.fatbin will be present in:

  • <your_directory>/nvidia/mathdx/yy.mm/lib/

The commonDx headers will be available at the following location:

  • <your_directory>/nvidia/mathdx/yy.mm/include/

Detailed requirements are listed in the Requirements section.

cuSolverDx In Your CMake Project#

The MathDx package provides configuration files that simplify using cuSolverDx in other CMake projects. After finding mathdx using find_package, users have to link mathdx::cusolverdx to their target. This ensures device linking against libcusolverdx.a and propagates the include directory cusolverdx_INCLUDE_DIRS, commonDx and CUTLASS dependencies, and the C++17 requirement to their target.

When CMake detects NVCC CUDA compiler 12.8 or newer, MathDx also exposes mathdx::cusolverdx_fatbin target. It can be used instead of mathdx::cusolverdx. This target uses libcusolverdx.fatbin library, which - in contrast to libcusolverdx.a - contains only device code and thus is host platform agnostic. For example, it can be safely used on AARCH64 platform, whereas libcusolverdx.a can only be used for x86_64 Linux builds.

Important

mathdx::cusolverdx_fatbin is only available when CMake detects that NVCC CUDA compiler 12.8 is used. You can check NVCC version in CMake script using CMAKE_CUDA_COMPILER_VERSION variable.

To enable LTO in CMake for a target, set INTERPROCEDURAL_OPTIMIZATION to true, and to allow separate compilation of device code set CUDA_SEPARABLE_COMPILATION to true. It is required for both mathdx::cusolverdx and mathdx::cusolverdx_fatbin targets. This is done by the CMake set_target_properties command:

# find cuSolverDx
find_package(mathdx REQUIRED COMPONENTS cusolverdx CONFIG)
# enable LTO in your target
set_target_properties(YourProgram
      PROPERTIES
          CUDA_SEPARABLE_COMPILATION ON
          INTERPROCEDURAL_OPTIMIZATION ON)
# link against mathdx::cusolverdx
target_link_libraries(YourProgram mathdx::cusolverdx)
# or against mathdx::cusolverdx_fatbin
target_link_libraries(YourProgram mathdx::cusolverdx_fatbin)

You can pass the path to MathDx package using PATHS option:

find_package(mathdx REQUIRED COMPONENTS cusolverdx CONFIG PATHS "<your_directory>/nvidia/mathdx/yy.mm/")

Alternatively, you can set mathdx_ROOT during cmake configuration of your project:

cmake -Dmathdx_ROOT="<your_directory>/nvidia/mathdx/yy.mm/" (...)

Defined Targets#

mathdx::cusolverdx

cuSolverDx static library target.

mathdx::cusolverdx_fatbin

cuSolverDx fatbin library target. Available only for CUDA 12.8 or newer.

Defined Variables#

mathdx_cusolverdx_FOUND, cusolverdx_FOUND

True if cuSolverDx was found.

cusolverdx_INCLUDE_DIRS

cuSolverDx include directories.

mathdx_INCLUDE_DIRS

MathDx include directories.

cusolverdx_LIBRARIES

cuSolverDx library target.

cusolverdx_FATBIN

Path to cuSolverDx fatbin library libcusolverdx.fatbin

cusolverdx_LIBRARY_DIRS

The directory containing cuSolverDx library

mathdx_VERSION

MathDx package version number in X.Y.Z format.

cusolverdx_VERSION

cuSolverDx version number in X.Y.Z format.

MathDx/cuSolverDx version matrix

MathDx

cuSolverDx

25.01

0.1.0

25.01.1

0.1.1

25.06

0.2.0