# jachansantiago/mode_guidance architecture

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

- Interactive diagram: https://gitdiagram.com/jachansantiago/mode_guidance
- Repository: https://github.com/jachansantiago/mode_guidance

## Overview

##### Project type and purpose
- This is an open-source research tool (MGD³) for dataset distillation that leverages pre-trained diffusion models. It provides scripts and Python modules to discover data modes, guide diffusion sampling toward those modes, generate synthetic datasets, and evaluate them.

##### File structure
Top-level directories and files:
- diffusion/        – core diffusion functions (utils, Gaussian diffusion, scheduling, timestep sampler)
- misc/             – utility scripts and class lists for datasets (class indices, reproducibility, TSNE plotting helpers)
- train_models/     – definitions of network architectures (ConvNet, ResNet variants, DenseNet)
- scripts/          – shell wrappers for dataset setup and full experiments (ImageNette, ImageNet subsets)
Other key files:
- download.py       – data downloader
- data.py           – dataset loader and preprocessor
- sample.py         – generic sampling pipeline
- sample_mode_guidance.py – sampling with mode guidance
- train.py / train_dit.py – training routines for distilled datasets
- finetune_dit.py / finetuning.py – optional fine-tuning scripts
- tsne_plots.py     – TSNE visualization of modes and distilled samples
- requirements.txt  – external dependencies

##### README for additional insights
- Three main stages: Mode Discovery, Mode Guidance, Stop Guidance
- No fine-tuning of diffusion models → uses pre-trained backbones
- Scripts target large-scale datasets (ImageNette, ImageNet-1K)

