# edwinkim3069/warp-cifsl architecture

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

- Interactive diagram: https://gitdiagram.com/edwinkim3069/warp-cifsl
- Repository: https://github.com/edwinkim3069/warp-cifsl

## Overview

##### Project type and purpose
- This is a research‐oriented Python codebase implementing “Warping the Space: Weight Space Rotation (WaRP) for Class‐Incremental Few‐Shot Learning.”
- It provides data indexing, dataloaders, model definitions, training scripts, and experiment orchestration for sequential few‐shot learning on CIFAR100, MiniImagenet, and CUB200.

##### File structure
- Top‐level:
- data/ — raw datasets plus session‐specific index lists
- dataloader/ — dataset wrappers and custom sampler
- models/ — network architectures, base trainer, weight‐rotation modules
- script/ — shell scripts for end‐to‐end runs
- train.py — main training entrypoint (pretraining & incremental sessions)
- utils.py — miscellaneous helpers
- LICENSE, README.md
- Patterns:
- Modular separation: data ingestion, model logic, training orchestration
- Trainer abstraction in models/base/fscil_trainer.py
- Configuration via command‐line flags in train.py and bash scripts

##### README for additional insights
- Describes workflow: automatic download for CIFAR100, manual download + extraction for others
- Two phases:
a) Pretraining on base classes
b) Incremental sessions with WaRP or prototype baseline
- Checkpoints are stored under a “checkpoint/…” structure and loaded as input to incremental runs

