# rickyyuan07/cmu10714-needle architecture

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

- Interactive diagram: https://gitdiagram.com/rickyyuan07/cmu10714-needle
- Repository: https://github.com/rickyyuan07/cmu10714-needle

## Overview

##### Main Components
- Front-end / Application Layer: Although there are “apps” in hw1, hw2, hw4, and hw4_extra, these mostly serve as examples or entry points demonstrating how the framework is used.
- Core Library (Needle Package): This is the heart of the framework and appears in nearly every hw directory. Key modules include:
– Autograd Engine (needle/autograd.py): Manages automatic differentiation.
– Backend Interface (backend_numpy.py, backend_ndarray/…): Provides low-level tensor operations with different backend implementations (NumPy based, CPU/ CUDA NDArray-based, etc.).
– Data Handling (needle/data/…): Contains modules for data transformations and dataset classes (e.g., mnist_dataset, cifar10_dataset, ptb_dataset).
– Neural Network Modules (needle/nn/…): Support definitions for basic neural network layers, convolutional layers, sequence models, and even transformer-related components (in hw4_extra).
– Initialization and Optimizer Modules (needle/init, needle/optim.py): Handle parameter initialization and optimization routines.
- Data and Testing: Each hw also includes a “data” folder for datasets and a “tests” folder to verify functionality. These are critical for understanding data flow and ensuring correctness.

##### Out the Relationships and Interactions
- The Application Layer calls into the Core Library for model definition and training.
- The Autograd Engine works closely with the backend layers, computing gradients as operations are executed.
- The Backend abstracts the computation (with variants for CPU and CUDA) and underpins the tensor operations used all over the system.
- Data modules feed data into pipelines used by models and training scripts.
- The Optimizer module interacts with both the model parameters (from the NN layer) and the computed gradients (from autograd) to update weights.
- Testing modules validate the behavior of each core component.

##### Architectural Patterns and Evolutions
- Modular Design: The repeated “needle” folder in each hw shows a deliberate separation of concerns – each module (autograd, data, nn, optimizer) is designed to be swappable or independently improved.
- Layered Abstraction: There is a clear layering from low-level array operations (backends) up to high-level NN modules and application examples.
- Incremental Enhancement: The repository’s structure (hw0 through hw4_extra) documents how new features are added. For instance, early assignments introduce simple ML routines (hw0), then add autograd support and basic backend operations (hw1–hw2), and later extend to more complex models (hw3–hw4_extra).

##### Incorporate Relevant Technologies
- Python is the base programming language with a clear structure in the “needle” package.
- C++/CUDA sources are present in the “src” subdirectories (in hw3 and hw4/ hw4_extra), supporting lower-level backends.
- Testing frameworks and Jupyter notebooks (.ipynb files) provide interactive experimentation and validation.
- Build systems like Makefile and CMakeLists.txt indicate that native-code compilation is involved for backend components.

##### Final Elements to be included
- Clear labels for each major component.
- Notations on technology choices, including references to the Python core, C++/CUDA backends, and dataset modules.
- A visual representation of how different assignments build upon one another, showing an evolution from a simple ML system (hw0) to a more full-featured deep learning framework (hw4_extra).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Application Layer
    subgraph "Application / Demo Layer"
        A["Application / Demo Layer"]:::frontend
    end

    %% Core Library (Needle Package)
    subgraph "Core Library (Needle Package)"
        AG["Autograd Engine"]:::core
        NN["Neural Network Modules"]:::core
        INIT["Initialization Modules"]:::core
        OPT["Optimizer Modules"]:::core
        DATA["Data Handling"]:::data
        subgraph "Backend Interfaces"
            BE_NP["Backend Interface (NumPy)"]:::backend
            BE_ND["Backend Interface (NDArray)"]:::backend
        end
        TESTS["Testing Suite"]:::core
    end

    %% Connections between layers
    A -->|"calls"| NN
    A -->|"feeds"| DATA
    A -->|"triggers"| OPT
    DATA -->|"supplies"| NN
    INIT -->|"initializes"| NN
    NN -->|"computes_gradients"| AG
    AG -->|"invokes"| BE_NP
    AG -->|"invokes"| BE_ND
    OPT -->|"updates"| NN
    TESTS -->|"validates"| AG
    TESTS -->|"validates"| NN
    TESTS -->|"validates"| OPT
    TESTS -->|"validates"| DATA

    %% Click Events
    click A "https://github.com/rickyyuan07/cmu10714-needle/tree/main/hw4/apps/"
    click AG "https://github.com/rickyyuan07/cmu10714-needle/blob/main/hw1/python/needle/autograd.py"
    click BE_NP "https://github.com/rickyyuan07/cmu10714-needle/blob/main/hw1/python/needle/backend_numpy.py"
    click BE_ND "https://github.com/rickyyuan07/cmu10714-needle/tree/main/hw3/python/needle/backend_ndarray/"
    click DATA "https://github.com/rickyyuan07/cmu10714-needle/tree/main/hw2/python/needle/data/"
    click NN "https://github.com/rickyyuan07/cmu10714-needle/blob/main/hw2/python/needle/nn/nn_basic.py"
    click INIT "https://github.com/rickyyuan07/cmu10714-needle/blob/main/hw1/python/needle/init/init_basic.py"
    click OPT "https://github.com/rickyyuan07/cmu10714-needle/blob/main/hw2/python/needle/optim.py"

    %% Styles
    classDef frontend fill:#fbbc05,stroke:#d2ab00,stroke-width:2px,color:#000;
    classDef core fill:#d1e8ff,stroke:#1c75bc,stroke-width:2px,color:#000;
    classDef backend fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000;
    classDef data fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000;
```
