# y-debug-sys/diffusion-ts architecture

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

- Interactive diagram: https://gitdiagram.com/y-debug-sys/diffusion-ts
- Repository: https://github.com/y-debug-sys/diffusion-ts

## Overview

##### Project Type & Purpose
- Diffusion-TS is a specialized framework that uses denoising diffusion probabilistic models for generating high-quality, interpretable time series. Specifically, it uses an encoder-decoder transformer architecture enhanced with Fourier and polynomial components for seasonality and trend decomposition.
- The project supports both conditional (forecasting, imputation) and unconditional generation.
- Its design is influenced by modern generative models and deep learning, with direct applications in forecasting, imputation, and simulation of time series data.

##### Analyzing the File Structure
- Key directories:
- Config: Contains various YAML configuration files with settings for different datasets or experiment configurations, indicating that the framework is highly configurable.
- Data: Stores or instructs the placement of datasets along with scripts for creating dataloaders.
- Experiments: Jupyter notebooks that showcase experiments, evaluations, and may include visualization of various metrics.
- Models: This directory has two main model implementations:
▪ "interpretable_diffusion" includes the diffusion model implementation (including classifier, Gaussian diffusion routines, transformer module, etc.).
▪ "ts2vec" focusing on time series representation.
- Utils: Contains utility submodules for data handling, metrics (discriminative, cross-correlation, predictive), masking, IO, etc.
- engine: Contains essential training components like logger, learning rate schedules, and a solver for the training process.
- Other files: main.py as the entry point, several tutorials, and requirements.txt for dependencies.
- This structure indicates a modular design separating configuration, models, data management, experiment scripts, and utility functions, which hints at a layered or component-oriented architecture.

a. Main Components to Include:
- Data Module:
- Data Ingestion: “Data” directory where raw datasets are placed.
- Preprocessing and Dataloader Script (located in Data/build_dataloader.py and Utils/Data_utils).
- Configuration Module:
- Config folder holding YAML files to customize training, sampling, and evaluation scenarios.
- Model Components:
- Interpretable Diffusion Module: Contains the diffusion algorithms (gaussian_diffusion), classifier guidance, and transformer architecture.
- TS2Vec Module: Handles extraction of latent representations from time series data.
- Engine/Training Module:
- Training Process: Managed via engine files (solver, lr_sch, logger) and initiated via main.py.
- Evaluation & Visualization Module:
- Evaluation scripts in the Experiments folder and Utils that compute context-FID, predictive scores, and visualization (e.g., t-SNE results).
- External Dependencies & Environment:
- The dependency management (requirements.txt) and GPU/CUDA environment details.

b. Relationships and Interactions:
- Data flows from the Data Module into preprocessing and then is fed into the Model Module.
- The configuration files serve as parameters that calibrate the behavior of both the training engine and the models.
- The Engine module interacts with the Model Module during training and sampling. trained checkpoints lead to the generation of samples.
- Post-generation, data is processed by evaluation utilities in the Utils and Experiments modules which provide quantitative and visual analysis.
- The overall flow can be illustrated as: Dataset → Data Loader / Preprocessing → Diffusion-TS Model (Encoder-Decoder with seasonal/trend decomposition) → Training Engine → Output Samples → Evaluation & Visualization.

c. Architectural Patterns and Design Principles:
- Modularity: The architecture is separated into clear components (data management, model definitions, utilities, engine/scheduler, experiments).
- Pipeline orchestration: The training and inference processes follow a sequential pipeline orchestrated by main.py and configuration-driven parameters.
- Extensibility: The clear separation between model architectures (interpretable diffusion vs. ts2vec) allows independent evolution/test of modules.
- Configurability: Use of YAML configuration files allows users to quickly switch contexts (e.g., different datasets or conditional vs. unconditional generation).
- Integration of multiple evaluation metrics shows an emphasis on comprehensive performance analysis.

d. Technologies, Frameworks, and Libraries:
- Python 3.8 and PyTorch (2.0+), as indicated in the README shields.
- Jupyter notebooks for experiments.
- YAML for configuration management.
- Additional libraries for evaluation metrics and visualization (possibly matplotlib, scikit-learn for t-SNE etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Module Subgraph
    subgraph "Data Module"
        A["Raw Datasets"] 
        B["Dataloader Script"]
        C["Preprocessing Utilities"]
    end

    %% Configuration Module Subgraph
    subgraph "Configuration Module"
        F["Configurations"]
    end

    %% Model Components Subgraph
    subgraph "Model Components"
        D["Interpretable Diffusion Model (Encoder-Decoder Transformer with Fourier/Trend & Classifier Guidance)"]
        E["TS2Vec Representation"]
    end

    %% Engine/Training Module Subgraph
    subgraph "Engine/Training Module"
        H["Entry Point (main.py)"]
        G["Training Engine"]
    end

    %% Evaluation & Visualization Module Subgraph
    subgraph "Evaluation & Visualization Module"
        J["Experiment Notebooks"]
        K["Evaluation Metrics & Visualization Utils"]
    end

    I["Output Samples"]

    %% Connections within Data Module
    A -->|"data flow"| B
    B -->|"data flow"| C

    %% Data flows to Model Components
    C -->|"processed data"| D
    C -->|"processed data"| E

    %% Configurations influence models and training
    F -->|"params"| D
    F -->|"params"| E
    F -->|"params"| G

    %% Model components feed into Training Engine
    D -->|"training input"| G
    E -->|"training input"| G

    %% Entry point initiates Training Engine
    H -->|"start"| G

    %% Training Engine produces output samples
    G -->|"generate"| I

    %% Output feeds into Evaluation & Visualization
    I -->|"evaluation input"| J
    I -->|"evaluation input"| K

    %% Feedback loop from Evaluation back to Configurations
    J -->|"feedback"| F
    K -->|"feedback"| F

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef config fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef model fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef engine fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef output fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef eval fill:#DDA0DD,stroke:#333,stroke-width:2px;

    class A,B,C data;
    class F config;
    class D,E model;
    class G,H engine;
    class I output;
    class J,K eval;

    %% Click Events
    click A "https://github.com/y-debug-sys/diffusion-ts/tree/main/Data/"
    click B "https://github.com/y-debug-sys/diffusion-ts/blob/main/Data/build_dataloader.py"
    click C "https://github.com/y-debug-sys/diffusion-ts/tree/main/Utils/Data_utils/"
    click F "https://github.com/y-debug-sys/diffusion-ts/tree/main/Config/"
    click D "https://github.com/y-debug-sys/diffusion-ts/tree/main/Models/interpretable_diffusion/"
    click E "https://github.com/y-debug-sys/diffusion-ts/tree/main/Models/ts2vec/"
    click G "https://github.com/y-debug-sys/diffusion-ts/tree/main/engine/"
    click H "https://github.com/y-debug-sys/diffusion-ts/blob/main/main.py"
    click J "https://github.com/y-debug-sys/diffusion-ts/tree/main/Experiments/"
    click K "https://github.com/y-debug-sys/diffusion-ts/tree/main/Utils/"
```
