# nvidia/cudalibrarysamples architecture

> Architecture diagram of the GitHub repository nvidia/cudalibrarysamples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia/cudalibrarysamples
- Repository: https://github.com/nvidia/cudalibrarysamples

## Overview

This project is an extensive repository of CUDA library samples that demonstrates a wide array of GPU-accelerated libraries for different computational domains. The overall purpose is to serve as both an educational and practical resource, showing how to integrate libraries for linear algebra (cuBLAS, cuBLASLt, cuBLASMp, cuBLASDx), FFT processing (cuFFT, cuFFTMp, cuFFTDx), random number generation (cuRAND), sparse matrix operations (cuSPARSE, cuSPARSELt), solvers (cuSOLVER, cuSOLVERMp, cuSOLVERSp2cuDSS), tensor operations (cuTENSOR, cuTENSORMg), image processing (NPP and its C++ extensions NPP+), JPEG and JPEG2000 encoding/decoding (nvJPEG, nvJPEG2000), TIFF processing (nvTIFF), and even compression (nvCOMP).

##### Main architectural components
- Repository Root – Acts as the umbrella for all the components.
- Library Sample Groups – These are the primary modules, each corresponding to a specific CUDA library. For example:
- Math and Linear Algebra: cuBLAS, cuBLASLt, cuBLASMp, cuBLASDx, cuDSS
- FFT Libraries: cuFFT, cuFFTMp, cuFFTDx
- Random Numbers: cuRAND
- Solvers: cuSOLVER, cuSOLVERMp, cuSOLVERSp2cuDSS
- Sparse Matrices: cuSPARSE, cuSPARSELt
- Tensor Operations: cuTENSOR, cuTENSORMg
- Image and Video Processing: NPP and NPP+
- JPEG / JPEG2000 / TIFF: nvJPEG, nvJPEG2000, nvTIFF
- Data Compression: nvCOMP
- Additionally, there are samples like cuPQC and others that illustrate specialized functionality.

##### Relationships and dependencies
- Each library module is relatively self-contained, often with its own README, examples, and build files (CMakeLists.txt, Makefile).
- Many modules share underlying CUDA concepts and utilities. For instance, common error checking, utility headers, and NVRTC helper components appear in several directories.

##### Important architectural patterns and design principles
- Modularity – Each library is housed in its own directory structure with separate examples and build configuration. This reinforces single responsibility and ease of navigation.
- Consistent build/deployment structure – Presence of CMakeLists.txt, Makefiles in each directory highlights a consistent build system across components.
- Layering – At the bottom layer, GPU accelerated kernel codes (in .cu files) reside; the upper layers present host code examples and integration samples to demonstrate how to call these kernels.
- Abstraction and separation – There is a clear separation between the device-side functionalities (e.g., cuBLASDx, cuFFTDx) versus host-side implementations (e.g., cuDSS, cuRAND/Host examples).

##### Relevant technologies, frameworks, and libraries
- CUDA, including its driver and runtime APIs.
- NVRTC, as seen in common NVRTC helper files.
- CMake and Make – the build systems used for compiling the samples.
- Specific GPU libraries (cuBLAS, cuFFT, etc.) which are the key technical stack.
- If desired, include integration points for Python and other language wrappers (as seen in cuTENSOR/python and cuFFTMp/JAX_FFT).

