# aailabkaist/tdsm architecture

> Architecture diagram of the GitHub repository aailabkaist/tdsm, 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/aailabkaist/tdsm
- Repository: https://github.com/aailabkaist/tdsm

## Overview

##### Main Components
- Data Preparation Module
– Represented by dataset_tool.py, which handles the conversion of standard datasets (e.g., CIFAR-10) into the specialized noisy labeled ZIP format (with a dataset.json for metadata).
- Model Training Components
– Two primary training scripts: train_classifier.py for classifier training and train_noise.py for the diffusion models using the TDSM objective.
– Common modules under the “training” directory handle augmentation (augment.py), loss computations (loss.py), and discrete training loops (training_loop.py, training_noise_loop.py, and classifier_loop.py).
- Utility Components
– The “dnnlib” directory (including util.py) contains utility functions likely used across various parts of the code.
– The “torch_utils” directory provides distributed training support, persistence, miscellaneous utilities, and training stats, which are essential for handling multi-GPU setups.
- Sample Generation
– The generate.py script is used to generate samples using a pre-trained network, indicating a final inference stage in the system.
- Environment and Deployment
– Dockerfile and environment.yml help manage the containerized and conda-based environment settings, ensuring replicability.

##### Relationships and Interactions
- Data Flow:
– Start with the data preparation module using dataset_tool.py to convert raw datasets into the required format.
– The prepared dataset is then used by the training scripts (train_classifier.py and train_noise.py).
- Model Training Workflow:
– The training scripts rely on several internal modules: the “training” submodules for data handling, loss functions, and network architectures, and the “dnnlib” and “torch_utils” for utilities and distributed support.
– There’s an interaction between the classifier (trained via train_classifier.py) and the diffusion training (train_noise.py) where the trained classifier network is supplied (using the --cls parameter) to adjust the diffusion model’s training.
- Sample Generation:
– After training, generate.py uses the trained score network and a latent noise seed to produce generated samples.

##### Architectural Patterns and Principles
- Modularity: The project separates different concerns into distinct modules (data handling, utilities, training, and generation). This clear separation makes the overall architecture more maintainable and reusable.
- Distributed/Parallel Training: The torch_utils components and the usage of torchrun with --nproc_per_node indicate that distributed training principles are applied.
- Custom Loss and Training Loops: The use of custom training loops (e.g., training_loop.py, training_noise_loop.py) highlights that the model uses a specialized training procedure (TDSM – Transition-aware weighted Denoising Score Matching), which is a core idea of the paper.

##### Technologies, Frameworks, and Libraries
- PyTorch (with specific reliance on its distributed training features) is the backbone for model training.
- CUDA is used for leveraging NVIDIA GPUs (Tesla P40 in the experiments).
- Utility libraries in dnnlib and torch_utils provide essential supporting functions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Preparation Layer
    subgraph "Data Preparation and Preprocessing"
        DP["Data Preparation"]:::preprocessing
    end

    %% Training Components Layer
    subgraph "Training Components"
        subgraph "Classifier Training"
            CT1["Train Classifier"]:::training
            CT2["Classifier Loop"]:::training
        end
        subgraph "Diffusion Training (TDSM)"
            DT1["Train Diffusion"]:::training
            DT2["Diffusion Loop"]:::training
        end
        subgraph "Core Training & Utilities"
            TLoop["Training Loop"]:::core
            TLoss["Loss Computations"]:::core
            TAug["Data Augmentation"]:::core
            TNet["Network Architectures"]:::core
            TRes["ResNet Conditioning"]:::core
            TDSet["Dataset Utilities"]:::core
        end
    end

    %% Utility Modules Layer
    subgraph "Utility Modules"
        DU["dnnlib Utilities"]:::utility
        UT["Distributed & Misc Utilities"]:::utility
    end

    %% Inference / Generation Layer
    SG["Sample Generation"]:::generation

    %% Environment & Deployment Layer
    subgraph "Environment & Deployment"
        Env1["Deployment Config"]:::deployment
        Env2["Conda Environment"]:::deployment
    end

    %% Connections - Data Flow
    DP -->|"provides data"| CT1
    DP -->|"provides data"| DT1
    CT1 -->|"executes"| CT2
    CT2 -->|"feeds into"| DT1
    %% Core Utilities support training pipelines
    TLoop --- CT1
    TLoop --- DT1
    %% Utility Modules support Core Training
    DU --> TLoop
    UT --> TLoop
    %% Training outputs lead to Sample Generation
    CT2 -->|"outputs"| SG
    DT2 -->|"outputs"| SG
    %% Environment supports major layers
    Env1 --- DP
    Env1 --- TLoop
    Env1 --- SG
    Env2 --- DP
    Env2 --- TLoop
    Env2 --- SG

    %% Style Classes
    classDef preprocessing fill:#ffdead,stroke:#8b4513,stroke-width:2px;
    classDef training fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef core fill:#e6e6fa,stroke:#4b0082,stroke-width:2px;
    classDef utility fill:#d3ffce,stroke:#006400,stroke-width:2px;
    classDef generation fill:#c1f0c1,stroke:#008000,stroke-width:2px;
    classDef deployment fill:#ffd700,stroke:#b8860b,stroke-width:2px;

    %% Click Events for Data Preparation
    click DP "https://github.com/aailabkaist/tdsm/blob/main/dataset_tool.py"

    %% Click Events for Classifier Training Components
    click CT1 "https://github.com/aailabkaist/tdsm/blob/main/train_classifier.py"
    click CT2 "https://github.com/aailabkaist/tdsm/blob/main/training/classifier_loop.py"

    %% Click Events for Diffusion Training Components
    click DT1 "https://github.com/aailabkaist/tdsm/blob/main/train_noise.py"
    click DT2 "https://github.com/aailabkaist/tdsm/blob/main/training/training_noise_loop.py"

    %% Click Events for Core Training & Utilities Components
    click TLoop "https://github.com/aailabkaist/tdsm/blob/main/training/training_loop.py"
    click TLoss "https://github.com/aailabkaist/tdsm/blob/main/training/loss.py"
    click TAug "https://github.com/aailabkaist/tdsm/blob/main/training/augment.py"
    click TNet "https://github.com/aailabkaist/tdsm/blob/main/training/networks.py"
    click TRes "https://github.com/aailabkaist/tdsm/blob/main/training/resnet_cond.py"
    click TDSet "https://github.com/aailabkaist/tdsm/blob/main/training/dataset.py"

    %% Click Events for Utility Modules
    click DU "https://github.com/aailabkaist/tdsm/blob/main/dnnlib/util.py"
    click UT "https://github.com/aailabkaist/tdsm/tree/main/torch_utils"

    %% Click Event for Sample Generation
    click SG "https://github.com/aailabkaist/tdsm/blob/main/generate.py"

    %% Click Events for Environment & Deployment Components
    click Env1 "https://github.com/aailabkaist/tdsm/tree/main/Dockerfile"
    click Env2 "https://github.com/aailabkaist/tdsm/blob/main/environment.yml"
```
