# jw1912/bullet architecture

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

- Interactive diagram: https://gitdiagram.com/jw1912/bullet
- Repository: https://github.com/jw1912/bullet

## Overview

##### Main Components

a) Core ML Framework Layer:
- Autograd System (/src/autograd/)
- Tensor Operations (/src/tensor/)
- Backend Operations (/src/backend/)

b) Hardware Acceleration Layer:
- CUDA Backend
- HIP Backend
- BLAS Integration Points

c) NNUE-Specific Components:
- Training System (/src/trainer/)
- Input Feature Handlers
- Output Bucket Management
- Network Architecture

**┌─ Application Layer ─────────────────────┐**
- Examples & Training Scripts             │
- ┬────────────────────┘
- ↓
**┌─ Domain Layer ────────────────────────────────────────┐**
- ┌─ Training Pipeline ─┐  ┌─ NNUE Specific Tools ─┐   │
- Default Trainer   │  │ - Input Features       │   │
- Schedule Manager  │  │ - Output Buckets       │   │
- Data Loader      │  │ - Network Architecture │   │
- ┘  └─────────────────────────┘   │
- ┬────────────────────────────────┘
- ↓
**┌─ Core ML Layer ──────────────────────────────────┐**
- ┌─ Autograd ─┐  ┌─ Tensor Ops ─┐  ┌─ Optimiser ┐│
- Graph    │  │ - Dense      │  │ - AdamW    ││
- Ops      │  │ - Sparse     │  │ - Utils    ││
- ┘  └─────────────┘  └────────────┘ │
- ┬───────────────────────────┘
- ↓
**┌─ Hardware Acceleration Layer ─────────────────────┐**
- ┌─ CUDA ────┐  ┌─ HIP ─────┐  ┌─ BLAS ────────┐ │
- Kernels   │  │ Kernels   │  │ Integration   │ │
- ┘  └───────────┘  └──────────────┘ │
- ┘

##### Important Relationships to Highlight

- Data flow from input features through the network
- Interaction between autograd and tensor operations
- Demonstrate how the hardware acceleration layer supports upper layers
- Training pipeline flow

##### Additional Elements

- Version/compatibility information
- Configuration points
- Extension points for custom implementations

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Application["Application Layer"]
        Examples["Examples & Training Scripts"]
    end

    subgraph Domain["Domain Layer"]
        subgraph Training["Training Pipeline"]
            Trainer["Default Trainer"]:::trainer
            Schedule["Schedule Manager"]:::trainer
            DataLoader["Data Loader"]:::loader
        end

        subgraph NNUE["NNUE Specific Tools"]
            InputFeatures["Input Features"]:::inputs
            OutputBuckets["Output Buckets"]:::outputs
            NetworkArch["Network Architecture"]
        end
    end

    subgraph Core["Core ML Layer"]
        subgraph AG["Autograd"]
            Graph["Graph Management"]:::autograd
            Operations["Operations"]:::autograd
        end

        subgraph Tensor["Tensor Operations"]
            Dense["Dense Matrix"]:::tensor
            Sparse["Sparse Matrix"]:::tensor
            CoreOps["Core Operations"]:::tensor
        end

        subgraph Opt["Optimizer"]
            AdamW["AdamW"]:::opt
            OptUtils["Utils"]:::opt
        end
    end

    subgraph Hardware["Hardware Acceleration Layer"]
        subgraph CUDA["CUDA"]
            CUDAKernels["CUDA Kernels"]:::cuda
            CUDNN["CUDNN Integration"]:::cuda
        end

        subgraph HIP["HIP"]
            HIPKernels["HIP Kernels"]:::hip
        end

        subgraph BLAS["BLAS"]
            BLASInt["BLAS Integration"]:::blas
        end
    end

    Examples --> Trainer
    Trainer --> Schedule
    Trainer --> DataLoader
    Trainer --> InputFeatures
    Trainer --> OutputBuckets
    InputFeatures --> Graph
    Graph --> Operations
    Operations --> Dense
    Operations --> Sparse
    Dense --> CoreOps
    Sparse --> CoreOps
    CoreOps --> CUDAKernels
    CoreOps --> HIPKernels
    CoreOps --> BLASInt
    Trainer --> AdamW
    AdamW --> OptUtils

    %% Component Mappings
    click Trainer "https://github.com/jw1912/bullet/tree/main/src/trainer/default/"
    click Schedule "https://github.com/jw1912/bullet/tree/main/src/trainer/schedule/"
    click DataLoader "https://github.com/jw1912/bullet/tree/main/src/trainer/default/loader/"
    click InputFeatures "https://github.com/jw1912/bullet/tree/main/src/trainer/default/inputs/"
    click OutputBuckets "https://github.com/jw1912/bullet/blob/main/src/trainer/default/outputs.rs"
    click Graph "https://github.com/jw1912/bullet/blob/main/src/autograd/graph.rs"
    click Operations "https://github.com/jw1912/bullet/blob/main/src/autograd/operation.rs"
    click Dense "https://github.com/jw1912/bullet/tree/main/src/tensor/dense_matrix/"
    click Sparse "https://github.com/jw1912/bullet/tree/main/src/tensor/sparse_matrix/"
    click CoreOps "https://github.com/jw1912/bullet/tree/main/src/tensor/operation/"
    click CUDAKernels "https://github.com/jw1912/bullet/blob/main/kernels/*.cu"
    click CUDNN "https://github.com/jw1912/bullet/blob/main/src/backend/bindings/cudnn.rs"
    click HIPKernels "https://github.com/jw1912/bullet/blob/main/src/backend/bindings/hip.rs"
    click AdamW "https://github.com/jw1912/bullet/blob/main/src/optimiser/adamw.rs"
    click OptUtils "https://github.com/jw1912/bullet/blob/main/src/optimiser/utils.rs"

    %% Styling
    classDef trainer fill:#90EE90
    classDef loader fill:#98FB98
    classDef inputs fill:#3CB371
    classDef outputs fill:#2E8B57
    classDef autograd fill:#87CEEB
    classDef tensor fill:#4682B4
    classDef opt fill:#B0C4DE
    classDef cuda fill:#FFA500
    classDef hip fill:#FF8C00
    classDef blas fill:#DAA520

    %% Legend
    subgraph Legend
        L1["Training Components"]:::trainer
        L2["Data Components"]:::loader
        L3["Core ML"]:::autograd
        L4["Hardware Acceleration"]:::cuda
    end
```
