# pkraison/toonygrad architecture

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

- Interactive diagram: https://gitdiagram.com/pkraison/toonygrad
- Repository: https://github.com/pkraison/toonygrad

## Overview

- Core Engine and Codegen: Represented by directories like engine (including files such as realize.py and schedule.py). This is where the computation scheduling, code generation, and memory planning (referenced in the README) happens.
- Tensor & Operations: The tensor.py file is central, and it interacts with various modules (toonygrad/function.py, ops.py). Also include the “UOp” and related UOps elements, which are now used in place of LazyBuffer.
- Neural Network Layer (NN): The nn directory (with datasets, optim, state) indicates higher-level abstractions for training and inference.
- Backend & Runtime: Capture device-related functionalities (device.py) and runtime-specific operations (runtime/ops_clang.py). This is critical because the project now supports only the CLANG backend.
- Data Types and Helpers: Modules like dtype.py and helpers.py provide foundational support that is decoupled from the rest of tinygrad’s dependencies.

##### Relationships and data flow
- That the NN layer (neural network abstractions) builds on top of the tensor and engine components, using helper functions and datasets.
- The renderer should be shown as a utility that interfaces with both the engine and tensor components for formatting or debugging output.
- That the lower-level device and runtime layers feed the engine with hardware-specific operations (CLANG backend).

##### Architectural patterns or design principles
- Dependency inversion: Higher-level NN operations are built on lower-level tensor and engine functionalities.
- Emphasis on immutability and modern Python practices: The removal of mutable lazy buffers in favor of “immutable UOp” indicates design consistency favoring immutability.
- Monolithic core refactoring: Since toonygrad is “just a replacement of engine and codegen,” focus on the engine as the central orchestrator.

##### Additional details based on the README
- Dependency on Python 3.10 as an environment requirement.

## Diagram (Mermaid)

```mermaid
flowchart TD
    E["Engine/Core Codegen"]:::engine
    T["Tensor & UOps"]:::tensor
    N["NN/High-Level Abstractions"]:::nn
    B["Backend/CLANG Runtime"]:::backend
    D["Data Types & Helpers"]:::data
    S["Shape & Symbolics"]:::shape
    R["Renderer"]:::renderer

    T -->|"calls"| E
    N -->|"buildsOn"| T
    E -->|"uses"| B
    T -->|"monitors"| S
    T -->|"uses"| D
    N -->|"uses"| D
    R -->|"formats"| E
    R -->|"visualizes"| T

    click E "https://github.com/pkraison/toonygrad/blob/master/toonygrad/engine/realize.py"
    click E "https://github.com/pkraison/toonygrad/blob/master/toonygrad/engine/schedule.py"
    click T "https://github.com/pkraison/toonygrad/blob/master/toonygrad/tensor.py"
    click T "https://github.com/pkraison/toonygrad/blob/master/toonygrad/ops.py"
    click T "https://github.com/pkraison/toonygrad/blob/master/toonygrad/function.py"
    click N "https://github.com/pkraison/toonygrad/tree/master/toonygrad/nn/"
    click N "https://github.com/pkraison/toonygrad/blob/master/toonygrad/nn/datasets.py"
    click N "https://github.com/pkraison/toonygrad/blob/master/toonygrad/nn/optim.py"
    click N "https://github.com/pkraison/toonygrad/blob/master/toonygrad/nn/state.py"
    click B "https://github.com/pkraison/toonygrad/blob/master/toonygrad/device.py"
    click B "https://github.com/pkraison/toonygrad/blob/master/toonygrad/runtime/ops_clang.py"
    click D "https://github.com/pkraison/toonygrad/blob/master/toonygrad/dtype.py"
    click D "https://github.com/pkraison/toonygrad/blob/master/toonygrad/helpers.py"
    click S "https://github.com/pkraison/toonygrad/blob/master/toonygrad/shape/shapetracker.py"
    click S "https://github.com/pkraison/toonygrad/blob/master/toonygrad/shape/symbolic.py"
    click S "https://github.com/pkraison/toonygrad/blob/master/toonygrad/shape/view.py"
    click R "https://github.com/pkraison/toonygrad/blob/master/toonygrad/renderer/cstyle.py"

    classDef engine fill:#ffcc00,stroke:#333,stroke-width:2px
    classDef tensor fill:#ccffcc,stroke:#333,stroke-width:2px
    classDef nn fill:#ff9999,stroke:#333,stroke-width:2px
    classDef backend fill:#cce5ff,stroke:#333,stroke-width:2px
    classDef data fill:#d9d9d9,stroke:#333,stroke-width:2px
    classDef shape fill:#f7c6c7,stroke:#333,stroke-width:2px
    classDef renderer fill:#e2e2ff,stroke:#333,stroke-width:2px
```
