# claudiashu/sonnet architecture

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

- Interactive diagram: https://gitdiagram.com/claudiashu/sonnet
- Repository: https://github.com/claudiashu/sonnet

## Overview

##### Main Components
- CLI & Config Manager
- Entry point: `scripts/run_experiment.py`
- Hydra + YAML configs under `configs/`
- Dataset Layer
- Local: `datasets/weatherbench/*.csv`
- External: Darts API (ELEC, ENER, ETTh)
- Configs: `configs/dataset/...`
- Data Loader
- `sonnet/data/weatherDataloader.py`
- `sonnet/data/dartsDataloader.py`
- Model Zoo
- Core: `sonnet/mts_model/models/Sonnet.py`
- Baselines: `sonnet/baselines/models/*.py`
- Shared layers: `sonnet/baselines/layers/*.py`
- Lightning Engine
- Modules: `sonnet/lightning/lightning_module.py`
- Naive baselines: `sonnet/lightning/lightning_naive.py`
- Training & validation loops via PyTorch Lightning
- Utilities
- Config loaders: `sonnet/data_config.py`, `sonnet/model_config.py`
- Metrics: `sonnet/utils/metrics.py`
- Misc: `sonnet/utils/utils.py`, masking, RevIN, etc.

##### Relationships and Data Flow
1. User invokes the CLI
→ Hydra reads `configs/exp/*.yaml`, `configs/model/*.yaml`, `configs/dataset/...`
2. Config manager instantiates
→ Data Loader (weather or Darts)
→ Model (Sonnet or one of the baselines)
→ LightningModule
3. PyTorch Lightning Trainer
→ Feeds batches from Data Loader
→ Calls forward pass of selected Model
→ Computes loss & metrics via `sonnet/utils/metrics.py`
4. Checkpointing & Logging
→ TensorBoard / Hydra outputs
5. Post‐processing
→ Scripts under `scripts/` can generate run‐sweep files (`generate_runs.sh`)

##### Architectural Patterns & Design Principles
- Modular “Model Zoo” for easy swap‐in of baselines vs Sonnet
- Config‐driven execution (Hydra) for reproducibility
- Separation of concerns: data loading, model definition, training loop
- Extensibility: add new datasets by placing YAML in `configs/dataset`, implement new DataLoader

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Config & CLI"
        CLI["CLI & Config Manager"]:::config
        Hydra["Hydra Configs"]:::config
    end

    subgraph "Dataset Layer"
        Local["Local CSVs"]:::data
        External["Darts API List"]:::data
    end

    subgraph "DataLoader"
        WBLoader["WeatherBench Loader"]:::data
        DartsLoader["Darts Loader"]:::data
    end

    subgraph "Model Zoo"
        SonnetModel["Core Sonnet Model"]:::model
        Baselines["Baselines Models"]:::model
        Layers["Shared Layers"]:::model
        RevIN["RevIN Layer"]:::model
    end

    subgraph "Lightning Engine"
        LM["LightningModule"]:::compute
        Naive["Naive Lightning"]:::compute
    end

    subgraph "Trainer & Outputs"
        Trainer["PyTorch Lightning Trainer"]:::compute
        Outputs["Outputs/Logs"]:::output
    end

    subgraph "Utilities"
        DataConfig["Data Config Loader"]:::util
        ModelConfig["Model Config Loader"]:::util
        Metrics["Metrics Utilities"]:::util
        Utils["Misc Utilities"]:::util
        Masking["Masking Utilities"]:::util
    end

    CLI -->|"reads"| Hydra
    Hydra -->|"provides configs to"| Local
    Hydra -->|"provides configs to"| External
    Local -->|"loads data"| WBLoader
    External -->|"loads data"| DartsLoader
    Hydra -->|"provides configs to"| SonnetModel
    Hydra -->|"provides configs to"| Baselines
    WBLoader -->|"batches"| SonnetModel
    DartsLoader -->|"batches"| SonnetModel
    SonnetModel -->|"instantiates"| LM
    Baselines -->|"instantiates"| LM
    Layers -.-> LM
    RevIN -.-> LM
    Naive -->|"instantiates"| LM
    LM -->|"forward"| Trainer
    Trainer -->|"logs metrics"| Outputs
    DataConfig -->|"loads configs"| LM
    ModelConfig -->|"loads configs"| LM
    Metrics -->|"computes metrics for"| Trainer
    Utils -.-> LM
    Masking -.-> LM

    click CLI "https://github.com/claudiashu/sonnet/blob/main/scripts/run_experiment.py"
    click Hydra "https://github.com/claudiashu/sonnet/tree/main/configs/"
    click Local "https://github.com/claudiashu/sonnet/blob/main/datasets/weatherbench/*.csv"
    click External "https://github.com/claudiashu/sonnet/blob/main/sonnet/data/dataset_list_darts.py"
    click WBLoader "https://github.com/claudiashu/sonnet/blob/main/sonnet/data/weatherDataloader.py"
    click DartsLoader "https://github.com/claudiashu/sonnet/blob/main/sonnet/data/dartsDataloader.py"
    click SonnetModel "https://github.com/claudiashu/sonnet/blob/main/sonnet/mts_model/models/Sonnet.py"
    click Baselines "https://github.com/claudiashu/sonnet/blob/main/sonnet/baselines/models/*.py"
    click Layers "https://github.com/claudiashu/sonnet/blob/main/sonnet/baselines/layers/*.py"
    click RevIN "https://github.com/claudiashu/sonnet/blob/main/sonnet/mts_model/layers/RevIN.py"
    click LM "https://github.com/claudiashu/sonnet/blob/main/sonnet/lightning/lightning_module.py"
    click Naive "https://github.com/claudiashu/sonnet/blob/main/sonnet/lightning/lightning_naive.py"
    click DataConfig "https://github.com/claudiashu/sonnet/blob/main/sonnet/data_config.py"
    click ModelConfig "https://github.com/claudiashu/sonnet/blob/main/sonnet/model_config.py"
    click Metrics "https://github.com/claudiashu/sonnet/blob/main/sonnet/utils/metrics.py"
    click Utils "https://github.com/claudiashu/sonnet/blob/main/sonnet/utils/utils.py"
    click Masking "https://github.com/claudiashu/sonnet/blob/main/sonnet/utils/masking.py"

    classDef config fill:#f9d5a2,stroke:#333,stroke-width:1px
    classDef data fill:#a2dff9,stroke:#333,stroke-width:1px
    classDef model fill:#a2f9a2,stroke:#333,stroke-width:1px
    classDef compute fill:#d5a2f9,stroke:#333,stroke-width:1px
    classDef util fill:#cfcfcf,stroke:#333,stroke-width:1px
    classDef output fill:#f9a2a2,stroke:#333,stroke-width:1px
```
