Installation Guide#

nvCOMPDx is distributed as part of the MathDx package. To download the most recent release of the MathDx package including nvCOMPDx, visit the https://developer.nvidia.com/nvcompdx-downloads website.

Note

The 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,

  • nvCOMPDx for compression and decompression.

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

Note that when using multiple device extension libraries in a project, all libraries must come from the same MathDx release. Examples of such integration are included in the package.

nvCOMPDx In Your Project#

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

The libnvcompdx.fatbin library contains only device code and therefore it is host platform agnostic. For example, it can be safely used on AArch64 platforms, whereas libnvcompdx.a can only be used for x86_64 Linux builds.

Important

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

# When using libnvcompdx.a (static library)
nvcc -dlto -std=c++17 -arch sm_XY (...) -I<mathdx_include_dir> <your_source_file>.cu -o <your_binary> -lnvcompdx

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

The -dlto option at link time instructs the linker to retrieve the LTO IR (link-time-optimizable intermediate representation) 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 the fatbin file libnvcompdx.fatbin or the library file libnvcompdx.a. Fatbin has to be used for platforms other than x86_64 Linux.

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

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

The library files libnvcompdx.a and libnvcompdx.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.

nvCOMPDx In Your CMake Project#

The MathDx package provides configuration files that simplify using nvCOMPDx in other CMake projects. After finding mathdx using find_package, users have to link mathdx::nvcompdx to their target. This ensures device linking against libnvcompdx.a and propagates the include directory nvcompdx_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 the mathdx::nvcompdx_fatbin target. It can be used instead of mathdx::nvcompdx. This target uses the libnvcompdx.fatbin library, which in contrast to libnvcompdx.a, contains only device code and thus is host platform agnostic. For example, it can be safely used on AArch64 platforms, whereas libnvcompdx.a can only be used for x86_64 Linux builds.

Important

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

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

# Find nvCOMPDx
find_package(mathdx REQUIRED COMPONENTS nvcompdx CONFIG)
# Enable LTO in your target
set_target_properties(YourProgram
      PROPERTIES
          CUDA_SEPARABLE_COMPILATION ON
          INTERPROCEDURAL_OPTIMIZATION ON)
# Link against mathdx::nvcompdx
target_link_libraries(YourProgram mathdx::nvcompdx)
# or
# Link against mathdx::nvcompdx_fatbin
target_link_libraries(YourProgram mathdx::nvcompdx_fatbin)

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

find_package(mathdx REQUIRED COMPONENTS nvcompdx 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::nvcompdx

nvCOMPDx static library target.

mathdx::nvcompdx_fatbin

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

Defined Variables#

mathdx_nvcompdx_FOUND, nvcompdx_FOUND

True if nvCOMPDx was found.

nvcompdx_INCLUDE_DIRS

nvCOMPDx include directories.

mathdx_INCLUDE_DIRS

MathDx include directories.

nvcompdx_LIBRARIES

nvCOMPDx library target.

nvcompdx_FATBIN

Path to the nvCOMPDx fatbin library libnvcompdx.fatbin

nvcompdx_LIBRARY_DIRS

The directory containing the nvCOMPDx library

mathdx_VERSION

MathDx package version number in major.minor.patch format.

nvcompdx_VERSION

nvCOMPDx version number in major.minor.patch format.

MathDx/nvCOMPDx version matrix

MathDx

nvCOMPDx

25.06

0.1.0