# mengxiangming/dmps architecture

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

- Interactive diagram: https://gitdiagram.com/mengxiangming/dmps
- Repository: https://github.com/mengxiangming/dmps

## Overview

##### Project type and purpose
- This is a research‐oriented Python toolkit implementing “Diffusion Model Based Posterior Sampling (DMPS)” for noisy linear inverse problems.
- It provides a command-line interface (main.py + shell scripts) to load a pretrained diffusion model, configure a task (denoising, deblurring, colorization, super-resolution), perform posterior sampling, and save results.

##### File structure
- Top-level directories:
- configs/ – YAML files describing model hyperparameters, diffusion settings, and task-specific measurement operators
- data/ – data loader and sample inputs for demo
- guided_diffusion/ – core diffusion model implementation (UNet, Gaussian diffusion process, sampling scheduler)
- util/ – helper modules for image I/O, preprocessing, metrics, logging
- scripts/ – shell wrappers that call main.py with predefined configs
- Key files:
- main.py – orchestrates end-to-end workflow: parse args, load configs, initialize model & data, run sampler
- requirements.txt – Python dependencies (PyTorch, mpi4py, scikit-image, etc.)
- Deployment artifacts: pretrained checkpoints in models/ (not in tree), outputs saved under user-specified save_dir.

##### Insights from README
- Stages: environment setup → download pretrained model → prepare data → run sampling
- Supported tasks driven entirely by config files: model_config*.yaml + diffusion_config.yaml + one task_config.yaml
- External dependencies: GPU/CUDA, mpi4py for parallel sampling, blobfile for data I/O.

##### Main components & interactions
A. Configuration Manager
- Loads YAML files (model, diffusion, task)
- Passes hyperparameters to downstream modules
B. Data Loader
- Reads sample images / dataset directory
- Applies preprocessing (util/data_preprocessing, resizer)
C. Diffusion Model Module (guided_diffusion/)
- UNet backbone (unet.py)
- Gaussian diffusion scheduler (gaussian_diffusion.py, posterior_mean_variance.py)
- Conditioning methods (condition_methods.py) for measurement operator A
- Utility functions (fp16_util, dist_util)
D. Posterior Sampler (main pipeline in main.py)
- At each diffusion timestep, compute score with model
- Incorporate measurement likelihood via pseudo-likelihood term
- Iterate sampling loop → produce final x samples
E. Utilities & Tools
- Logging (util/logger.py)
- Metrics computation (util/compute_metric.py)
- Image I/O and visualization (util/img_utils.py, figures/)
F. Shell Scripts & CLI
- scripts/run_*.sh launch main.py with predefined configs
G. External Services
- PyTorch + CUDA for GPU acceleration
- mpi4py for distributed sampling (optional)
- File system for loading/saving checkpoints, data, results

##### Architectural patterns & design principles
- Modular separation: configs ↔ core model ↔ data ↔ utilities
- Plugin style for new tasks: drop in new task_config.yaml
- Single orchestration script (main.py) using dependency injection from configs
- Lightweight wrapper scripts for reproducibility
- Clear separation between pure ML code (guided_diffusion) and infrastructure (data, util, logging)

