# hojonathanho/diffusion architecture

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

- Interactive diagram: https://gitdiagram.com/hojonathanho/diffusion
- Repository: https://github.com/hojonathanho/diffusion

## Overview

##### Project Type and Purpose
- The project is a research code repository implementing denoising diffusion probabilistic models (as described in the associated paper). It is a machine learning experiment repository targeting generative modeling with applications in image synthesis.
- The code is written for TensorFlow 1.15 and designed to run experiments on Google Cloud TPUs. It includes scripts for training and evaluating on datasets like CelebA-HQ, CIFAR, and LSUN.
- The primary goal is to build and evaluate diffusion probabilistic models using state-of-the-art architectures (e.g., U-Net) with TPU acceleration.

##### Analyzing the File Structure
- The top-level files include configuration, dependency listings (requirements.txt), and a comprehensive README that outlines the experiments.
- The “diffusion_tf” directory is the core library package containing:
- Core utilities (diffusion_utils.py, diffusion_utils_2.py and utils.py) that encapsulate the diffusion process.
- The “models” subdirectory with a file unet.py, which contains the primary network architecture.
- TPU-specific utilities (in diffusion_tf/tpu_utils) for metrics, dataset handling, evaluation workers, summaries, and general TPU routines. This highlights a focus on optimizing and executing experiments on TPU hardware.
- A separate nn.py module possibly coordinating neural network operations.
- The “scripts” folder houses the entry point scripts (run_celebahq.py, run_cifar.py, run_lsun.py) that serve as training and evaluation routines. They include commented command examples that detail how to execute experiments with proper Cloud TPU and bucket configurations.
- The “resources” folder holds sample images illustrating outputs from the model.

##### Key Components
a. Core Library (diffusion_tf Package):
- Diffusion Core: diffusion_utils and utils modules.
- Model Definitions: “models” folder – particularly unet.py.
- Neural Networks: nn.py for network operations.

b. TPU Utilities:
- TPU Integration: All files under diffusion_tf/tpu_utils handle dataset loading (datasets.py), evaluation (simple_eval_worker.py), summaries (tpu_summaries.py), and utility routines (tpu_utils.py). They represent the backend support for scaling experiments on TPUs.

c. Experiment / Execution Scripts:
- Training/Evaluation Entry Points: Scripts under the “scripts” directory are light wrappers that initialize experiments. They pass configuration details like the GCS bucket prefix to the underlying model and TPU routines.
- Data Management: Reflected through the usage of GCS buckets, with the naming convention described in the README.

d. External Dependencies and Infrastructure:
- Cloud TPU v3-8 as the hardware backend.
- Google Cloud Storage (GCS) for storing and retrieving datasets and possibly model snapshots.
- TensorFlow 1.15, along with TensorFlow Probability, GAN utilities, and related Python libraries from requirements.txt.

##### Relationships & Interactions
- The execution scripts (scripts/run_*.py) act as the orchestrators, invoking core model functionalities and utility functions.
- The core “diffusion_tf” package is the engine where the diffusion process is implemented. It interacts with the TPU utilities to handle distributed computation, data pipelines, and performance monitoring.
- Data flows from external sources (GCS buckets) into the TPU processing pipelines via the datasets modules in TPU utils.
- Post-processing (sample generation and evaluation) is fed back into the system, leveraging TensorFlow and TPU summaries for logging and visual output.
- The unet model definition sits at the heart of the diffusion process, dictating how images are generated.

