# tracel-ai/burn architecture

> Architecture diagram of the GitHub repository tracel-ai/burn, 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/tracel-ai/burn
- Repository: https://github.com/tracel-ai/burn

## Overview

##### Main Components
- Core Engine: At the heart is the central "burn" crate with modules responsible for core tensor operations, mathematical functions, and handling data (e.g., tensor creation, tensor API, and basic utilities).
- Backend Infrastructure: There are multiple backend implementations (WGPU, Candle, LibTorch, NdArray, etc.) that are used to execute computations. They are organized as separate crates under “crates” (for instance, burn-wgpu, burn-candle, burn-tch, burn-ndarray). These backends are generic over a common Backend trait so that they can be interchanged.
- Training & Inference Modules: The framework separates the training loop, checkpointing, logging, and metrics gathering into dedicated crates (such as burn-train, learner components, logger, and metric modules). This layer handles the orchestration of training pipelines and asynchronous execution.
- Import & IR Support: There are crates for model import (e.g., burn-import for ONNX or PyTorch model conversion) and intermediate representation (like burn-ir) that ease model exchange between frameworks.
- Examples & Documentation: The repository also includes a wide range of examples (e.g., mnist, text-generation, image classification ones) that demonstrate how the components work together. Although not part of the core runtime, these serve as usage and integration testing scenarios.

##### Relationships and Interactions
- Connections between the Import components (burn-import) and the Core Engine, signifying that they translate models from other frameworks into an internal representation that can be executed using the Core and selected backends.

##### Architectural Patterns & Design Principles
- Use of the Decorator Pattern – highlight that “Autodiff” and “Fusion” are not independent backends but are wrappers that augment a chosen backend.
- Make clear the Separation of Concerns: core tensor operations, computational graph and autodifferentiation, asynchronous execution details, backend specific optimization (kernel fusion, asynchronous scheduling, memory pooling), and training orchestration/logging.
- Plug-and-play nature – by using a common Backend trait, the system can swap among WGPU, Candle, LibTorch, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Import & IR Support"
        I1["Burn Import (Model Importer)"]
        I2["Burn IR (IR Conversion)"]
    end

    subgraph "Core Layer"
        Core["Burn Core (Tensor API, Modules)"]
    end

    subgraph "Decorator Layers"
        D1["Decorator: Autodiff"]
        D2["Decorator: Fusion"]
    end

    subgraph "Backend Infrastructure"
        BA["Backend Abstraction"]
        B1["WGPU Backend"]
        B2["Candle Backend"]
        B3["LibTorch/Tch Backend"]
        B4["NdArray Backend"]
        B5["CubeCL Backend"]
        B6["CUDA Backend"]
    end

    subgraph "Training & Inference Modules"
        T1["Burn Train (Training & Inference)"]
    end

    subgraph "Examples & Documentation"
        E1["Documentation (burn-book)"]
        E2["Examples"]
    end

    %% Connections from Import & IR Support to Core and Backend
    I1 -->|"imports_to"| Core
    I2 -->|"ir_to_core"| Core
    I2 -->|"optimizes"| BA

    %% Connections from Core to Decorator Layers
    Core -->|"autodiff"| D1
    Core -->|"fusion"| D2

    %% Connections from Decorator Layers to Backend Abstraction
    D1 -->|"wraps"| BA
    D2 -->|"wraps"| BA

    %% Training module triggers core operations
    T1 -->|"trains"| Core

    %% Backend Abstraction connects to individual Backends
    BA -->|"uses"| B1
    BA -->|"uses"| B2
    BA -->|"uses"| B3
    BA -->|"uses"| B4
    BA -->|"uses"| B5
    BA -->|"uses"| B6

    %% Class Definitions for Colors
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#ABEBC6,stroke:#229954,stroke-width:2px;
    classDef decorator fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef training fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef impir fill:#D5DBDB,stroke:#566573,stroke-width:2px;
    classDef documentation fill:#FAD7A0,stroke:#D35400,stroke-width:2px;

    %% Assign Classes
    class Core core;
    class I1,I2 impir;
    class D1,D2 decorator;
    class T1 training;
    class BA,B1,B2,B3,B4,B5,B6 backend;
    class E1,E2 documentation;

    %% Click Events
    click Core "https://github.com/tracel-ai/burn/tree/main/crates/burn/src"
    click B1 "https://github.com/tracel-ai/burn/tree/main/crates/burn-wgpu"
    click B2 "https://github.com/tracel-ai/burn/tree/main/crates/burn-candle"
    click B3 "https://github.com/tracel-ai/burn/tree/main/crates/burn-tch"
    click B4 "https://github.com/tracel-ai/burn/tree/main/crates/burn-ndarray"
    click B5 "https://github.com/tracel-ai/burn/tree/main/crates/burn-cubecl"
    click B6 "https://github.com/tracel-ai/burn/tree/main/crates/burn-cuda"
    click D1 "https://github.com/tracel-ai/burn/tree/main/crates/burn-autodiff"
    click D2 "https://github.com/tracel-ai/burn/tree/main/crates/burn-fusion"
    click T1 "https://github.com/tracel-ai/burn/tree/main/crates/burn-train"
    click I1 "https://github.com/tracel-ai/burn/tree/main/crates/burn-import"
    click I2 "https://github.com/tracel-ai/burn/tree/main/crates/burn-ir"
    click E1 "https://github.com/tracel-ai/burn/tree/main/burn-book"
    click E2 "https://github.com/tracel-ai/burn/tree/main/examples/"
```
