# deeplink-org/dlblas architecture

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

- Interactive diagram: https://gitdiagram.com/deeplink-org/dlblas
- Repository: https://github.com/deeplink-org/dlblas

## Overview

##### Project Type and Purpose
- DLBlas is an open-source, Python-based operator library for Triton kernels.

##### High-Level Architecture
- **API Layer**
- Entry points for users:
– `dlblas.utils.get_op(…)` fetches a tuned operator.
– Direct imports like `from dlblas.kernels.rms_norm import rms_norm`.
– Top-level calls like `dlblas.topk_gating(...)`.
- **Frontend Parsers** (`dlblas/frontend`)
- FX-based parsers that transform user code or Torch modules into an intermediate representation (IR).
- **Operator Registry** (`dlblas/op_registry.py`, `dlblas/op_struct.py`)
- Central registry mapping operator names and signatures to available kernel implementations.
- **Autotuner Subsystem** (`dlblas/autotune`)
- **Search Space** (`space.py`) defines tunable parameters (block sizes, tile sizes).
- **Policy** (`policy.py`) implements search strategies (Bayesian, heuristic).
- **Dynamic Compiler & Passes** (`dynamic_compiler.py`, `passes.py`) generate and optimize kernel code.
- **Autotuner** (`autotuner.py`, `configs.py`) orchestrates the search, measures performance, and picks the best configuration.
- **Cache** (`dlblas/cache.py`)
- **Kernel Implementations** (`dlblas/kernels`)
- Hardware-specific and Triton kernels organized by backend:
– `ascend`, `camb`, `cutlass`, pure Triton, FP8 variants, fused operations, etc.
- **Layer Abstractions** (`dlblas/layers`)
- Higher-level modules, e.g., MoE (`dlblas/layers/moe`) built atop kernels.
- **Utilities** (`dlblas/utils`)
- Device queries, logging, op collection, MOE helpers, general helpers.
- **Examples & Benchmarks**
- `benchmarks/`: performance scripts per hardware and kernel.
- `examples/`: end-to-end training scripts for MoE models.
- **Tests** (`tests/`)
- Unit and e2e tests validating kernels, autotuning, caching, and end-to-end scenarios.

##### Component Relationships and Data Flow
1. **User Code** calls **API Layer**.
2. API invokes **Frontend Parsers** (optional) to build IR.
3. **Registry** looks up candidate kernels for the requested op/signature.
4. **Cache** is queried:
- Hit: return cached kernel + config.
- Miss: pass candidates to **Autotuner Subsystem**.
5. **Autotuner** runs benchmark loops via **Dynamic Compiler** and **Search Policy** over the **Search Space**, collects performance metrics.
6. Best config is chosen and stored in the **Cache**.
7. Kernel implementation is loaded from **Kernel Modules** and executed on device.
8. **Utilities** provide device info, logging, and metrics throughout.

##### Architectural Patterns and Principles
- **Plugin/Registry Pattern** for kernel discovery and extension.
- **Strategy Pattern** for search policies (swap in Bayesian vs. random).
- **Caching Layer** to avoid redundant tuning.
- **Separation of Concerns**: parsing, registry, tuning, caching, execution all modular.
- **Extensibility**: new hardware backends or kernels drop into `dlblas/kernels` and auto-register.

## Diagram (Mermaid)

