# atsumiyai/locoop architecture

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

- Interactive diagram: https://gitdiagram.com/atsumiyai/locoop
- Repository: https://github.com/atsumiyai/locoop

## Overview

##### Project type and purpose
- This is a research‐oriented PyTorch codebase implementing “LoCoOp: Few‐Shot Out‐of‐Distribution Detection via Prompt Learning.”

##### File structure
- Top‐level modules:
- clip_w_local/ – CLIP wrapper, tokenizer, vocabulary, model definitions.
- configs/ – YAML files defining datasets and trainer (LoCoOp) hyperparameters.
- datasets/ – custom DataLoader wrappers for in‐distribution datasets (ImageNet, Oxford Pets).
- trainers/ – the LoCoOp trainer logic (train loop, OOD regularization).
- utils/ – helper functions for detection, training/evaluation, plotting.
- scripts/locoop/ – shell scripts to launch training, evaluation, and visualization with specific arguments.
- train.py, eval_ood_detection.py, demo_visualization.py – entry‐point Python scripts.
- figure/ – stored architecture and visualization PNGs.
- External dependencies and build artifacts: requirements.txt, .gitignore, LICENSE.

##### README for additional insights
- The paper’s high‐level architecture (figure/framework.png) shows how CLIP local features are used for OOD regularization via prompt learning.
- Training, evaluation, and visualization commands are driven by shell scripts reading from configs.

a. Main components
1. Data Storage
- Raw data folder (`data/imagenet`, `data/iNaturalist`, etc.)
- YAML dataset configs under configs/datasets
2. Configuration Manager
- YAML files for data and trainer under configs/
- A loader in train.py and eval scripts that parses these configs
3. Preprocessing & Tokenization
- simple_tokenizer.py & BPE vocab
- Data augmentation / transforms (in Dassl.pytorch)
4. CLIP Wrapper
- clip.py and model.py in clip_w_local/ – load pre‐trained CLIP, expose local features
5. Prompt Learning Module
- trainers/locoop.py – implements LoCoOp prompt parameterization and OOD regularization
6. Trainer
- train.py – orchestrates dataset loader, CLIP wrapper, LoCoOp trainer, optimizer, logging
7. Evaluation
- eval_ood_detection.py – loads checkpoint, runs MCM or GL‑MCM inference on OOD datasets
8. Visualization
- demo_visualization.py – extracts and plots OOD regions using plot_util.py
9. External Services & Dependencies
- Dassl.pytorch (for backbone data transforms and base Trainer classes)
- OpenAI CLIP library
- MCM codebase for OOD score computation
b. Relationships and interactions
- Trainer ↔ Configuration Manager (reads hyperparams)
- Trainer → Checkpoint Writer → Stored Models
- Evaluation script reads Stored Models + Data Storage → computes OOD metrics via MCM
- Visualization script reads Stored Models + an image path → outputs attention/heatmaps
- All Python entry‐points invoked via shell scripts in scripts/locoop
c. Architectural patterns & design principles
- Config‐driven pipeline (YAML configs decouple hyperparameters from code)
- Modular separation: data, model definition, training logic, evaluation, visualization
- Wrapper pattern: clip_w_local module abstracts CLIP internals and local feature extraction
- Reuse of external toolbox (Dassl) for common functionality, promoting DRY
d. Key technologies, frameworks, libraries
- PyTorch 1.8.1
- Dassl.pytorch for dataset handling and base training loops
- OpenAI CLIP for vision‐language backbone
- MCM (and optional GL‐MCM) for OOD score computation
- YAML for configuration management
- Shell scripts for reproducible experiment commands

