# francoismaze/topodiff architecture

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

- Interactive diagram: https://gitdiagram.com/francoismaze/topodiff
- Repository: https://github.com/francoismaze/topodiff

## Overview

##### Project type and purpose
- From the README and the file tree, this is a scientific/ML research codebase for “TopoDiff, a guided diffusion model for Topology Optimization.”
- It provides three independent training pipelines (diffusion model, compliance regressor, floating material classifier), sampling from the diffusion model, and analysis of results.

##### File structure
- Top-level:
- notebooks (1_diffusion_model_training.ipynb, …, 5_analysis.ipynb) for interactive training, sampling, analysis
- scripts/ – main CLI scripts for training and sampling (classifier_floating_mat_train.py, regressor_train.py, image_train.py, topodiff_sample.py, etc.)
- preprocessing/ – notebook for generating physical fields features
- topodiff/ – core Python package implementing models, data loaders, training utilities, diffusion algorithms, logging, FEA integration
- data/ (empty) – placeholder for datasets
- checkpoints/ (empty) – placeholder for saved model weights
- fem_files/ – temporary files created by the external FEA solver during sampling/analysis
- setup.py – package installer
- Within topodiff/:
- model definitions (unet.py, nn.py)
- diffusion core (gaussian_diffusion.py, resample.py, respace.py)
- data loaders (image_datasets_diffusion_model.py, image_datasets_regressor.py, image_datasets_floating_mat_classifier.py)
- training & scripting utilities (train_util.py, script_util.py, logger.py)
- mixed‐precision and distributed training helpers (fp16_util.py, dist_util.py)
- analysis tools (topodiff_analysis.py)
- input dataset definitions (cons_input_datasets.py)

##### README for additional insights
- Confirms three independent model trainings and sampling pipeline
- Dependencies installed via `pip install -e .` (likely PyTorch, NumPy, etc.)
- External datasets and checkpoints downloaded separately
- Interaction with an external FEA solver through fem_files/

##### Main components
a. Data Layer
- Datasets (dataset_1_diff, dataset_2_reg, dataset_3_class) in `/data/`
- Checkpoints in `/checkpoints/`
b. Preprocessing
- Physical field generation (preprocessing/physical_fields_generation.ipynb)
c. Core Library (topodiff package)
- Model definitions (UNet, diffusion operators)
- Data loaders
- Training utilities (mixed precision, distributed)
- Loss functions
- Logging
- Analysis module
d. Training Pipelines
- Diffusion model training (scripts/image_train.py or notebook)
- Compliance regressor training (scripts/regressor_train.py)
- Floating material classifier training (scripts/classifier_floating_mat_train.py)
e. Sampling Pipeline
- topodiff_sample script/notebook invokes the diffusion sampler and calls FEA solver via fem_files/
f. Analysis
- Notebooks and topodiff_analysis.py produce metrics, plots, comparison to GAN baselines
g. External Services
- FEA solver (external executable reading/writing fem_files/)
- Dataset & checkpoint download URLs

##### Architectural patterns & design principles
- Modular Python package (`topodiff`) separated from CLI scripts and notebooks
- Clear separation of concerns: data loading, model definition, training utilities, analysis
- Reusable core library for diffusion operations and U‑Net architecture
- Independent pipelines for three models facilitating parallel development and testing

##### Technologies & frameworks
- Python packaging (setup.py)
- PyTorch (implied by mixed‐precision and distributed utilities)
- Jupyter notebooks for interactive usage
- Standard logging
- External FEA solver interfaced via file I/O