```mermaid
graph TB
    classDef subsystem fill:#f9f,stroke:#333,stroke-width:1px
    classDef pluggable fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#efe,stroke:#333,stroke-width:1px

    UC["User Code"]:::external
    API["API Layer"]:::subsystem
    subgraph "Frontend Parsers"
        FX1["fx_parser.py"]:::subsystem
        FX2["fx_runnable_module_parser.py"]:::subsystem
    end
    subgraph "Operator Registry"
        REG1["op_registry.py"]:::subsystem
        REG2["op_struct.py"]:::subsystem
    end
    Cache["Cache"]:::subsystem
    subgraph "Autotuner Subsystem"
        SS["Search Space"]:::pluggable
        SP["Policy"]:::pluggable
        DC["Dynamic Compiler"]:::pluggable
        PS["Compiler Passes"]:::pluggable
        AT["Autotuner"]:::pluggable
        CF["Configs"]:::pluggable
    end
    subgraph "Kernel Implementations"
        ASC["ascend"]:::pluggable
        CAMB["camb"]:::pluggable
        CUT["cutlass"]:::pluggable
        TRI["triton & variants"]:::pluggable
    end
    subgraph "Layer Abstractions"
        MOE1["ep_moe.py"]:::pluggable
        MOE2["eplb.py"]:::pluggable
        MOE3["experts_distribution_recorder.py"]:::pluggable
        MOEK["moe kernels"]:::pluggable
    end
    subgraph "Utilities"
        U1["device_utils.py"]:::pluggable
        U2["logger.py"]:::pluggable
        U3["moe_utils.py"]:::pluggable
        U4["op_collector.py"]:::pluggable
        U5["op_helper.py"]:::pluggable
        U6["utils.py"]:::pluggable
    end
    Hardware["Triton / Hardware Runtime"]:::external

    UC -->|"calls"| API
    API -->|"parsing"| FX1
    API --> FX2
    FX1 --> REG1
    FX2 --> REG1
    REG1 --> REG2
    REG2 --> Cache
    Cache -->|hit| ASC
    Cache -->|hit| CAMB
    Cache -->|hit| CUT
    Cache -->|hit| TRI
    Cache -->|miss| SS
    SS --> SP
    SP --> DC
    DC --> PS
    PS --> AT
    AT --> CF
    CF --> Cache
    Cache --> ASC
    Cache --> CAMB
    Cache --> CUT
    Cache --> TRI
    ASC --> Hardware
    CAMB --> Hardware
    CUT --> Hardware
    TRI --> Hardware
    API --> U1
    API --> U2
    AT --> U3
    AT --> U4
    AT --> U5
    AT --> U6

    click API "https://github.com/deeplink-org/dlblas/blob/main/dlblas/__init__.py"
    click FX1 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/frontend/fx_parser.py"
    click FX2 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/frontend/fx_runnable_module_parser.py"
    click REG1 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/op_registry.py"
    click REG2 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/op_struct.py"
    click SS "https://github.com/deeplink-org/dlblas/blob/main/dlblas/autotune/space.py"
    click SP "https://github.com/deeplink-org/dlblas/blob/main/dlblas/autotune/policy.py"
    click DC "https://github.com/deeplink-org/dlblas/blob/main/dlblas/autotune/dynamic_compiler.py"
    click PS "https://github.com/deeplink-org/dlblas/blob/main/dlblas/autotune/passes.py"
    click AT "https://github.com/deeplink-org/dlblas/blob/main/dlblas/autotune/autotuner.py"
    click CF "https://github.com/deeplink-org/dlblas/blob/main/dlblas/autotune/configs.py"
    click Cache "https://github.com/deeplink-org/dlblas/blob/main/dlblas/cache.py"
    click ASC "https://github.com/deeplink-org/dlblas/tree/main/dlblas/kernels/ascend"
    click CAMB "https://github.com/deeplink-org/dlblas/tree/main/dlblas/kernels/camb"
    click CUT "https://github.com/deeplink-org/dlblas/tree/main/dlblas/kernels/cutlass"
    click TRI "https://github.com/deeplink-org/dlblas/tree/main/dlblas/kernels"
    click MOE1 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/layers/moe/ep_moe.py"
    click MOE2 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/layers/moe/eplb.py"
    click MOE3 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/layers/moe/experts_distribution_recorder.py"
    click MOEK "https://github.com/deeplink-org/dlblas/tree/main/dlblas/layers/moe/kernels"
    click U1 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/utils/device_utils.py"
    click U2 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/utils/logger.py"
    click U3 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/utils/moe_utils.py"
    click U4 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/utils/op_collector.py"
    click U5 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/utils/op_helper.py"
    click U6 "https://github.com/deeplink-org/dlblas/blob/main/dlblas/utils/utils.py"

    class UC,Hardware external
    class API,REG1,REG2,Cache,FX1,FX2 subsystem
    class SS,SP,DC,PS,AT,CF,ASC,CAMB,CUT,TRI,MOE1,MOE2,MOE3,MOEK,U1,U2,U3,U4,U5,U6 pluggable
```
