# rocm/tensile architecture

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

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

## Overview

This project is Tensile – a highly complex, benchmark‐driven backend generator for GEMM and related tensor contraction libraries, developed primarily as the performance engine for rocBLAS on AMD GPUs. Its purpose is to create optimized GPU kernels tailored for matrix multiplications, batched GEMMs, and multi-dimensional tensor contractions via a vast, configurable solution and tuning infrastructure.

a. Core Engine & Library Generator:
- This includes the main “Tensile” Python modules (e.g., Tensile.py, TensileCreateLibrary.py, TensileMergeLibrary.py), which gather problem definitions, tuning configurations, and custom kernels.
- It processes configuration files from the Tensile/Configs and tuning directories.
b. Configuration and Tuning Subsystem:
- Tuning automation scripts in the tuning/automation folder that analyze performance and adjust configuration parameters.
c. Kernel Generation & Customization Layers:
- Components such as the BuildCommands modules (located under Tensile/BuildCommands) and KernelWriter modules (KernelWriterAssembly.py, KernelWriterSource.py, etc.) that generate assembly or HIP source code for the GPU.
- CustomKernels and EmbeddedData components which allow for specialized or user-defined kernels.
d. Testing and Validation:
- Extensive HostLibraryTests, unit tests (Tensile/Tests/unit), integration tests, and pre_checkin tests. This branch shows how automatically generated libraries are validated against expected solutions.
e. External Interfaces and Deployment:
- Peripheral components such as the “docker”, “docs”, and “cmake” directories, which support building, deployment, and documentation.

##### Interactions and Data Flows
- From the core engine, show flows into the Kernel Generation layer (via the KernelWriter and BuildCommands modules) that produces GPU kernel source files.
- Then, indicate the output library (and intermediate products, e.g., “embedded” or “merged” libraries) that integrate with rocBLAS.
- Feedback loops from the testing suites to the core engine—for example, performance or correctness results that can drive further tuning.

##### Architectural Patterns & Design Aesthetics
– Another (e.g., orange) for kernel writing and generation modules.
– Yet another (e.g., purple) for testing and validation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration and Tuning Subsystem"
        CT1["Tensile/Configs"]:::config
        CT2["tuning/configuration"]:::config
        CT3["tuning/automation"]:::config
    end

    subgraph "Core Engine & Library Generator"
        CE1["Tensile.py"]:::engine
        CE2["TensileCreateLibrary.py"]:::engine
        CE3["TensileMergeLibrary.py"]:::engine
        CE4["TensileRetuneLibrary.py"]:::engine
        CE5["TensileUpdateLibrary.py"]:::engine
    end

    subgraph "Kernel Generation & Customization Layers"
        KG1["Tensile/KernelWriter.py"]:::kernel
        KG2["Tensile/KernelWriterAssembly.py"]:::kernel
        KG3["Tensile/KernelWriterSource.py"]:::kernel
        KG4["Tensile/KernelWriterBetaOnly.py"]:::kernel
        KG5["Tensile/KernelWriterConversion.py"]:::kernel
        KG6["Tensile/KernelWriterStreamKInit.py"]:::kernel
        KG7["Tensile/BuildCommands"]:::kernel
        KG8["Tensile/CustomKernels"]:::kernel
        KG9["Tensile/EmbeddedData.py"]:::kernel
    end

    subgraph "Testing and Validation"
        T1["Tensile/Tests"]:::testing
        T2["HostLibraryTests"]:::testing
    end

    subgraph "Deployment & Integration"
        DI1["docker"]:::deployment
        DI2["docs"]:::deployment
        DI3["Tensile/cmake"]:::deployment
        DI4["setup.py"]:::deployment
        DI5["Library Output (rocBLAS)"]:::deployment
    end

    EC["External Consumers (rocBLAS)"]:::external

    %% Interactions and Data Flows
    CT1 -->|"configInput"| CE1
    CE1 -->|"process"| KG1
    KG1 -->|"generate"| DI5
    DI5 -->|"deployed_to"| EC
    T1 -->|"feedback"| CE1
    T2 -->|"feedback"| CE1

    %% Click Events for Configuration and Tuning Subsystem
    click CT1 "https://github.com/rocm/tensile/tree/develop/Tensile/Configs"
    click CT2 "https://github.com/rocm/tensile/tree/develop/tuning/configuration"
    click CT3 "https://github.com/rocm/tensile/tree/develop/tuning/automation"

    %% Click Events for Core Engine & Library Generator
    click CE1 "https://github.com/rocm/tensile/blob/develop/Tensile/Tensile.py"
    click CE2 "https://github.com/rocm/tensile/blob/develop/Tensile/TensileCreateLibrary.py"
    click CE3 "https://github.com/rocm/tensile/blob/develop/Tensile/TensileMergeLibrary.py"
    click CE4 "https://github.com/rocm/tensile/blob/develop/Tensile/TensileRetuneLibrary.py"
    click CE5 "https://github.com/rocm/tensile/blob/develop/Tensile/TensileUpdateLibrary.py"

    %% Click Events for Kernel Generation & Customization Layers
    click KG1 "https://github.com/rocm/tensile/blob/develop/Tensile/KernelWriter.py"
    click KG2 "https://github.com/rocm/tensile/blob/develop/Tensile/KernelWriterAssembly.py"
    click KG3 "https://github.com/rocm/tensile/blob/develop/Tensile/KernelWriterSource.py"
    click KG4 "https://github.com/rocm/tensile/blob/develop/Tensile/KernelWriterBetaOnly.py"
    click KG5 "https://github.com/rocm/tensile/blob/develop/Tensile/KernelWriterConversion.py"
    click KG6 "https://github.com/rocm/tensile/blob/develop/Tensile/KernelWriterStreamKInit.py"
    click KG7 "https://github.com/rocm/tensile/tree/develop/Tensile/BuildCommands"
    click KG8 "https://github.com/rocm/tensile/tree/develop/Tensile/CustomKernels"
    click KG9 "https://github.com/rocm/tensile/blob/develop/Tensile/EmbeddedData.py"

    %% Click Events for Testing and Validation
    click T1 "https://github.com/rocm/tensile/tree/develop/Tensile/Tests"
    click T2 "https://github.com/rocm/tensile/tree/develop/HostLibraryTests"

    %% Click Events for Deployment & Integration
    click DI1 "https://github.com/rocm/tensile/tree/develop/docker"
    click DI2 "https://github.com/rocm/tensile/tree/develop/docs"
    click DI3 "https://github.com/rocm/tensile/tree/develop/Tensile/cmake"
    click DI4 "https://github.com/rocm/tensile/blob/develop/setup.py"

    %% Styles
    classDef config fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef engine fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef kernel fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef testing fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef deployment fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef external fill:#c0c0c0,stroke:#333,stroke-width:2px;
```
