# mobaidoctor/med-ddpm architecture

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

## Overview

##### Main Components
- Data Management & Preprocessing:
- Dataset Folder: Contains the raw input data (NIfTI files for 3D MRIs and segmentation masks), sample CSV files, and scripts like dataset.py and preprocess_brats_data.py.
- Input types include whole-head images and BraTS modalities (T1, T1ce, T2, Flair).
- Diffusion Model Core:
- Folder “diffusion_model” holds core routines: FP16 utilities, logger, modules, trainers (trainer.py, trainer_brats.py), and U-Net model implementations. This is where model training and conditional diffusion logic are implemented.
- Fast Sampling Modules:
- The “fast_sampling” folder (with guided_diffusion and th_deis submodules) is dedicated to running inference quickly. It contains IPython notebooks and scripts for sample generation and optimized sampling routines (e.g., inference_ddpm.py, inference_deis.py).
- Training & Inference Scripts:
- Scripts under “scripts” (train.sh, train_brats.sh, sample.sh, sample_brats.sh) orchestrate training and sampling pipelines.
- Utility Functions:
- The “utils” folder includes helper functions (e.g., dtypes, lowpass_filter) that support data type conversions and filtering needed during processing.
- External Dependencies:
- The README highlights dependencies such as Torchio and Nibabel for handling MRI data.

##### Relationships and Interactions
- Data Flow:
- Data enters via the dataset files (organized per modality and segmentation masks) and is processed through dataset.py. A transformation or preprocessing module prepares the images for model consumption.
- Model Training:
- The training scripts (train.py, train_brats.py) invoke diffusion_model modules. The conditional diffusion process is implemented via U-Net architectures and related utilities (found in diffusion_model/unet.py and unet_brats.py). The training process logs its progress using the logger modules.
- Model Sampling (Inference):
- The fast_sampling modules (fast_sampling/guided_diffusion and fast_sampling/th_deis) illustrate the fast sampling routines optimised specifically for inference. These components take a segmentation mask input and generate synthetic MRI images.
- Integration:
- The system integrates data preprocessing, model training, and sampling into a cohesive workflow controlled by the provided shell scripts.

##### Architectural Patterns & Design Principles
- Modularity: The project separates concerns by having distinct modules for data management, model training, and fast sampling. This separation enables easier testing and potential reusability for different MRI synthesis tasks.
- Pipeline Architecture: A linear yet well-partitioned data pipeline exists, beginning from dataset ingestion, through preprocessing, to model training and sampling.
- Conditional Generation: The architecture emphasizes conditional synthesis, which requires the diffusion model to be fed not only random noise but also semantic information (segmentation masks).

