How rose-stl-lab/dyffusion works
Project Type and Purpose
• This is a research-grade machine-learning library implementing the “DYffusion” spatiotemporal forecasting pipeline.
• It is not a web app or microservice; it’s an ML experiment platform built around PyTorch Lightning for training diffusion-based models on physical systems and SST data.
• Hydra handles configuration, PyTorch Lightning handles training loops, and Weights & Biases (W&B) or TensorBoard handle logging/checkpointing.
Key Architectural Components
a. CLI & Configuration Layer
• Entry points: run.py and train.py.
• Hydra (via pyproject.toml, setup.cfg, hydra imports) loads configs from src/configs/**.
• All experiment parameters (model, optimizer, scheduler, datamodule, diffusion settings, logging, trainer) are defined as YAML.
b. Experiment Orchestrator
• src/interface.py inspects your Hydra config and instantiates:
• A Lightning DataModule (from src/datamodules/…)
• An “Experiment” object (classes in src/experiment_types/…) that wraps model + training logic
• src/train.py kicks off the Lightning trainer with callbacks, loggers, schedulers, etc.
c. Data Layer
• Data download scripts in scripts/ populate $DATA_DIR.
• src/datamodules/abstract_datamodule.py defines the interface; concrete datasets are implemented in src/datamodules/datasets/….
• Data transforms and batching follow the Lightning DataModule pattern.
d. Model & Diffusion Layer
• Base model classes in src/models/_base_model.py.
• Specific architectures in src/models/unet.py, src/models/simple_conv_net.py, and advanced MCV-D variants in src/models/mcvd/….
• Diffusion schedulers and algorithms in src/diffusion/ (e.g., ddpm.py, dyffusion.py, mcvd.py).
• Experiment logic (interpolation vs. forecasting) lives in src/experiment_types/forecasting_multi_horizon.py and interpolation.py.
e. Training & Callbacks
• PyTorch Lightning Trainer configured via src/configs/trainer/*.yaml.
• Callbacks (early‐stop, checkpointing, custom logging) in src/configs/callbacks/*.yaml and implemented under src/utilities/wandb_callbacks.py.
• Learning‐rate schedulers under src/utilities/lr_scheduler.py and configurable via src/configs/scheduler/*.yaml.
f. Logging & Checkpointing
• W&B integration via src/configs/logger/wandb.yaml and src/utilities/wandb_api.py.
• TensorBoard alternative via src/configs/logger/tensorboard.yaml.
Relationships & Data Flows
• CLI → Hydra loads config → interface.py builds DataModule + Experiment
• DataModule fetches raw data from file system → preprocessed batches
• Experiment receives batches → model.forward() + diffusion steps → loss backprop
• Trainer invokes callbacks & logger → checkpoints & metrics sent to W&B/TensorBoard
• Optionally, external scripts handle data acquisition before CLI run.
Architectural Patterns & Principles
• Dependency‐injection via Hydra: loose coupling between code and configs.
• PyTorch Lightning’s “DataModule + LightningModule” abstraction for clear separation of data and model logic.
• Modular diffusion logic: base classes + pluggable schedules/models (factory pattern).