a. Main components
1. Data Storage
– “data/” directory holding raw images and session index files
2. Data Loader Layer
– dataloader/data_utils.py: reads index lists & raw files
– dataloader/*/*.py: Dataset subclasses for each benchmark
– dataloader/sampler.py: custom sampler for few‐shot batches
3. Model Layer
– models/base: Network, Trainer abstraction, helper routines
– models/resnet*_*.py, rotated_modules.py, switch_module.py: core architectures & WaRP logic
4. Training Orchestrator
– train.py: CLI interface handling pretrain vs. incremental mode, argument parsing
– script/*.sh: bash wrappers invoking train.py with dataset‐specific flags
5. Checkpoint & Logging
– checkpoint/… folder (created at runtime) storing model .pth files per session
6. External Services
– PyTorch, torchvision
– gdown for Google Drive downloads
– Shell environment (bash)

b. Relationships & data flow
1. Scripts kick off train.py
2. train.py invokes Data Loader Layer → yields DataLoader objects
3. DataLoader feeds batches to Model Layer
4. Model Layer (via fscil_trainer) runs forward/backward, applying WaRP transformations
5. Trainer writes checkpoints to disk; optional logs to stdout or TensorBoard
6. Subsequent incremental sessions load previous checkpoint, repeat steps 2–5

c. Architectural patterns & design principles
- Modular separation of concerns
- Trainer abstraction for base vs. incremental loops
- Configurable via CLI flags, enabling reproducibility
- Weight‐space rotation encapsulated in dedicated modules

d. Key technologies
- Python 3.x
- PyTorch deep learning framework
- Shell scripting (bash) for experiment pipelines

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Storage
    DS["Data Storage"]:::data
    DS -->|reads index lists| DL

    %% Data Loader Layer
    subgraph "Data Loader Layer"
        direction TB
        DU["Utilities (data_utils.py)"]:::code
        DSAM["Sampler (sampler.py)"]:::code
        DCF["CIFAR100 Dataset (cifar.py)"]:::code
        DMI["MiniImagenet Dataset (miniimagenet.py)"]:::code
        DCB["CUB200 Dataset (cub200.py)"]:::code
    end
    DL[/"DataLoader Objects"/]:::code
    DU --> DL
    DSAM --> DL
    DCF --> DL
    DMI --> DL
    DCB --> DL

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        MN["Base Network API"]:::code
        MT["Trainer Abstraction"]:::code
        MB["Base Classes & Helpers"]:::code
        R18C["ResNet-18 CIFAR Variant"]:::code
        R20C["ResNet-20 CIFAR Variant"]:::code
        R18E["ResNet-18 Encoder"]:::code
        WRM["Weight-Space Rotation Modules"]:::code
        SM["Switch Module for WaRP Routing"]:::code
        MU["General Utilities"]:::code
    end
    DL -->|feeds batches| MN
    MN --> MT
    MB --> MT
    R18C --> MT
    R20C --> MT
    R18E --> MT
    WRM --> MT
    SM --> MT
    MU --> MT

    %% Training Orchestrator
    subgraph "Training Orchestrator"
        direction TB
        TS["Main Script (train.py)"]:::orchestrator
        S1["CIFAR100 Runner"]:::orchestrator
        S2["MiniImagenet Runner"]:::orchestrator
        S3["CUB200 Runner"]:::orchestrator
    end
    S1 --> TS
    S2 --> TS
    S3 --> TS
    TS --> DL
    TS --> MN

    %% Checkpoint & Logging
    CP["Checkpoint Store"]:::checkpoint
    MT -->|writes .pth files| CP
    CP -->|loads previous| TS

    %% Click Events
    click DS "https://github.com/edwinkim3069/warp-cifsl/tree/main/data/index_list"
    click DU "https://github.com/edwinkim3069/warp-cifsl/blob/main/dataloader/data_utils.py"
    click DSAM "https://github.com/edwinkim3069/warp-cifsl/blob/main/dataloader/sampler.py"
    click DCF "https://github.com/edwinkim3069/warp-cifsl/blob/main/dataloader/cifar100/cifar.py"
    click DMI "https://github.com/edwinkim3069/warp-cifsl/blob/main/dataloader/miniimagenet/miniimagenet.py"
    click DCB "https://github.com/edwinkim3069/warp-cifsl/blob/main/dataloader/cub200/cub200.py"
    click MN "https://github.com/edwinkim3069/warp-cifsl/blob/main/models/base/Network.py"
    click MT "https://github.com/edwinkim3069/warp-cifsl/blob/main/models/base/fscil_trainer.py"
    click MB "https://github.com/edwinkim3069/warp-cifsl/blob/main/models/base/base.py"
    click MB "https://github.com/edwinkim3069/warp-cifsl/blob/main/models/base/helper.py"
    click R18C "https://github.com/edwinkim3069/warp-cifsl/blob/main/models/resnet18_cifar.py"
    click R20C "https://github.com/edwinkim3069/warp-cifsl/blob/main/models/resnet20_cifar.py"
    click R18E "https://github.com/edwinkim3069/warp-cifsl/blob/main/models/resnet18_encoder.py"
    click WRM "https://github.com/edwinkim3069/warp-cifsl/blob/main/models/rotated_modules.py"
    click SM "https://github.com/edwinkim3069/warp-cifsl/blob/main/models/switch_module.py"
    click MU "https://github.com/edwinkim3069/warp-cifsl/blob/main/models/utils.py"
    click TS "https://github.com/edwinkim3069/warp-cifsl/blob/main/train.py"
    click S1 "https://github.com/edwinkim3069/warp-cifsl/blob/main/script/run_cifar100.sh"
    click S2 "https://github.com/edwinkim3069/warp-cifsl/blob/main/script/run_mini-imagenet.sh"
    click S3 "https://github.com/edwinkim3069/warp-cifsl/blob/main/script/run_cub200.sh"
    click UT "https://github.com/edwinkim3069/warp-cifsl/blob/main/utils.py"

    %% Styles
    classDef data fill:#cce5ff,stroke:#003366,stroke-width:1px,shape:cylinder
    classDef code fill:#ccffcc,stroke:#336633,stroke-width:1px,shape:rect
    classDef orchestrator fill:#ffebcc,stroke:#994d00,stroke-width:1px,shape:roundrect
    classDef checkpoint fill:#e2e3e5,stroke:#6c757d,stroke-width:1px,shape:cylinder
```