- Clear labels for each component: e.g., “cuBLAS Samples”, “cuFFT Examples”, “nvJPEG Decoder”, “NPP Image Processing”.
- Build tools (CMake/Make) as part of the infrastructure that enables the building/deployment of these samples.
- Annotations showing that the samples function as demonstrative use cases and reference implementations for leveraging the CUDA library stack.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    UA("User Application"):::user
    Repo("Repository Root"):::repo
    BT("Build Tools (CMake/Make)"):::build

    %% High-Level Flow
    UA -->|"calls"| Repo
    Repo -->|"builds via"| BT

    %% Math/Linear Algebra Subgraph
    subgraph "Math/Linear Algebra"
        CU_BLAS("cuBLAS Samples"):::math
        CU_BLAS_EXT("cuBLAS Extensions"):::math
        CU_BLASLT("cuBLASLt Samples"):::math
        CU_BLASMP("cuBLASMp Samples"):::math
        CU_BLASDX("cuBLASDx Samples"):::math
        CU_DSS("cuDSS Samples"):::math
    end
    Repo -->|"contains"| CU_BLAS
    CU_BLAS --> CU_BLAS_EXT
    CU_BLAS_EXT --> CU_BLASLT
    CU_BLASLT --> CU_BLASMP
    CU_BLASMP --> CU_BLASDX
    CU_BLASDX --> CU_DSS

    %% FFT Libraries Subgraph
    subgraph "FFT Libraries"
        CU_FFT("cuFFT Samples"):::fft
        CU_FFTDX("cuFFTDx Samples"):::fft
        CU_FFTMP("cuFFTMp Samples"):::fft
    end
    Repo -->|"contains"| CU_FFT
    CU_FFT --> CU_FFTDX
    CU_FFTDX --> CU_FFTMP

    %% Random Numbers Subgraph
    subgraph "Random Numbers"
        CU_RAND("cuRAND Samples"):::random
        CU_RANDDX("cuRANDDx Samples"):::random
    end
    Repo -->|"contains"| CU_RAND
    CU_RAND --> CU_RANDDX

    %% Solvers Subgraph
    subgraph "Solvers"
        CU_SOLVER("cuSOLVER Samples"):::solvers
        CU_SOLVERMP("cuSOLVERMp Samples"):::solvers
        CU_SOLVERSP("cuSOLVERSp2cuDSS Samples"):::solvers
    end
    Repo -->|"contains"| CU_SOLVER
    CU_SOLVER --> CU_SOLVERMP
    CU_SOLVERMP --> CU_SOLVERSP

    %% Sparse Matrices Subgraph
    subgraph "Sparse Matrices"
        CU_SPARSE("cuSPARSE Samples"):::sparse
        CU_SPARESLT("cuSPARSELt Samples"):::sparse
    end
    Repo -->|"contains"| CU_SPARSE
    CU_SPARSE --> CU_SPARESLT

    %% Tensor Operations Subgraph
    subgraph "Tensor Operations"
        CU_TENSOR("cuTENSOR Samples"):::tensor
        CU_TENSORMG("cuTENSORMg Samples"):::tensor
    end
    Repo -->|"contains"| CU_TENSOR
    CU_TENSOR --> CU_TENSORMG

    %% Image Processing Subgraph
    subgraph "Image and Video Processing"
        NPP("NPP Image Processing"):::image
        NPP_PLUS("NPP+ (C++ Extensions)"):::image
    end
    Repo -->|"contains"| NPP
    NPP --> NPP_PLUS

    %% JPEG / TIFF Subgraph
    subgraph "JPEG / JPEG2000 / TIFF"
        NV_JPEG("nvJPEG Samples"):::jpeg
        NV_JPEG2000("nvJPEG2000 Samples"):::jpeg
        NV_TIFF("nvTIFF Samples"):::jpeg
    end
    Repo -->|"contains"| NV_JPEG
    NV_JPEG --> NV_JPEG2000
    NV_JPEG2000 --> NV_TIFF

    %% Data Compression Subgraph
    subgraph "Data Compression"
        NV_COMP("nvCOMP"):::compression
    end
    Repo -->|"contains"| NV_COMP

    %% Specialized Functionality Subgraph
    subgraph "Specialized Samples"
        CU_PQC("cuPQC Samples"):::specialized
    end
    Repo -->|"contains"| CU_PQC

    %% Click Events
    click Repo "https://github.com/nvidia/cudalibrarysamples/blob/master/README.md"
    click CU_BLAS "https://github.com/nvidia/cudalibrarysamples/tree/master/cuBLAS"
    click CU_BLAS_EXT "https://github.com/nvidia/cudalibrarysamples/tree/master/cuBLAS/Extensions"
    click CU_BLASLT "https://github.com/nvidia/cudalibrarysamples/tree/master/cuBLASLt"
    click CU_BLASMP "https://github.com/nvidia/cudalibrarysamples/tree/master/cuBLASMp"
    click CU_BLASDX "https://github.com/nvidia/cudalibrarysamples/tree/master/MathDx/cuBLASDx"
    click CU_DSS "https://github.com/nvidia/cudalibrarysamples/tree/master/cuDSS"
    click CU_FFT "https://github.com/nvidia/cudalibrarysamples/tree/master/cuFFT"
    click CU_FFTDX "https://github.com/nvidia/cudalibrarysamples/tree/master/MathDx/cuFFTDx"
    click CU_FFTMP "https://github.com/nvidia/cudalibrarysamples/tree/master/cuFFTMp"
    click CU_RAND "https://github.com/nvidia/cudalibrarysamples/tree/master/cuRAND"
    click CU_RANDDX "https://github.com/nvidia/cudalibrarysamples/tree/master/MathDx/cuRANDDx"
    click CU_SOLVER "https://github.com/nvidia/cudalibrarysamples/tree/master/cuSOLVER"
    click CU_SOLVERMP "https://github.com/nvidia/cudalibrarysamples/tree/master/cuSOLVERMp"
    click CU_SOLVERSP "https://github.com/nvidia/cudalibrarysamples/tree/master/cuSOLVERSp2cuDSS"
    click CU_SPARSE "https://github.com/nvidia/cudalibrarysamples/tree/master/cuSPARSE"
    click CU_SPARESLT "https://github.com/nvidia/cudalibrarysamples/tree/master/cuSPARSELt"
    click CU_TENSOR "https://github.com/nvidia/cudalibrarysamples/tree/master/cuTENSOR"
    click CU_TENSORMG "https://github.com/nvidia/cudalibrarysamples/tree/master/cuTENSORMg"
    click NPP "https://github.com/nvidia/cudalibrarysamples/tree/master/NPP"
    click NPP_PLUS "https://github.com/nvidia/cudalibrarysamples/tree/master/NPP+"
    click NV_JPEG "https://github.com/nvidia/cudalibrarysamples/tree/master/nvJPEG"
    click NV_JPEG2000 "https://github.com/nvidia/cudalibrarysamples/tree/master/nvJPEG2000"
    click NV_TIFF "https://github.com/nvidia/cudalibrarysamples/tree/master/nvTIFF"
    click NV_COMP "https://github.com/nvidia/cudalibrarysamples/tree/master/nvCOMP"
    click CU_PQC "https://github.com/nvidia/cudalibrarysamples/tree/master/cuPQC"

    %% Styles
    classDef repo fill:#cccccc,stroke:#000000,stroke-width:2px;
    classDef math fill:#ffcccc,stroke:#660000,stroke-width:2px;
    classDef fft fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef random fill:#ccccff,stroke:#000066,stroke-width:2px;
    classDef solvers fill:#ffcc99,stroke:#993300,stroke-width:2px;
    classDef sparse fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef tensor fill:#ccffff,stroke:#006666,stroke-width:2px;
    classDef image fill:#ffccff,stroke:#660066,stroke-width:2px;
    classDef jpeg fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef compression fill:#e6ccff,stroke:#663399,stroke-width:2px;
    classDef specialized fill:#d9ead3,stroke:#336633,stroke-width:2px;
    classDef build fill:#f2f2f2,stroke:#999999,stroke-width:2px;
    classDef user fill:#ffebcc,stroke:#cc6600,stroke-width:2px;
```
