# rapidsai/cuml architecture

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

- Interactive diagram: https://gitdiagram.com/rapidsai/cuml
- Repository: https://github.com/rapidsai/cuml

## Overview

##### Key system components
- Core C++ Library: Represent the “cpp” directory which contains the low-level implementations of machine learning algorithms, CUDA kernels, and optimized routines (e.g., clustering, dimensionality reduction, linear models, etc.).
- Python API Layer: Illustrate the “python” directory where Python wrappers, bindings, and extension modules interface with the C++ layer. Show that this layer provides scikit-learn-like APIs.
- Dask/Dask-Associated Components: Highlight the “dask” integration inside the Python API (in python/cuml) for multi-GPU and distributed computing. Note the use of UCX and Dask CUDA to deploy on clusters.
- Build and CI/CD Infrastructure: Include the components such as the Conda recipes, Docker/Devcontainer configurations (.devcontainer), GitHub actions/workflows, build scripts (BUILD.md, ci/ scripts) and testing suites (cpp/tests, python/cuml/tests).
- Documentation and Notebooks: Mark the “docs” and “notebooks” directories as integrations for user guidance, benchmarking, and demonstration use cases.
- External Dependencies and Third-Party Integration: Indicate integration with third-party libraries (e.g., Faiss for nearest neighbors, cuDF for GPU dataframes, and adapters towards scikit-learn) and external services (e.g., UCX for fast GPU communication).

##### Relationships and interactions
- The Python API calls directly into the compiled C++ library via extension modules, bridging high-level algorithms with GPU-accelerated code.
- CI/CD pipelines (via GitHub Actions and various ci/ scripts) continuously build, test, and validate both the C++ and Python components.
- Devcontainer and Conda configuration files manage the reproducible environment for development and containerized testing.
- Dask integration supports deploying distributed GPU workloads over clusters. Show how Dask workers interact with cuML’s Dask-enabled estimators.
- External integrations such as libraries (Faiss, UCX, cuDF) are connected to the C++ and Python layers to enhance functionality and performance.

##### Architectural patterns and design principles
- Modular Design: Emphasize the separation by functionality (e.g., clustering, dimensionality reduction, linear models, etc.) and by language components (C++ modules versus Python modules).
- Extensibility: Note that there are clear extension points, for example, novel algorithm implementations in the “experimental” subdirectories and integration with third-party libraries.
- CI/CD and Testing: Include the automated build, test, and release processes as an integral part of ensuring quality and performance.
- Containerization: Recognize the use of different devcontainer configurations for different CUDA versions and build systems (pip versus Conda).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Components"
        A["C++ Core Library"]:::backend
        B["Python API Layer (scikit-learn)"]:::frontend
        C["Dask Distributed Layer"]:::dask
    end

    subgraph "Infrastructure"
        D["Build & CI/CD"]:::infrastructure
    end

    subgraph "Guidance"
        E["Documentation & Notebooks"]:::documentation
    end

    F["External Dependencies (Faiss, UCX, cuDF)"]:::external

    B -->|"calls"| A
    B -->|"integrates"| C
    D -->|"builds"| A
    D -->|"builds"| B
    F -->|"integrates"| A
    F -->|"integrates"| B
    E -->|"documents"| B
    E -->|"documents"| A

    click A "https://github.com/rapidsai/cuml/tree/branch-25.04/cpp"
    click B "https://github.com/rapidsai/cuml/tree/branch-25.04/python/cuml"
    click C "https://github.com/rapidsai/cuml/tree/branch-25.04/python/cuml/dask"
    click D "https://github.com/rapidsai/cuml/blob/branch-25.04/.devcontainer"
    click D "https://github.com/rapidsai/cuml/blob/branch-25.04/.github"
    click D "https://github.com/rapidsai/cuml/blob/branch-25.04/BUILD.md"
    click D "https://github.com/rapidsai/cuml/tree/branch-25.04/ci/"
    click E "https://github.com/rapidsai/cuml/tree/branch-25.04/docs"
    click E "https://github.com/rapidsai/cuml/tree/branch-25.04/notebooks"

    classDef backend fill:#ffaaaa,stroke:#990000,stroke-width:2px;
    classDef frontend fill:#aaccff,stroke:#003399,stroke-width:2px;
    classDef dask fill:#ddddff,stroke:#333399,stroke-width:2px;
    classDef infrastructure fill:#ccffcc,stroke:#339933,stroke-width:2px;
    classDef documentation fill:#fff0b3,stroke:#cc9900,stroke-width:2px;
    classDef external fill:#ffccff,stroke:#cc0099,stroke-width:2px;
```
