How jachansantiago/mode_guidance works
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.