##### Detail without over‐fragmentation
- Logical component above.
- Avoid splitting too finely (e.g., every single Python file), but ensure each major responsibility is shown—data ingestion, model definition, training loop, evaluation, visualization, and configuration.
- Both static structure (modules and directories) and dynamic flow (training and inference pipelines).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Storage
    subgraph "Data Storage"
        DS["Raw Data (data/)"]:::data
    end

    %% Configuration Manager
    subgraph "Configuration Manager"
        CFG1["Dataset YAMLs"]:::code
        CFG2["Trainer YAMLs"]:::code
    end

    %% Preprocessing & Tokenization
    subgraph "Preprocessing & Tokenization"
        TOK["simple_tokenizer.py"]:::code
        VOCAB["bpe_simple_vocab_16e6.txt.gz"]:::code
    end

    %% CLIP Wrapper
    subgraph "CLIP Wrapper"
        CLIP_PY["clip.py"]:::code
        MODEL_PY["model.py"]:::code
    end

    %% Prompt Learning Module
    subgraph "Prompt Learning Module"
        LOCOOP["locoop.py"]:::code
    end

    %% Trainer Orchestration
    subgraph "Trainer Entry Point"
        TRAIN["train.py"]:::script
        UTIL_TRAIN["train_eval_util.py"]:::code
    end

    %% Evaluation Component
    subgraph "Evaluation Component"
        EVAL["eval_ood_detection.py"]:::script
        UTIL_DET["detection_util.py"]:::code
    end

    %% Visualization Component
    subgraph "Visualization Component"
        DEMO["demo_visualization.py"]:::script
        PLOT_UTIL["plot_util.py"]:::code
        DEMO_SH["demo_visualization.sh"]:::script
    end

    %% Dataset Loaders
    subgraph "Dataset Loaders"
        IMAGENET["imagenet.py"]:::code
        PETS["oxford_pets.py"]:::code
    end

    %% Experiment Launch Scripts
    subgraph "Experiment Launch Scripts"
        TRAIN_SH["train.sh"]:::script
        EVAL_SH["eval.sh"]:::script
    end

    %% Figures & Diagrams
    FIG["figure/"]:::fig

    %% External Dependencies
    subgraph "External Dependencies"
        DASSL["Dassl.pytorch"]:::external
        CLIP_LIB["OpenAI CLIP"]:::external
        MCM["MCM/GL-MCM"]:::external
    end

    %% Data Flow & Relationships
    DS --> IMAGENET
    DS --> PETS
    IMAGENET --> TRAIN
    PETS --> TRAIN

    CFG1 --> TRAIN
    CFG2 --> TRAIN

    TRAIN --> UTIL_TRAIN
    UTIL_TRAIN --> LOCOOP
    LOCOOP --> CLIP_PY
    LOCOOP --> MODEL_PY
    TRAIN --> UTIL_TRAIN
    TRAIN --> CFG1
    TRAIN --> CFG2

    TOK --> TRAIN
    VOCAB --> TRAIN

    TRAIN -->|"writes checkpoint"| CKPT["Stored Models"]:::data

    CKPT --> EVAL
    DS --> EVAL
    EVAL --> UTIL_DET
    UTIL_DET --> MCM

    CKPT --> DEMO
    DEMO --> PLOT_UTIL
    DEMO_SH --> DEMO

    TRAIN_SH --> TRAIN
    EVAL_SH --> EVAL

    FIG --> TRAIN
    FIG --> DEMO

    TRAIN --> DASSL
    LOCOOP --> DASSL
    LOCOOP --> CLIP_LIB

    %% Click Events
    click CLIP_PY "https://github.com/atsumiyai/locoop/blob/master/clip_w_local/clip.py"
    click MODEL_PY "https://github.com/atsumiyai/locoop/blob/master/clip_w_local/model.py"
    click TOK "https://github.com/atsumiyai/locoop/blob/master/clip_w_local/simple_tokenizer.py"
    click VOCAB "https://github.com/atsumiyai/locoop/blob/master/clip_w_local/bpe_simple_vocab_16e6.txt.gz"
    click CFG1 "https://github.com/atsumiyai/locoop/tree/master/configs/datasets/"
    click CFG2 "https://github.com/atsumiyai/locoop/tree/master/configs/trainers/LoCoOp/"
    click IMAGENET "https://github.com/atsumiyai/locoop/blob/master/datasets/imagenet.py"
    click PETS "https://github.com/atsumiyai/locoop/blob/master/datasets/oxford_pets.py"
    click LOCOOP "https://github.com/atsumiyai/locoop/blob/master/trainers/locoop.py"
    click TRAIN "https://github.com/atsumiyai/locoop/blob/master/train.py"
    click UTIL_TRAIN "https://github.com/atsumiyai/locoop/blob/master/utils/train_eval_util.py"
    click EVAL "https://github.com/atsumiyai/locoop/blob/master/eval_ood_detection.py"
    click UTIL_DET "https://github.com/atsumiyai/locoop/blob/master/utils/detection_util.py"
    click DEMO "https://github.com/atsumiyai/locoop/blob/master/demo_visualization.py"
    click PLOT_UTIL "https://github.com/atsumiyai/locoop/blob/master/utils/plot_util.py"
    click DEMO_SH "https://github.com/atsumiyai/locoop/blob/master/scripts/locoop/demo_visualization.sh"
    click TRAIN_SH "https://github.com/atsumiyai/locoop/blob/master/scripts/locoop/train.sh"
    click EVAL_SH "https://github.com/atsumiyai/locoop/blob/master/scripts/locoop/eval.sh"
    click FIG "https://github.com/atsumiyai/locoop/tree/master/figure/"

    %% Styles
    classDef data fill:#D6E9FE,stroke:#3E8EED,stroke-width:1px;
    classDef code fill:#E6F4EA,stroke:#34A853,stroke-width:1px;
    classDef script fill:#FFF4E5,stroke:#FBBD08,stroke-width:1px;
    classDef external fill:#FFE8E8,stroke:#EA4335,stroke-dasharray: 5 5,stroke-width:1px;
    classDef fig fill:#F0F0F0,stroke:#888888,stroke-width:1px;
```
