# keyang8/witt architecture

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

- Interactive diagram: https://gitdiagram.com/keyang8/witt
- Repository: https://github.com/keyang8/witt

## Overview

##### Project Type and Purpose
- This is a PyTorch‐based ML research pipeline implementing a Wireless Image Transmission Transformer (WITT).
- Core goal: train and evaluate an end‐to‐end semantic communication model (encoder → noisy channel → decoder) on image datasets under varying channel conditions.

##### File Structure
- data/
– datasets.py: defines PyTorch Dataset classes and data‐loading logic for DIV2K, CIFAR10, Kodak, etc.
- loss/
– distortion.py: implements distortion metrics (MSE, MS‐SSIM).
- net/
– encoder.py & decoder.py: Transformer‐based modules for encoding/decoding image latents.
– channel.py: simulates wireless channels (AWGN, Rayleigh).
– modules.py: spatial modulation module (scales latents by CSI).
– network.py: orchestrates encoder + channel + decoder into the full WITT model.
- train.py: CLI entry point for training and testing loops.
- utils.py: shared utilities (logging, checkpointing, metric computations).
- results/: holds evaluation outputs and visualization scripts.

##### Extract Key Architecture Details from README
- Model variations: WITT (with spatial modulation) and WITT_W/O (without).
- External building blocks: Swin Transformer backbone, BPG + LDPC or capacity‐achieving channel codes.
- CLI parameters select dataset, model variant, channel type, SNR settings, distortion metric.

##### Main Components and Interactions
a. Data Ingestion
– Input: image datasets (DIV2K, CIFAR10, Kodak, etc.)
– Loader: data/datasets.py → DataLoader → minibatches
b. Model Forward Pass
– Encoder (net/encoder.py): Swin‐based feature extraction → bottleneck representation
– Spatial Modulation (net/modules.py): scale by CSI if WITT variant
– Channel Simulator (net/channel.py): apply AWGN or Rayleigh noise
– Decoder (net/decoder.py): reconstruct image from noisy latents
c. Loss Computation
– Distortion (loss/distortion.py): MSE or MS‐SSIM between output and ground truth
d. Training Loop (train.py)
– Optimizer & scheduler → backpropagate loss → update network (net/network.py)
– Logging and checkpointing via utils.py
e. Evaluation & Results
– Run forward pass on test set → save metrics and visual comparisons in results/

##### Architectural Patterns & Design Principles
- Modular separation: data, model, loss, utilities, results
- Single‐entry CLI (train.py) controlling both train and test pipelines
- Clear plug‐in points: choose channel type, distortion metric, or model variant via flags
- Reusable building blocks: encoder/decoder follow same interface, channel module is swappable

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Entry
    TrainCLI["Training & Evaluation CLI\ntrain.py"]:::infra
    click TrainCLI "https://github.com/keyang8/witt/blob/main/train.py"

    %% Data Components
    subgraph "Data Layer"
        DatasetStore[(Datasets\nDIV2K, CIFAR10, Kodak)]:::data
        DataLoader["Data Loader\ndata/datasets.py"]:::data
        click DataLoader "https://github.com/keyang8/witt/blob/main/data/datasets.py"
    end

    %% Model Components
    subgraph "Model Pipeline"
        Encoder["Encoder\nnet/encoder.py"]:::model
        click Encoder "https://github.com/keyang8/witt/blob/main/net/encoder.py"
        SpatialMod["Spatial Modulation\nnet/modules.py"]:::model
        click SpatialMod "https://github.com/keyang8/witt/blob/main/net/modules.py"
        ChannelSim["Channel Simulator\nnet/channel.py"]:::model
        click ChannelSim "https://github.com/keyang8/witt/blob/main/net/channel.py"
        Decoder["Decoder\nnet/decoder.py"]:::model
        click Decoder "https://github.com/keyang8/witt/blob/main/net/decoder.py"
    end

    %% Orchestration
    Network["WITT Network Orchestration\nnet/network.py"]:::model
    click Network "https://github.com/keyang8/witt/blob/main/net/network.py"

    %% Loss and Training Infrastructure
    subgraph "Training Infrastructure"
        Loss["Distortion Loss\nloss/distortion.py"]:::infra
        click Loss "https://github.com/keyang8/witt/blob/main/loss/distortion.py"
        Optimizer["Optimizer & Scheduler"]:::infra
        Utils["Shared Utilities\nutils.py"]:::infra
        click Utils "https://github.com/keyang8/witt/blob/main/utils.py"
    end

    %% Storage and Results
    Checkpoints[(Checkpoints)]:::infra
    ResultsStore[(Results & Visualizations\nresults/)]:::data
    click ResultsStore "https://github.com/keyang8/witt/tree/main/results/"

    %% External Dependencies
    subgraph "External Dependencies"
        PyTorch["PyTorch"]:::external
        Swin["Swin Transformer\n(pre-trained)"]:::external
        ChannelCode["Channel Code Libraries\n(BPG, LDPC)"]:::external
    end

    %% Flow
    TrainCLI -->|config flags| DataLoader
    DataLoader -->|"image batch"| Encoder
    Encoder -->|"latent vector"| SpatialMod
    SpatialMod -->|"latent vector + CSI"| ChannelSim
    ChannelSim -->|"noisy latents"| Decoder
    Decoder -->|"reconstructed image"| Loss
    Loss -->|"loss value"| Optimizer
    Optimizer -->|update weights| Network
    Network -->|forward pass| Encoder

    %% Training Loop Storage
    Optimizer -->|checkpoint| Checkpoints
    Loss -->|metrics| ResultsStore
    ResultsStore -->|visualize| Utils

    %% CLI Control Flows
    TrainCLI -.->|--model-variant| SpatialMod
    TrainCLI -.->|--channel-type| ChannelSim
    TrainCLI -.->|--distortion-metric| Loss

    %% External Integrations
    Encoder ---> Swin
    SpatialMod ---> ChannelCode
    ChannelSim ---> ChannelCode
    Network ---> PyTorch
    DataLoader ---> PyTorch

    %% Styles
    classDef data fill:#e0ffe0,stroke:#2d8f2d
    classDef model fill:#e0f0ff,stroke:#2a6fb0
    classDef infra fill:#ffe0b3,stroke:#b07a2a
    classDef external fill:#dddddd,stroke:#888888,stroke-dasharray: 2 2
```
