# jannerm/diffuser architecture

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

- Interactive diagram: https://gitdiagram.com/jannerm/diffuser
- Repository: https://github.com/jannerm/diffuser

## Overview

##### Project type and purpose
- This is an open-source research tool for diffusion-based planning in offline reinforcement learning (RL).
- It provides functionality for:
- Training diffusion models on D4RL locomotion datasets
- Training value functions
- Generating action plans via guided sampling
- Visualizing results and integrating with cloud and HPC back-ends

##### File structure
Top-level directories:
- diffuser/        ← core Python package
- datasets/      ← data buffers, normalization, sequence handling
- environments/  ← MuJoCo/PyBullet environment wrappers and XML assets
- models/        ← diffusion and temporal model definitions
- sampling/      ← sampling functions, guides, policies
- utils/         ← I/O, logging, rendering, training loops, serialization, cloud helpers
- config/          ← default hyperparameter definitions for diffusion, values, plans
- scripts/         ← CLI entrypoints (train.py, train_values.py, plan_guided.py, plotting notebooks, download helpers)
- plotting/        ← score plotting and table-generation scripts
- azure/, gcp/, slurm/ ← cloud/HPC orchestration, launch & sync scripts for Azure, GCP, and Slurm
- Dockerfile, Singularity.def ← container definitions
- environment.yml, setup.py ← environment and packaging
- logs/ (created at runtime) ← storage of model checkpoints, configs, sample images, plan outputs

##### README for additional insights
- Core workflows:
a. Download or train diffusion model (`scripts/train.py`)
b. Train value function (`scripts/train_values.py`)
c. Plan via guided sampling (`scripts/plan_guided.py`)
- Integration: Docker, Singularity, Azure (using azure/launch.py), GCP, and Slurm scripts.
- Dependencies: D4RL, mujoco/pybullet, PyTorch, Hugging Face Diffusers integration.