##### Final advice
- Explicitly show that each of the three training pipelines is independent but shares the same core library.
- Don’t over‐optimize the visual; clarity of components and flows is paramount.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        Data["Datasets (/data/)"]:::data
        Checkpoints["Checkpoints (/checkpoints/)"]:::data
    end

    %% Preprocessing
    subgraph "Preprocessing"
        Pre["Physical Fields Generation Notebook"]:::preprocess
    end

    %% Core Library
    subgraph "Core Library (topodiff)"
        subgraph "Model Definitions"
            UNET["unet.py"]:::core
            NN["nn.py"]:::core
        end
        subgraph "Diffusion Core"
            GD["gaussian_diffusion.py"]:::core
            RESAMP["resample.py"]:::core
            RESPACE["respace.py"]:::core
        end
        subgraph "Data Loaders"
            D1["image_datasets_diffusion_model.py"]:::core
            D2["image_datasets_regressor.py"]:::core
            D3["image_datasets_floating_mat_classifier.py"]:::core
            CONS["cons_input_datasets.py"]:::core
        end
        subgraph "Utilities"
            TU["train_util.py"]:::core
            SU["script_util.py"]:::core
            LOG["logger.py"]:::core
        end
        subgraph "Training Helpers"
            FP16["fp16_util.py"]:::core
            DIST["dist_util.py"]:::core
        end
        LOSS["losses.py"]:::core
        ANALYSIS_MOD["topodiff_analysis.py"]:::core
        Setup["setup.py"]:::core
    end

    %% Training Pipelines
    subgraph "Training Pipelines"
        IMG["scripts/image_train.py"]:::train
        REG["scripts/regressor_train.py"]:::train
        CLA["scripts/classifier_floating_mat_train.py"]:::train
    end

    %% Sampling Pipeline
    subgraph "Sampling Pipeline"
        SAMPLER["scripts/topodiff_sample.py"]:::sampling
        NB4["4_TopoDiff_sample.ipynb"]:::sampling
    end

    %% Analysis
    subgraph "Analysis"
        NB5["5_analysis.ipynb"]:::analysis
    end

    %% External
    FEA["External FEA Solver"]:::external

    %% Relationships
    Data -->|provides raw data| D1
    Data -->|provides raw data| D2
    Data -->|provides raw data| D3
    Data --> Pre
    Pre -->|outputs features| D1
    D1 & D2 & D3 & CONS -->|loaded by| IMG
    D1 & D2 & D3 & CONS -->|loaded by| REG
    D1 & D2 & D3 & CONS -->|loaded by| CLA
    IMG -->|uses| UNET
    IMG -->|uses| GD
    IMG -->|uses| TU
    REG -->|uses| LOG
    CLA -->|uses| FP16
    IMG & REG & CLA -->|produce| Checkpoints
    IMG & REG & CLA -->|log via| LOG
    Checkpoints -->|consumed by| SAMPLER
    SAMPLER -->|writes fem_files/| FEA
    FEA -->|produces results| NB4
    NB4 -->|analysis uses| ANALYSIS_MOD
    NB5 -->|uses| ANALYSIS_MOD
    NB5 -->|reads| Checkpoints
    NB5 -->|reads| Results

    %% Click Events
    click Data "https://github.com/francoismaze/topodiff/tree/main//data/"
    click Checkpoints "https://github.com/francoismaze/topodiff/tree/main//checkpoints/"
    click Pre "https://github.com/francoismaze/topodiff/blob/main/preprocessing/physical_fields_generation.ipynb"
    click UNET "https://github.com/francoismaze/topodiff/blob/main/topodiff/unet.py"
    click NN "https://github.com/francoismaze/topodiff/blob/main/topodiff/nn.py"
    click GD "https://github.com/francoismaze/topodiff/blob/main/topodiff/gaussian_diffusion.py"
    click RESAMP "https://github.com/francoismaze/topodiff/blob/main/topodiff/resample.py"
    click RESPACE "https://github.com/francoismaze/topodiff/blob/main/topodiff/respace.py"
    click D1 "https://github.com/francoismaze/topodiff/blob/main/topodiff/image_datasets_diffusion_model.py"
    click D2 "https://github.com/francoismaze/topodiff/blob/main/topodiff/image_datasets_regressor.py"
    click D3 "https://github.com/francoismaze/topodiff/blob/main/topodiff/image_datasets_floating_mat_classifier.py"
    click CONS "https://github.com/francoismaze/topodiff/blob/main/topodiff/cons_input_datasets.py"
    click TU "https://github.com/francoismaze/topodiff/blob/main/topodiff/train_util.py"
    click SU "https://github.com/francoismaze/topodiff/blob/main/topodiff/script_util.py"
    click LOG "https://github.com/francoismaze/topodiff/blob/main/topodiff/logger.py"
    click FP16 "https://github.com/francoismaze/topodiff/blob/main/topodiff/fp16_util.py"
    click DIST "https://github.com/francoismaze/topodiff/blob/main/topodiff/dist_util.py"
    click LOSS "https://github.com/francoismaze/topodiff/blob/main/topodiff/losses.py"
    click ANALYSIS_MOD "https://github.com/francoismaze/topodiff/blob/main/topodiff/topodiff_analysis.py"
    click Setup "https://github.com/francoismaze/topodiff/blob/main/setup.py"
    click IMG "https://github.com/francoismaze/topodiff/blob/main/scripts/image_train.py"
    click REG "https://github.com/francoismaze/topodiff/blob/main/scripts/regressor_train.py"
    click CLA "https://github.com/francoismaze/topodiff/blob/main/scripts/classifier_floating_mat_train.py"
    click SAMPLER "https://github.com/francoismaze/topodiff/blob/main/scripts/topodiff_sample.py"
    click NB4 "https://github.com/francoismaze/topodiff/blob/main/4_TopoDiff_sample.ipynb"
    click NB5 "https://github.com/francoismaze/topodiff/blob/main/5_analysis.ipynb"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef preprocess fill:#B3E5FC,stroke:#0288D1,color:#01579B
    classDef core fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef train fill:#C8E6C9,stroke:#43A047,color:#1B5E20
    classDef sampling fill:#B2DFDB,stroke:#009688,color:#004D40
    classDef analysis fill:#FFF9C4,stroke:#FBC02D,color:#F57F17
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#4A148C
```