##### Main components
A. CLI Layer (entry points):
- scripts/*.sh, train.py, sample.py, finetune*.py
B. Data Acquisition & Preprocessing:
- download.py → data.py → misc/utils.py
C. Mode Discovery Module:
- diffusion/diffusion_utils.py + misc/reproduce.py + tsne_plots.py
D. Diffusion Engine:
- diffusion/gaussian_diffusion.py + respace.py + timestep_sampler.py
E. Mode Guidance Controller:
- sample_mode_guidance.py (injects mode embeddings into diffusion steps)
F. Stop Guidance Controller:
- diffusion_utils (stop guidance logic embedded here)
G. Model Training & Evaluation:
- train_models/ (architectures)
- train.py / train_dit.py
- finetune_dit.py / finetuning.py
H. Output & Visualization:
- synthetic dataset files
- tsne_plots.py
- logs, metrics

##### Relationships and data flows
- User invokes a shell script or Python CLI → loads parameters (argument.py)
- Data Acquisition → raw images → Preprocessing pipeline → Mode Discovery.
- Mode Discovery outputs cluster centroids/modes → passed to Mode Guidance Controller
- Diffusion Engine receives guidance signals + pre-trained model weights → generates synthetic samples
- Samples → save to disk → optionally used by Model Training module
- Training module loads synthetic samples + train_models architectures → produces evaluation metrics
- Visualization (tsne_plots.py) reads modes & samples → generates TSNE visualizations

##### Architectural patterns & design principles
- Modular pipeline: each stage is encapsulated in its own module/package
- CLI-driven orchestration: entry points are thin scripts that wire modules together
- Separation of concerns: diffusion logic vs. guidance vs. model training vs. data utilities
- Extensibility points:
- New diffusion schedulers (drop-in under diffusion/)
- New model architectures in train_models/
- New datasets via scripts/ + misc/class_*.txt

##### Detailed capture of essential elements
- Pre-trained diffusion model as an external dependency (e.g., “checkpoint.pth” from Hugging Face).
- Argument parsing in argument.py as the glue for all CLIs.
- Misc/ as config & utilities that feed into multiple steps (data lists, reproducibility seeds).
- Train_models/ under a “Model Zoo” block to illustrate extensibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer" 
        direction TB
        CLI_scripts["Shell Scripts"]:::cli
        CLI_train["train.py"]:::cli
        CLI_sample["sample.py"]:::cli
        CLI_finetune1["finetune_dit.py"]:::cli
        CLI_finetune2["finetuning.py"]:::cli
        CLI_arg["argument.py"]:::cli
    end

    %% Data & Preprocessing Layer
    subgraph "Data Acquisition & Preprocessing" 
        direction TB
        DL["download.py"]:::data
        DLP["data.py"]:::data
        UTILS["misc/utils.py"]:::data
    end

    %% Mode Discovery Layer
    subgraph "Mode Discovery Module" 
        direction TB
        DU["diffusion/diffusion_utils.py"]:::guide
        REP["misc/reproduce.py"]:::data
        TSNE1["tsne_plots.py"]:::viz
    end

    %% Diffusion & Guidance
    subgraph "Diffusion & Guidance" 
        direction TB
        GD["diffusion/gaussian_diffusion.py"]:::guide
        RS["diffusion/respace.py"]:::guide
        TS["diffusion/timestep_sampler.py"]:::guide
        MG["sample_mode_guidance.py"]:::guide
    end

    %% Model Training & Evaluation
    subgraph "Model Training & Evaluation" 
        direction TB
        CONV["train_models/convnet.py"]:::model
        RES["train_models/resnet.py"]:::model
        RESA["train_models/resnet_ap.py"]:::model
        DNS["train_models/densenet_cifar.py"]:::model
        TD["train_dit.py"]:::model
        TBASE["train.py"]:::model
        FT1["finetune_dit.py"]:::model
        FT2["finetuning.py"]:::model
    end

    %% Output & Visualization
    subgraph "Output & Visualization"
        direction TB
        SYN["Synthetic Dataset"]:::data_store
        METR["Metrics & Logs"]:::data_store
        TSNE2["tsne_plots.py"]:::viz
    end

    %% External
    PRE["checkpoint.pth"]:::external

    %% Data Stores
    subgraph "Data Stores" 
        direction TB
        RAW["Raw Images"]:::data_store
        MODES["Modes (modes.json)"]:::data_store
    end

    %% Connections
    CLI_scripts -->|uses| CLI_arg
    CLI_train -->|uses| CLI_arg
    CLI_sample -->|uses| CLI_arg
    CLI_finetune1 -->|uses| CLI_arg
    CLI_finetune2 -->|uses| CLI_arg

    CLI_sample -->|download command| DL
    DL -->|raw images| RAW
    RAW -->|load/preprocess| DLP
    DLP -->|utilities| UTILS
    DLP -->|preprocessed data| DU

    DU -->|compute modes| MODES
    MODES --> DU
    DU -->|visualize modes| TSNE1

    MODES -->|guidance| MG
    PRE -->|model weights| GD
    MG -->|guided signals| GD
    GD -->|schedules| RS
    RS -->|timesteps| TS
    GD -->|samples| SYN

    SYN -->|train input| CONV
    SYN -->|train input| RES
    SYN -->|train input| RESA
    SYN -->|train input| DNS
    CONV -->|train| TBASE
    RES -->|train| TBASE
    RESA -->|train| TBASE
    DNS -->|train| TBASE
    TBASE -->|outputs metrics| METR

    SYN -->|fine-tune| FT1
    FT1 -->|outputs metrics| METR
    SYN -->|fine-tune| FT2
    FT2 -->|outputs metrics| METR

    MODES -->|visualize| TSNE2
    SYN -->|visualize| TSNE2

    %% Click Events
    click CLI_scripts "https://github.com/jachansantiago/mode_guidance/blob/main/scripts/imagenet100.sh"
    click CLI_scripts "https://github.com/jachansantiago/mode_guidance/blob/main/scripts/nette.sh"
    click CLI_train "https://github.com/jachansantiago/mode_guidance/blob/main/train.py"
    click CLI_sample "https://github.com/jachansantiago/mode_guidance/blob/main/sample.py"
    click CLI_finetune1 "https://github.com/jachansantiago/mode_guidance/blob/main/finetune_dit.py"
    click CLI_finetune2 "https://github.com/jachansantiago/mode_guidance/blob/main/finetuning.py"
    click CLI_arg "https://github.com/jachansantiago/mode_guidance/blob/main/argument.py"
    click DL "https://github.com/jachansantiago/mode_guidance/blob/main/download.py"
    click DLP "https://github.com/jachansantiago/mode_guidance/blob/main/data.py"
    click UTILS "https://github.com/jachansantiago/mode_guidance/blob/main/misc/utils.py"
    click DU "https://github.com/jachansantiago/mode_guidance/blob/main/diffusion/diffusion_utils.py"
    click REP "https://github.com/jachansantiago/mode_guidance/blob/main/misc/reproduce.py"
    click TSNE1 "https://github.com/jachansantiago/mode_guidance/blob/main/tsne_plots.py"
    click GD "https://github.com/jachansantiago/mode_guidance/blob/main/diffusion/gaussian_diffusion.py"
    click RS "https://github.com/jachansantiago/mode_guidance/blob/main/diffusion/respace.py"
    click TS "https://github.com/jachansantiago/mode_guidance/blob/main/diffusion/timestep_sampler.py"
    click MG "https://github.com/jachansantiago/mode_guidance/blob/main/sample_mode_guidance.py"
    click CONV "https://github.com/jachansantiago/mode_guidance/blob/main/train_models/convnet.py"
    click RES "https://github.com/jachansantiago/mode_guidance/blob/main/train_models/resnet.py"
    click RESA "https://github.com/jachansantiago/mode_guidance/blob/main/train_models/resnet_ap.py"
    click DNS "https://github.com/jachansantiago/mode_guidance/blob/main/train_models/densenet_cifar.py"
    click TD "https://github.com/jachansantiago/mode_guidance/blob/main/train_dit.py"
    click TBASE "https://github.com/jachansantiago/mode_guidance/blob/main/train.py"
    click FT1 "https://github.com/jachansantiago/mode_guidance/blob/main/finetune_dit.py"
    click FT2 "https://github.com/jachansantiago/mode_guidance/blob/main/finetuning.py"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef data fill:#bbf,stroke:#333,stroke-width:1px
    classDef guide fill:#bfb,stroke:#333,stroke-width:1px
    classDef model fill:#fb8,stroke:#333,stroke-width:1px
    classDef viz fill:#ccc,stroke:#333,stroke-width:1px
    classDef data_store fill:#eef,stroke:#333,stroke-width:1px
    classDef external fill:#fff,stroke:#f00,stroke-width:2px,stroke-dasharray: 5 5
```
