# pranavphoenix/wavemix architecture

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

- Interactive diagram: https://gitdiagram.com/pranavphoenix/wavemix
- Repository: https://github.com/pranavphoenix/wavemix

## Overview

##### Project Type and Purpose
- This is an open-source Python library (“wavemix”) for resource-efficient computer-vision tasks: image classification, semantic segmentation, and single-image super-resolution.
- It provides core neural architectures (WaveMix and WaveMix-Lite) based on 2D discrete wavelet transforms, example scripts for various datasets, and pretrained model weights.

##### File Structure Analysis
- Top-level folders:
- **Image_Classification**, **Semantic_Segmentation**, **Image_Super_Resolution** – example/training scripts for each task.
- **Saved_weights** – pretrained model checkpoints organized by dataset.
- **wavemix/** – core Python package implementing the WaveMix architectures:
– classification.py
– SemSegment.py
– sisr.py
– waveblock modules (in __init__.py or submodules)
- Other files: setup.py for packaging, README.md for project description, LICENSE.

##### README Insights
- Describes three main use-cases: classification, segmentation, super-resolution.
- Lists dependencies (PyTorch), installation, usage examples for each task.

##### Main Components
a. **User Applications / Scripts**
- Example scripts under Image_Classification, Semantic_Segmentation, Image_Super_Resolution.
- They handle dataset loading, model instantiation, training/inference loops, evaluation.
b. **Core Library (“wavemix” package)**
- Task-specific modules: classification.py, SemSegment.py, sisr.py.
- Shared WaveMix blocks implementing 2D-DWT token mixing.
- Utilities: initial convolutions, upsampling/deconvolutions, feed-forward MLP layers.
c. **External Dependencies**
- PyTorch (torch), torchvision or custom dataset loaders.
d. **Data Sources**
- Datasets (CIFAR-10, ImageNet, Cityscapes, DIV2K, Galaxy10, TinyImageNet, etc.)
- Data augmentation and preprocessing pipelines.
e. **Model Weights Store**
- Saved_weights directory organizing pretrained checkpoints.
f. **Output / Evaluation**
- Metrics (accuracy, mIoU, PSNR).
- Inference outputs (class labels, segmentation masks, super-resolved images).

##### Component Relationships and Data Flow
- **Scripts → Core Library**: example scripts import wavemix modules.
- **Core Library** uses **WaveMix Blocks** to build models.
- **Data Loader** feeds mini-batches to **Model**.
- **Model** produces predictions → loss calculation → backpropagation → updated **Model**.
- **Trained Weights** saved to **Saved_weights**.
- **Inference Pipeline** loads **Saved_weights**, runs Model on new images → outputs.

##### Architectural Patterns and Design Principles
- **Modular Package Design**: clear separation by task, shared building blocks.
- **Plugin-style extensibility**: adding new tasks only requires new module + WaveMix parameters.
- **Layered Abstraction**:
- Data layer (loaders, augmentations)
- Model layer (initial conv → WaveMix blocks → head)
- Training/Evaluation layer (loss, optimizer, metrics)
- Persistence layer (checkpoint saving/loading)

##### Relevant Technologies and Frameworks
- Python 3.x, PyTorch
- 2D Discrete Wavelet Transform (via PyWavelets or custom implementations)
- Packaging: setuptools (setup.py)

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "User Applications / Scripts"
        ImgClassScripts["Image_Classification Scripts"]:::scripts
        SegScripts["Semantic_Segmentation Scripts"]:::scripts
        SRscripts["Super-Resolution Scripts"]:::scripts
    end

    subgraph "Core Library (wavemix package)"
        CorePkg["wavemix/__init__.py"]:::core
        ClassMod["classification.py"]:::core
        SegMod["SemSegment.py"]:::core
        SISRMod["sisr.py"]:::core
        subgraph "WaveMix Building Blocks"
            WaveMixBlock["WaveMix Block\n(2D-DWT→MLP→iDWT)"]:::core
        end
        subgraph "Utilities"
            Utils["Initial Conv, Upsample, MLP"]:::core
        end
    end

    subgraph Data_Layer
        DataSrc["Datasets & Preprocessing"]:::data
    end

    subgraph External_Dependencies
        Torch["PyTorch & torchvision"]:::external
    end

    WeightsStore["Saved_weights (Checkpoints)"]:::datastore

    Outputs["Inference Outputs & Metrics"]:::output

    subgraph "Project Metadata & Packaging"
        Setup["setup.py"]:::meta
        Readme["README.md"]:::meta
        License["LICENSE"]:::meta
    end

    %% Data flow
    DataSrc -->|images| ImgClassScripts
    DataSrc -->|images| SegScripts
    DataSrc -->|images| SRscripts

    %% Script imports
    ImgClassScripts -->|imports| CorePkg
    SegScripts -->|imports| CorePkg
    SRscripts -->|imports| CorePkg

    %% Core uses components
    CorePkg --> WaveMixBlock
    CorePkg --> Utils
    CorePkg --> Torch
    WaveMixBlock --> Torch
    Utils --> Torch

    %% Training and saving
    ImgClassScripts -->|trains| ClassMod
    SegScripts -->|trains| SegMod
    SRscripts -->|trains| SISRMod

    ClassMod -->|checkpoints| WeightsStore
    SegMod -->|checkpoints| WeightsStore
    SISRMod -->|checkpoints| WeightsStore

    %% Inference
    WeightsStore -->|loads| ClassMod
    WeightsStore -->|loads| SegMod
    WeightsStore -->|loads| SISRMod

    ClassMod -->|predictions| Outputs
    SegMod -->|predictions| Outputs
    SISRMod -->|predictions| Outputs

    %% Metadata
    Setup --- Readme
    Readme --- License

    %% Click events
    click ImgClassScripts "https://github.com/pranavphoenix/wavemix/tree/main/Image_Classification/"
    click SegScripts "https://github.com/pranavphoenix/wavemix/tree/main/Semantic_Segmentation/"
    click SRscripts "https://github.com/pranavphoenix/wavemix/tree/main/Image_Super_Resolution/"
    click CorePkg "https://github.com/pranavphoenix/wavemix/blob/main/wavemix/__init__.py"
    click ClassMod "https://github.com/pranavphoenix/wavemix/blob/main/wavemix/classification.py"
    click SegMod "https://github.com/pranavphoenix/wavemix/blob/main/wavemix/SemSegment.py"
    click SISRMod "https://github.com/pranavphoenix/wavemix/blob/main/wavemix/sisr.py"
    click WeightsStore "https://github.com/pranavphoenix/wavemix/tree/main/Saved_weights/"
    click Setup "https://github.com/pranavphoenix/wavemix/blob/main/setup.py"
    click Readme "https://github.com/pranavphoenix/wavemix/blob/main/README.md"
    click License "https://github.com/pranavphoenix/wavemix/tree/main/LICENSE"

    %% Styles
    classDef scripts fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef data fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#fbf,stroke:#333,stroke-width:1px
    classDef datastore fill:#ffb,stroke:#333,stroke-width:1px
    classDef output fill:#fbb,stroke:#333,stroke-width:1px
    classDef meta fill:#ddd,stroke:#333,stroke-width:1px
```