##### Detail
- Submodules for clarity (e.g., within Core: datasets, models, sampling, utils)
- Both local and remote execution paths (Docker/Singularity vs. Azure/GCP/Slurm)
- Storage of checkpoints, logs, and upload/download via azure/utils or gcp scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Scripts
    subgraph "CLI & Scripts"
        style CLI_Scripts fill:#a2d5f2,stroke:#333,stroke-width:1px
        CLI_Train["train.py"]:::cli
        CLI_TrainValues["train_values.py"]:::cli
        CLI_Plan["plan_guided.py"]:::cli
        CLI_Read["read_results.py"]:::cli
        CLI_Notebook["diffuser_sample.ipynb"]:::cli
    end

    %% Configuration Manager
    Config["Configuration Manager\n(locomotion.py)"]:::config

    %% Core Library
    subgraph "Core Library"
        style CoreLib fill:#b2f2bb,stroke:#333,stroke-width:1px
        subgraph "Data Loader & Buffer"
            Buffer["buffer.py"]:::core
            D4RL["d4rl.py"]:::core
            Norm["normalization.py"]:::core
            Preproc["preprocessing.py"]:::core
            Seq["sequence.py"]:::core
        end
        subgraph "Environment Interface"
            Ant["ant.py"]:::core
            HalfCheetah["half_cheetah.py"]:::core
            Hopper["hopper.py"]:::core
            Walker2d["walker2d.py"]:::core
            Reg["registration.py"]:::core
            Assets["assets/*.xml"]:::core
        end
        subgraph "Model Trainer"
            Diffusion["diffusion.py"]:::core
            Temporal["temporal.py"]:::core
            Helpers["helpers.py"]:::core
            TrainUtil["training.py"]:::core
        end
        subgraph "Sampler & Planner"
            Functions["functions.py"]:::core
            Guides["guides.py"]:::core
            Policies["policies.py"]:::core
        end
        subgraph "Utilities"
            Logger["logger.py"]:::core
            Serialization["serialization.py"]:::core
            ConfigUtil["config.py"]:::core
            CloudUtil["cloud.py"]:::core
            Rendering["rendering.py"]:::core
            Progress["progress.py"]:::core
            Video["video.py"]:::core
            GitUtil["git_utils.py"]:::core
            TrainUtil2["training.py"]:::core
            SetupUtil["setup.py"]:::core
        end
    end

    %% Storage & Logging
    subgraph "Storage & Logging"
        style Storage fill:#f9db7c,stroke:#333,stroke-width:1px
        Logs["logs/"]:::storage
        LogUtil["logger.py"]:::storage
        SerUtil["serialization.py"]:::storage
    end

    %% Visualization & Reporting
    subgraph "Visualization & Reporting"
        style Viz fill:#d1c4e9,stroke:#333,stroke-width:1px
        PlotScores["locomotion_scores.py"]:::viz
        PlotTable["table.py"]:::viz
        ReadResults2["read_results.py"]:::viz
    end

    %% Containers & Orchestration
    subgraph "Container & Orchestration"
        style Orch fill:#ffcc80,stroke:#333,stroke-width:1px
        subgraph "Local Containers"
            Docker["Dockerfile"]:::orch
            Singularity["Singularity.def"]:::orch
        end
        subgraph "Cloud/HPC Launchers"
            Azure["azure/launch.py"]:::orch
            GCP["gcp/train.sh"]:::orch
            Slurm["slurm/train.sh"]:::orch
        end
    end

    %% Packaging & Environment
    subgraph "Packaging & Environment"
        style Pack fill:#cfd8dc,stroke:#333,stroke-width:1px
        Setup["setup.py"]:::pack
        EnvYML["environment.yml"]:::pack
    end

    %% External Dependencies
    subgraph "External Dependencies"
        style Ext fill:#eceff1,stroke:#333,stroke-width:1px
        D4RL_Ext["D4RL"]:::ext
        Mujoco["MuJoCo"]:::ext
        PyBullet["PyBullet"]:::ext
        PyTorch["PyTorch"]:::ext
        HF["HuggingFace\nDiffusers"]:::ext
    end

    %% Connections
    CLI_Train -->|uses config| Config
    CLI_TrainValues -->|uses config| Config
    CLI_Plan -->|uses config| Config
    CLI_Read -->|uses config| Config
    CLI_Notebook -->|uses config| Config

    Config -->|configures| Buffer
    Config -->|configures| Ant

    Config -->|configures| Diffusion

    Buffer -->|provides data| Diffusion
    Buffer -->|provides data| Temporal

    Ant -->|environment step| Diffusion
    Ant -->|environment step| Functions

    Diffusion -->|train| Logs
    Temporal -->|train| Logs

    Functions -->|sample plan| Logs
    Guides -->|guide sampling| Functions
    Policies -->|policy sampling| Functions

    Logs -->|persist| SerUtil

    PlotScores -->|read| Logs
    PlotTable -->|read| Logs
    ReadResults2 -->|read| Logs

    Docker -->|containerizes| CLI_Train
    Singularity -->|containerizes| CLI_Train

    Azure -->|launch| Docker
    GCP -->|launch| Docker
    Slurm -->|launch| Docker

    Azure -->|upload/download| Logs
    GCP -->|upload/download| Logs
    Slurm -->|upload/download| Logs

    CLI_Train -->|imports| Diffusion
    CLI_TrainValues -->|imports| Temporal
    CLI_Plan -->|imports| Functions
    CLI_Read -->|imports| SerUtil

    CLI_Train -->|calls| D4RL_Ext
    CLI_Train -->|calls| Mujoco
    CLI_Train -->|calls| PyBullet
    CLI_Train -->|calls| PyTorch
    CLI_Train -->|calls| HF

    %% Click Events
    click CLI_Train "https://github.com/jannerm/diffuser/blob/main/scripts/train.py"
    click CLI_TrainValues "https://github.com/jannerm/diffuser/blob/main/scripts/train_values.py"
    click CLI_Plan "https://github.com/jannerm/diffuser/blob/main/scripts/plan_guided.py"
    click CLI_Read "https://github.com/jannerm/diffuser/blob/main/scripts/read_results.py"
    click CLI_Notebook "https://github.com/jannerm/diffuser/blob/main/scripts/diffuser_sample.ipynb"
    click Buffer "https://github.com/jannerm/diffuser/blob/main/diffuser/datasets/buffer.py"
    click D4RL "https://github.com/jannerm/diffuser/blob/main/diffuser/datasets/d4rl.py"
    click Norm "https://github.com/jannerm/diffuser/blob/main/diffuser/datasets/normalization.py"
    click Preproc "https://github.com/jannerm/diffuser/blob/main/diffuser/datasets/preprocessing.py"
    click Seq "https://github.com/jannerm/diffuser/blob/main/diffuser/datasets/sequence.py"
    click Ant "https://github.com/jannerm/diffuser/blob/main/diffuser/environments/ant.py"
    click HalfCheetah "https://github.com/jannerm/diffuser/blob/main/diffuser/environments/half_cheetah.py"
    click Hopper "https://github.com/jannerm/diffuser/blob/main/diffuser/environments/hopper.py"
    click Walker2d "https://github.com/jannerm/diffuser/blob/main/diffuser/environments/walker2d.py"
    click Reg "https://github.com/jannerm/diffuser/blob/main/diffuser/environments/registration.py"
    click Assets "https://github.com/jannerm/diffuser/blob/main/diffuser/environments/assets/*.xml"
    click Diffusion "https://github.com/jannerm/diffuser/blob/main/diffuser/models/diffusion.py"
    click Temporal "https://github.com/jannerm/diffuser/blob/main/diffuser/models/temporal.py"
    click Helpers "https://github.com/jannerm/diffuser/blob/main/diffuser/models/helpers.py"
    click TrainUtil "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/training.py"
    click Functions "https://github.com/jannerm/diffuser/blob/main/diffuser/sampling/functions.py"
    click Guides "https://github.com/jannerm/diffuser/blob/main/diffuser/sampling/guides.py"
    click Policies "https://github.com/jannerm/diffuser/blob/main/diffuser/sampling/policies.py"
    click Logger "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/logger.py"
    click Serialization "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/serialization.py"
    click ConfigUtil "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/config.py"
    click CloudUtil "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/cloud.py"
    click Rendering "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/rendering.py"
    click Progress "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/progress.py"
    click Video "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/video.py"
    click GitUtil "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/git_utils.py"
    click TrainUtil2 "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/training.py"
    click SetupUtil "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/setup.py"
    click Config "https://github.com/jannerm/diffuser/blob/main/config/locomotion.py"
    click Logs "https://github.com/jannerm/diffuser/tree/main/logs/"
    click LogUtil "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/logger.py"
    click SerUtil "https://github.com/jannerm/diffuser/blob/main/diffuser/utils/serialization.py"
    click PlotScores "https://github.com/jannerm/diffuser/blob/main/plotting/locomotion_scores.py"
    click PlotTable "https://github.com/jannerm/diffuser/blob/main/plotting/table.py"
    click ReadResults2 "https://github.com/jannerm/diffuser/blob/main/scripts/read_results.py"
    click Docker "https://github.com/jannerm/diffuser/tree/main/Dockerfile"
    click Singularity "https://github.com/jannerm/diffuser/blob/main/Singularity.def"
    click Azure "https://github.com/jannerm/diffuser/blob/main/azure/launch.py"
    click GCP "https://github.com/jannerm/diffuser/blob/main/gcp/train.sh"
    click Slurm "https://github.com/jannerm/diffuser/blob/main/slurm/train.sh"
    click Setup "https://github.com/jannerm/diffuser/blob/main/setup.py"
    click EnvYML "https://github.com/jannerm/diffuser/blob/main/environment.yml"

    %% Styles
    classDef cli fill:#a2d5f2,stroke:#333;
    classDef core fill:#b2f2bb,stroke:#333;
    classDef config fill:#ffe082,stroke:#333;
    classDef storage fill:#f9db7c,stroke:#333;
    classDef viz fill:#d1c4e9,stroke:#333;
    classDef orch fill:#ffcc80,stroke:#333;
    classDef pack fill:#cfd8dc,stroke:#333;
    classDef ext fill:#eceff1,stroke:#333;
```