##### Final checklist
- All major Python packages/modules represented
- Clear boundary between user interface (CLI/scripts) and core library
- Configurable pipeline stages visibly annotated

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "CLI & Scripts"
        direction TB
        Scripts["Shell Scripts & CLI"]:::blue
    end

    %% Configuration Layer
    subgraph "Configuration Manager"
        direction TB
        Config["Load YAML Configs"]:::blue
    end

    %% Data Layer
    subgraph "Data Loader" 
        direction TB
        DataLoader["Data Loader"]:::orange
    end

    %% Core ML Components
    subgraph "Diffusion Model Module" 
        direction TB
        UNet["UNet"]:::green
        GaussianDiff["Gaussian Diffusion Scheduler"]:::green
        PosteriorMV["Posterior Mean & Variance"]:::green
        ConditionMethods["Condition Methods"]:::green
        DistUtil["Distributed Util"]:::green
        FP16Util["FP16 Util"]:::green
        Measurements["Measurements"]:::green
        NN["NN Helpers"]:::green
    end

    %% Posterior Sampler
    subgraph "Posterior Sampler Pipeline"
        direction TB
        Sampler["Sampler Controller (main.py)"]:::blue
    end

    %% Utilities & Tools
    subgraph "Utilities & Tools"
        direction TB
        Logger["Logging (logger.py)"]:::orange
        Metrics["Metrics (compute_metric.py)"]:::orange
        Preprocess["Preprocessing"]:::orange
        ImgUtils["Image I/O (img_utils.py)"]:::orange
        Resizer["Resizer"]:::orange
        Functions["Functions"]:::orange
        Tools["Tools"]:::orange
        FastMRI["FastMRI Utils"]:::orange
    end

    %% External Services
    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch + CUDA"]:::gray
        MPI["mpi4py"]:::gray
        FS["Filesystem"]:::gray
        Requirements["requirements.txt"]:::gray
    end

    %% Connections
    Scripts -->|"invoke"| Config
    Config -->|"YAML params"| DataLoader
    Config -->|"YAML params"| Sampler
    DataLoader -->|"batch of images"| Sampler
    Sampler -->|"model init"| UNet
    Sampler -->|"scheduler & variance"| GaussianDiff
    Sampler -->|"posterior stats"| PosteriorMV
    Sampler -->|"conditioning"| ConditionMethods
    UNet -->|"calls"| DistUtil
    UNet -->|"supports"| FP16Util
    ConditionMethods -->|"uses"| Measurements
    UNet -->|"built on"| NN

    Sampler -->|"samples"| Logger
    Sampler -->|"metrics"| Metrics
    Sampler -->|"preprocess calls"| Preprocess
    Sampler -->|"image ops"| ImgUtils
    Sampler -->|"resize ops"| Resizer
    Sampler -->|"misc functions"| Functions
    Sampler -->|"tools calls"| Tools
    Sampler -->|"fastMRI ops"| FastMRI

    Sampler -->|"writes"| FS
    Sampler -->|"distributed"| MPI
    Sampler -->|"GPU accel"| PyTorch
    Sampler -->|"deps"| Requirements

    %% Click Events
    click Config "https://github.com/mengxiangming/dmps/tree/main/configs/"
    click DataLoader "https://github.com/mengxiangming/dmps/blob/main/data/dataloader.py"
    click UNet "https://github.com/mengxiangming/dmps/blob/main/guided_diffusion/unet.py"
    click GaussianDiff "https://github.com/mengxiangming/dmps/blob/main/guided_diffusion/gaussian_diffusion.py"
    click PosteriorMV "https://github.com/mengxiangming/dmps/blob/main/guided_diffusion/posterior_mean_variance.py"
    click ConditionMethods "https://github.com/mengxiangming/dmps/blob/main/guided_diffusion/condition_methods.py"
    click DistUtil "https://github.com/mengxiangming/dmps/blob/main/guided_diffusion/dist_util.py"
    click FP16Util "https://github.com/mengxiangming/dmps/blob/main/guided_diffusion/fp16_util.py"
    click Measurements "https://github.com/mengxiangming/dmps/blob/main/guided_diffusion/measurements.py"
    click NN "https://github.com/mengxiangming/dmps/blob/main/guided_diffusion/nn.py"
    click Sampler "https://github.com/mengxiangming/dmps/blob/main/main.py"
    click Logger "https://github.com/mengxiangming/dmps/blob/main/util/logger.py"
    click Metrics "https://github.com/mengxiangming/dmps/blob/main/util/compute_metric.py"
    click Preprocess "https://github.com/mengxiangming/dmps/blob/main/util/data_preprocessing.py"
    click ImgUtils "https://github.com/mengxiangming/dmps/blob/main/util/img_utils.py"
    click Resizer "https://github.com/mengxiangming/dmps/blob/main/util/resizer.py"
    click Functions "https://github.com/mengxiangming/dmps/blob/main/util/functions.py"
    click Tools "https://github.com/mengxiangming/dmps/blob/main/util/tools.py"
    click FastMRI "https://github.com/mengxiangming/dmps/blob/main/util/fastmri_utils.py"
    click Scripts "https://github.com/mengxiangming/dmps/blob/main/scripts/run_denoise_ffhq.sh"
    click Requirements "https://github.com/mengxiangming/dmps/blob/main/requirements.txt"

    %% Styles
    classDef blue fill:#D6EAF8,stroke:#2E86C1,color:#1B4F72,stroke-width:1px;
    classDef green fill:#D5F5E3,stroke:#27AE60,color:#145A32,stroke-width:1px;
    classDef orange fill:#FCF3CF,stroke:#F1C40F,color:#7D6608,stroke-width:1px;
    classDef gray fill:#E5E7E9,stroke:#566573,color:#1C2833,stroke-width:1px;
```