##### Relevant Technologies and Frameworks
- PyTorch: The central framework used to implement the diffusion models.
- Medical Imaging Libraries: Torchio and Nibabel facilitate 3D MRI data handling.
- External GitHub Projects: The project builds upon methodologies from repositories such as denoising-diffusion-pytorch and guided-diffusion.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Management & Preprocessing
    subgraph "Data Management & Preprocessing"
        DP1["Dataset Directory (NIfTI, CSV)"]:::data
        DP2["dataset.py (Data Loader)"]:::data
        DP3["preprocess_brats_data.py (Preprocessing)"]:::data
    end

    %% Diffusion Model Core
    subgraph "Diffusion Model Core"
        DC1["FP16 Utilities (fp16_util.py)"]:::model
        DC2["Logger (logger.py)"]:::model
        DC3["Modules (modules.py)"]:::model
        DC4["Trainer (trainer.py)"]:::model
        DC5["Trainer for BraTS (trainer_brats.py)"]:::model
        DC6["U-Net (unet.py)"]:::model
        DC7["U-Net for BraTS (unet_brats.py)"]:::model
    end

    %% Fast Sampling Modules
    subgraph "Fast Sampling"
        FS1["Fast Sampling Directory (fast_sampling/)"]:::sampling
        FS2["Guided Diffusion (guided_diffusion/)"]:::sampling
        FS3["Th DEIS Module (th_deis/)"]:::sampling
        FS4["Inference DDPM (inference_ddpm.py)"]:::sampling
        FS5["Inference DEIS (inference_deis.py)"]:::sampling
        FS6["Inference Utils (inference_utils.py)"]:::sampling
    end

    %% Training & Inference Scripts
    subgraph "Training & Inference Scripts"
        TS1["Shell Scripts Directory (scripts/)"]:::script
        TS2["Train Script (train.py)"]:::script
        TS3["Train BraTS Script (train_brats.py)"]:::script
        TS4["Sample Script (sample.py)"]:::script
        TS5["Sample BraTS Script (sample_brats.py)"]:::script
    end

    %% Utility Functions
    subgraph "Utility Functions"
        U1["Utilities Directory (utils/)"]:::utility
        U2["DType Utils (dtypes.py)"]:::utility
        U3["DType BraTS (dtypes_brats.py)"]:::utility
        U4["Lowpass Filter (lowpass_filter.py)"]:::utility
    end

    %% Data flow connections
    DP1 --> DP2
    DP2 --> DP3
    DP3 --> DC4
    DP3 --> DC5

    %% Integration with Training Scripts
    TS2 --> DC4
    TS3 --> DC5

    %% Diffusion Model to U-Net blocks
    DC4 --> DC6
    DC4 --> DC7
    DC5 --> DC6
    DC5 --> DC7

    %% Output flow into Fast Sampling Modules
    DC6 --> FS1
    DC7 --> FS1

    %% Fast Sampling internal flow
    FS1 --> FS2
    FS1 --> FS3
    FS1 --> FS4
    FS1 --> FS5
    FS1 --> FS6

    %% Training & Inference Scripts - additional orchestration
    TS1 --> TS2
    TS1 --> TS3
    TS1 --> TS4
    TS1 --> TS5

    %% Utility functions support various modules
    U1 --> DP2
    U1 --> DP3
    U1 --> DC2
    U1 --> FS6

    %% Classes for visual styling
    classDef data fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef model fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef sampling fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef script fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef utility fill:#DDA0DD,stroke:#000,stroke-width:2px;

    %% Click Events for Data Management & Preprocessing
    click DP1 "https://github.com/mobaidoctor/med-ddpm/tree/main/dataset/"
    click DP2 "https://github.com/mobaidoctor/med-ddpm/blob/main/dataset.py"
    click DP3 "https://github.com/mobaidoctor/med-ddpm/blob/main/preprocess_brats_data.py"

    %% Click Events for Diffusion Model Core
    click DC1 "https://github.com/mobaidoctor/med-ddpm/blob/main/diffusion_model/fp16_util.py"
    click DC2 "https://github.com/mobaidoctor/med-ddpm/blob/main/diffusion_model/logger.py"
    click DC3 "https://github.com/mobaidoctor/med-ddpm/blob/main/diffusion_model/modules.py"
    click DC4 "https://github.com/mobaidoctor/med-ddpm/blob/main/diffusion_model/trainer.py"
    click DC5 "https://github.com/mobaidoctor/med-ddpm/blob/main/diffusion_model/trainer_brats.py"
    click DC6 "https://github.com/mobaidoctor/med-ddpm/blob/main/diffusion_model/unet.py"
    click DC7 "https://github.com/mobaidoctor/med-ddpm/blob/main/diffusion_model/unet_brats.py"

    %% Click Events for Fast Sampling Modules
    click FS1 "https://github.com/mobaidoctor/med-ddpm/tree/main/fast_sampling/"
    click FS2 "https://github.com/mobaidoctor/med-ddpm/tree/main/fast_sampling/guided_diffusion/"
    click FS3 "https://github.com/mobaidoctor/med-ddpm/tree/main/fast_sampling/th_deis/"
    click FS4 "https://github.com/mobaidoctor/med-ddpm/blob/main/fast_sampling/inference_ddpm.py"
    click FS5 "https://github.com/mobaidoctor/med-ddpm/blob/main/fast_sampling/inference_deis.py"
    click FS6 "https://github.com/mobaidoctor/med-ddpm/blob/main/fast_sampling/inference_utils.py"

    %% Click Events for Training & Inference Scripts
    click TS1 "https://github.com/mobaidoctor/med-ddpm/tree/main/scripts/"
    click TS2 "https://github.com/mobaidoctor/med-ddpm/blob/main/train.py"
    click TS3 "https://github.com/mobaidoctor/med-ddpm/blob/main/train_brats.py"
    click TS4 "https://github.com/mobaidoctor/med-ddpm/blob/main/sample.py"
    click TS5 "https://github.com/mobaidoctor/med-ddpm/blob/main/sample_brats.py"

    %% Click Events for Utility Functions
    click U1 "https://github.com/mobaidoctor/med-ddpm/tree/main/utils/"
    click U2 "https://github.com/mobaidoctor/med-ddpm/blob/main/utils/dtypes.py"
    click U3 "https://github.com/mobaidoctor/med-ddpm/blob/main/utils/dtypes_brats.py"
    click U4 "https://github.com/mobaidoctor/med-ddpm/blob/main/utils/lowpass_filter.py"
```
