# rocm/rccl-tests architecture

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

- Interactive diagram: https://gitdiagram.com/rocm/rccl-tests
- Repository: https://github.com/rocm/rccl-tests

## Overview

##### Main Components
- Build & Configuration System:
- Build scripts (Makefile at root, CMakeLists.txt in root and under “src”) and installation scripts (install.sh).
- Configuration for different environments: HIP, MPI, RCCL is configurable via environment variables (e.g., HIP_HOME, NCCL_HOME, MPI_HOME).
- Core Test Implementations:
- The “src” directory contains the core C/CUDA source files (e.g., all_reduce.cu, broadcast.cu, alltoall.cu, etc.) which implement different collective operations.
- “verifiable” directory holds additional tests or verification components (e.g., verifiable.cu, verifiable.h, Makefile) used to verify correctness.
- Automated Unit & Integration Testing:
- The “test” directory houses Python unit tests (using pytest) that likely run higher-level correctness checks.
- CI/CD & Scripting:
- Directories like “.github” and “.jenkins” contain CI configuration files (GitHub workflows, Jenkins groovy scripts) that integrate continuous testing and static analysis into the development process.
- Docker Environment:
- Dockerfiles in the “docker” directory show that containerized builds/installations are supported, targeting different platforms (Centos, Ubuntu).

##### Relationships and Interactions
- The build system (Make/CMake) compiles the CUDA-based tests from the “src” folder and also may handle the “verifiable” components.
- The test runners (both binary executables built from “src” and the Python tests in “test”) are executed either locally or via MPI in multi-GPU environments.
- CI/CD tools (Jenkins, GitHub Actions) trigger builds and tests automatically upon code changes.
- Docker environments provide isolated and reproducible build and run contexts to ensure consistency across different platforms.
- External dependencies like HIP, MPI, and RCCL are injected at build time via environmental variables and compiler configurations.

##### Important Architectural Patterns and Design Principles
- Separation of Concerns: Differentiation between core operations (in “src”), verification (“verifiable”), unit tests (“test”), and deployment/integration (CI/CD scripts and Dockerfiles).
- Configurability: The build scripts and README emphasize tailoring builds via specific environment variables and flags (e.g., MPI support, HIP paths).
- Modular Testing: The design supports both performance and functional correctness testing—each collective operation is individually implemented and then tested.
- Containerization and Continuous Integration: The existence of Docker and CI configuration promotes reproducibility and automated testing.

##### Relevant Technologies, Frameworks, or Libraries
- Programming Languages: C/CUDA (in .cu and .cc files), Python for testing.
- Build Tools: Make, CMake.
- CI/CD: Jenkins and GitHub Actions.
- Containerization: Docker.
- Dependencies: HIP, MPI, RCCL. Additionally, frameworks like pytest for unit testing.
- Performance Benchmarking: Custom command-line argument parsing to set testing parameters (number of GPUs, threads, message sizes, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Dependencies
    subgraph "External Dependencies"
        HIP["HIP"]:::external
        MPI["MPI"]:::external
        RCCL["RCCL"]:::external
    end

    %% Build & Configuration System
    subgraph "Build & Configuration System"
        BC1["Makefile"]:::build
        BC2["CMakeLists.txt"]:::build
        BC3["install.sh"]:::build
        BC4["src/CMakeLists.txt"]:::build
        BC5["src/Makefile"]:::build
    end

    %% Core Test Implementations
    subgraph "Core Test Implementations"
        CORE["src"]:::source
    end

    %% Verification & Additional Testing
    subgraph "Verification & Additional Testing"
        VER["verifiable"]:::verify
    end

    %% Automated Unit & Integration Testing
    subgraph "Automated Unit & Integration Testing"
        TEST["test"]:::test
    end

    %% CI/CD & Scripting
    subgraph "CI/CD & Scripting"
        GITHUB[".github"]:::ci
        JENKINS[".jenkins"]:::ci
    end

    %% Docker Environment
    subgraph "Docker Environment"
        DOCKER["docker"]:::docker
    end

    %% Relationships: External Dependencies to Build System
    HIP -->|"depends"| BC1
    MPI -->|"depends"| BC1
    RCCL -->|"depends"| BC1

    %% CI/CD & Docker trigger Build System
    GITHUB -->|"triggers"| BC1
    JENKINS -->|"triggers"| BC1
    DOCKER -->|"provides isolated build"| BC1

    %% Build System compiles tests
    BC1 -->|"compiles"| CORE
    BC1 -->|"compiles"| VER

    %% Core and Verification feed Automated Testing
    CORE -->|"tested by"| TEST
    VER -->|"tested by"| TEST

    %% CI/CD triggers testing
    GITHUB -->|"triggers"| TEST
    JENKINS -->|"triggers"| TEST

    %% Click Events for Build & Configuration System
    click BC1 "https://github.com/rocm/rccl-tests/tree/develop/Makefile"
    click BC2 "https://github.com/rocm/rccl-tests/blob/develop/CMakeLists.txt"
    click BC3 "https://github.com/rocm/rccl-tests/blob/develop/install.sh"
    click BC4 "https://github.com/rocm/rccl-tests/blob/develop/src/CMakeLists.txt"
    click BC5 "https://github.com/rocm/rccl-tests/tree/develop/src/Makefile"

    %% Click Event for Core Test Implementations
    click CORE "https://github.com/rocm/rccl-tests/tree/develop/src"

    %% Click Event for Verification and Additional Testing
    click VER "https://github.com/rocm/rccl-tests/tree/develop/verifiable"

    %% Click Event for Automated Unit & Integration Testing
    click TEST "https://github.com/rocm/rccl-tests/tree/develop/test"

    %% Click Events for CI/CD & Scripting
    click GITHUB "https://github.com/rocm/rccl-tests/blob/develop/.github"
    click JENKINS "https://github.com/rocm/rccl-tests/blob/develop/.jenkins"

    %% Click Event for Docker Environment
    click DOCKER "https://github.com/rocm/rccl-tests/tree/develop/docker"

    %% Styles
    classDef build fill:#9ad1f2,stroke:#333,stroke-width:2px;
    classDef source fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef verify fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef test fill:#f4d03f,stroke:#333,stroke-width:2px;
    classDef ci fill:#82e0aa,stroke:#333,stroke-width:2px;
    classDef docker fill:#d98880,stroke:#333,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#333,stroke-width:2px;
```
