# jiamingkong/meshgraphnets_paddlepaddle architecture

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

- Interactive diagram: https://gitdiagram.com/jiamingkong/meshgraphnets_paddlepaddle
- Repository: https://github.com/jiamingkong/meshgraphnets_paddlepaddle

## Overview

##### Project Type and Purpose
- This is a machine-learning research reproduction project implemented in PaddlePaddle.
- It implements “Learning Mesh-Based Simulation with Graph Networks” for the `cylinder_flow` dataset.
- Core functionality: data preparation, graph-based model definition, training, inference (rollout), and visualization.

##### High-Level Architecture
a. Data Ingestion & Preparation
- Raw TFRecord files (DeepMind’s cylinder_flow)
- `parse_tfrecord.py` → converts TFRecords → HDF5/PKL format
b. Dataset & Pipeline
- `dataset/`
- `data.py` – Graph `Data` object and batching (`Collator`)
- `dataloader.py` – wraps Data into Paddle’s `DataLoader`
- `fpc.py` – (if used) feature preprocessing or additional I/O
- `transforms/` – Graph transforms: FaceToEdge, Cartesian, Distance, Scatter
c. Model Definition
- `model/`
- `blocks.py` – reusable GNN blocks (e.g., edge-update, node-update)
- `model.py` – full MeshGraphNet architecture
- `simulator.py` – rollout logic for multi-step prediction
d. Training Component
- `train.py`
- uses PaddlePaddle optimizers, loss functions
- writes model checkpoints under `checkpoint/`
e. Inference (Rollout)
- `rollout.py` – loads checkpoint, performs forward rollouts on test graphs
- outputs PKL files under `result/`
f. Visualization
- `visualize_cylinder_flow.py` – renders PKL results → MP4 videos
g. Utilities
- `utils/` – metrics (`average_meter.py`), noise injection, normalization, general helpers

##### Relationships and Data Flow
1. User downloads raw dataset → `data/cylinder_flow/*.tfrecord`
2. `parse_tfrecord.py` reads TFRecord → writes `data/cylinder_flow/datapkls/`
3. `train.py`
- Loads PKLs via `dataset` module
- Applies `transforms` → batched graph data
- Feeds into `model` → computes loss → optimizer step
- On intervals, saves parameters to `checkpoint/`
4. `rollout.py`
- Loads saved params → feeds initial graph(s) → uses `simulator.py` to unroll predictions → dumps PKL results
5. `visualize_cylinder_flow.py`
- Reads PKL results → Matplotlib/other tools to generate video

##### Architectural Patterns and Design Principles
- Modular separation: data, transforms, model, training, inference, visualization
- Graph-centric abstraction: custom `Data` and `Collator` mimic PyG behavior
- Pipeline pattern: clear stages (preprocess → dataset → transforms → model → postprocess)
- Checkpointing for reproducibility
- Single-process monolithic service rather than microservices

##### Technologies and Frameworks
- PaddlePaddle core for tensors, training, GPU support
- H5py or Pickle for on-disk graph data
- NumPy for transforms and batching
- Standard Python scripts for orchestration

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "1. Data Preparation"
        Raw["Raw TFRecord Files"]:::io
        Parser["parse_tfrecord.py"]:::io
        Processed["Processed Data (PKL/HDF5)"]:::io
    end

    subgraph "2. Data Pipeline"
        direction TB
        DSData["dataset/data.py"]:::compute
        DSDLoader["dataset/dataloader.py"]:::compute
        FPC["dataset/fpc.py"]:::compute
        subgraph "Graph Transforms"
            TF1["face_to_edge.py"]:::compute
            TF2["cartesian.py"]:::compute
            TF3["distance.py"]:::compute
            TF4["scatter.py"]:::compute
            TF5["basic.py"]:::compute
        end
        Collator["Collator & DataLoader"]:::compute
    end

    subgraph "3. Model"
        Blocks["model/blocks.py"]:::compute
        Arch["model/model.py"]:::compute
        Simulator["model/simulator.py"]:::compute
    end

    subgraph "4. Orchestration"
        Train["train.py"]:::orch
        Rollout["rollout.py"]:::orch
        Viz["visualize_cylinder_flow.py"]:::orch
    end

    subgraph "Storage"
        Checkpoint["checkpoint/"]:::io
        Results["result/"]:::io
    end

    subgraph "Utilities" 
        Avg["average_meter.py"]:::util
        Noise["noise.py"]:::util
        Norm["normalization.py"]:::util
        Utils["utils.py"]:::util
    end

    Raw -->|reads| Parser -->|writes| Processed
    Processed -->|loads| DSData -->|wraps| DSDLoader
    DSDLoader --> FPC
    FPC --> TF1 --> TF2 --> TF3 --> TF4 --> TF5 --> Collator
    Collator --> Arch
    Arch --> Blocks
    Arch --> Simulator
    Collator --> Train
    Arch --> Train
    Train -->|saves params| Checkpoint
    Checkpoint -->|loads params| Rollout
    Rollout -->|uses| Simulator
    Rollout -->|dumps results| Results
    Results -->|renders| Viz
    Avg --> Train
    Noise --> Train
    Norm --> Train
    Utils --> Train
    Avg --> Rollout
    Noise --> Rollout
    Norm --> Rollout
    Utils --> Rollout

    click Parser "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/parse_tfrecord.py"
    click DSData "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/dataset/data.py"
    click DSDLoader "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/dataset/dataloader.py"
    click FPC "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/dataset/fpc.py"
    click TF1 "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/transforms/face_to_edge.py"
    click TF2 "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/transforms/cartesian.py"
    click TF3 "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/transforms/distance.py"
    click TF4 "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/transforms/scatter.py"
    click TF5 "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/transforms/basic.py"
    click Blocks "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/model/blocks.py"
    click Arch "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/model/model.py"
    click Simulator "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/model/simulator.py"
    click Train "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/train.py"
    click Rollout "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/rollout.py"
    click Viz "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/visualize_cylinder_flow.py"
    click Checkpoint "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/tree/master/checkpoint/"
    click Avg "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/utils/average_meter.py"
    click Noise "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/utils/noise.py"
    click Norm "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/utils/normalization.py"
    click Utils "https://github.com/jiamingkong/meshgraphnets_paddlepaddle/blob/master/utils/utils.py"

    classDef io fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef compute fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef orch fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef util fill:#f5f5f5,stroke:#999,stroke-dasharray: 5 5
```