##### Architectural Patterns and Design Principles
- Modular Separation: Clear separation between domain-specific diffusion logic (diffusion_tf package), TPU and data handling utilities (tpu_utils), and experiment orchestration (scripts).
- Scalability: The design supports high-performance TPU computations, factored via the TPU utilities.
- Extensibility: With clearly defined modules (e.g., multiple diffusion utilities, separate model definitions), it’s straightforward to extend or alter diffusion processes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies & Infrastructure
    subgraph "External Dependencies & Infrastructure"
        TPU_HW["Cloud TPU v3-8"]:::external
        GCS["Google Cloud Storage"]:::external
        TF["TensorFlow 1.15 & Libraries"]:::external
    end

    %% Execution Scripts
    subgraph "Execution Scripts"
        Exec1["Run CelebA-HQ"]:::exec
        Exec2["Run CIFAR"]:::exec
        Exec3["Run LSUN"]:::exec
    end

    %% Core Diffusion Library
    subgraph "Core Diffusion Library"
        %% Diffusion Operations
        subgraph "Diffusion Operations"
            Diff1["Diffusion Utils"]:::core
            Diff2["Diffusion Utils 2"]:::core
            DiffUtil["Utils"]:::core
        end
        %% Model Architectures (U-Net)
        subgraph "Model Architectures (U-Net)"
            Unet["U-Net Model"]:::core
        end
        %% Neural Network Utilities
        subgraph "Neural Network Utilities"
            NN["NN Operations"]:::core
        end
    end

    %% TPU Utilities
    subgraph "TPU Utilities"
        TPU_DS["TPU Datasets"]:::tpu
        TPU_Eval["TPU Eval Worker"]:::tpu
        TPU_Sum["TPU Summaries"]:::tpu
        TPU_Func["TPU Functions"]:::tpu
        TPU_Metr["TPU Metrics"]:::tpu
    end

    %% Execution Scripts to Core Diffusion Library interactions
    Exec1 -->|"init_diffusion"| Diff1
    Exec2 -->|"init_diffusion"| Diff1
    Exec3 -->|"init_diffusion"| Diff1
    Exec1 -->|"setup_TPU"| TPU_DS

    %% External Dependencies to TPU Utilities interactions
    GCS -->|"TrainingData"| TPU_DS

    %% Core Diffusion Library internal interactions
    Unet -->|"accelerate"| TPU_Func
    Unet -->|"compute"| NN

    %% TPU Utilities internal interactions
    TPU_Metr -->|"measure"| TPU_Eval
    TPU_Eval -->|"logMetrics"| TPU_Sum

    %% Class definitions for coloring
    classDef external fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef exec fill:#cceeff,stroke:#006699,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef tpu fill:#fff2cc,stroke:#cc9900,stroke-width:2px;

    %% Click Events for Core Diffusion Library – Diffusion Operations
    click Diff1 "https://github.com/hojonathanho/diffusion/blob/master/diffusion_tf/diffusion_utils.py"
    click Diff2 "https://github.com/hojonathanho/diffusion/blob/master/diffusion_tf/diffusion_utils_2.py"
    click DiffUtil "https://github.com/hojonathanho/diffusion/blob/master/diffusion_tf/utils.py"

    %% Click Event for Core Diffusion Library – Model Architectures
    click Unet "https://github.com/hojonathanho/diffusion/blob/master/diffusion_tf/models/unet.py"

    %% Click Event for Core Diffusion Library – Neural Network Utilities
    click NN "https://github.com/hojonathanho/diffusion/blob/master/diffusion_tf/nn.py"

    %% Click Events for TPU Utilities
    click TPU_DS "https://github.com/hojonathanho/diffusion/blob/master/diffusion_tf/tpu_utils/datasets.py"
    click TPU_Eval "https://github.com/hojonathanho/diffusion/blob/master/diffusion_tf/tpu_utils/simple_eval_worker.py"
    click TPU_Sum "https://github.com/hojonathanho/diffusion/blob/master/diffusion_tf/tpu_utils/tpu_summaries.py"
    click TPU_Func "https://github.com/hojonathanho/diffusion/blob/master/diffusion_tf/tpu_utils/tpu_utils.py"
    click TPU_Metr "https://github.com/hojonathanho/diffusion/blob/master/diffusion_tf/tpu_utils/classifier_metrics_numpy.py"

    %% Click Events for Experiment / Execution Scripts
    click Exec1 "https://github.com/hojonathanho/diffusion/blob/master/scripts/run_celebahq.py"
    click Exec2 "https://github.com/hojonathanho/diffusion/blob/master/scripts/run_cifar.py"
    click Exec3 "https://github.com/hojonathanho/diffusion/blob/master/scripts/run_lsun.py"
```
