# simonzeng7108/rbf-pinn architecture

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

- Interactive diagram: https://gitdiagram.com/simonzeng7108/rbf-pinn
- Repository: https://github.com/simonzeng7108/rbf-pinn

## Overview

##### Project Type and Purpose
- This is an open-source scientific framework (“RBF-PINN”) for enhancing Physics-Informed Neural Networks with a Radial Basis Function (RBF) feature-mapping layer.
- It provides nine canonical PDE experiments (Wave 1D, Diffusion 1D, Heat2d multiscale, Poisson 2D, Burgers 1D, Steady NS, Inverse Burgers, Inverse Lorenz, Poisson Nd) plus ablation studies under “Ablation study/…”.

##### File-Structure Analysis
- Top-level directories:
- `1_Wave_1D` … `9_PoissonNd` – each directory is a self-contained experiment.
- `Ablation study/…` – nested copies of experiments for compact-support and surjectivity ablations.
- `Figs` (figures), `README.md`.
- `data/` (raw PDE data files)
- `dataset.py` (data loader & sampling)
- `RBF_kernels.py` + `Utils.py` (preprocessing, feature-mapping functions)
- `network.py` (PINN architecture with feature-mapping layer)
- `trainer.py` (training loop, PINN residual & boundary losses)
- `main.py` (CLI/script entry point tying all components)
- `plot_*.py` (visualization)
- `logs/models/` (serialized PyTorch models)
- `results/` (metrics, error analyses, PDFs)

##### Core Components
a. Data Layer
– PDE data files → `dataset.py` (sampling collocation, boundary points)
b. Preprocessing & Feature Mapping
– `Utils.py`, `RBF_kernels.py` → compute RBF feature‐map of coordinates
c. Neural Network (PINN)
– `network.py` defines feed-forward NN + feature mapping layer
d. Training Engine
– `trainer.py` sets up loss (physics residual + data/inverse losses), optimizer, epoch loop
e. Orchestration & CLI
– `main.py` parses config/args, instantiates Data → Model → Trainer, triggers training
f. Logging & Persistence
– `logs/models/*.pt`
– optional `logs/loss.pkl`, `running_result.txt` (in ablation)
g. Results & Visualization
– `results/` (plots, numeric summaries)
– `plot_*.py` generates figures from trained models

##### Interactions & Data Flow
- Data files → `dataset` → (sampled batches) → feature mapping → forward pass in `network`
- Network outputs → residual/loss computed in `trainer` → backprop → updated network → logs/model checkpoints
- After training completes (or per epoch), logs are written, and `plot_*.py` or `main.py` post-processing dumps results into `results/`.
- Ablation studies reuse the same pipeline but swap or extend `RBF_kernels.py` or network hyperparameters.

##### Architectural Patterns & Design Principles
- Modular “experiment‐per‐directory” pattern: each PDE problem is a plug-and-play module conforming to the same interface.
- Pipeline pattern: Data → Preprocessing → Model → Trainer → Logger → Visualizer.
- Extensibility: new PDE cases or feature mappings can be added by copying one directory template.
- Separation of concerns: data loading, feature mapping, model definition, training logic, and visualization are all decoupled.

##### External Dependencies & Technologies
- PyTorch (torch==2.0)
- Numpy, Matplotlib
- pyDOE (for sampling if used)
- torchsummary for model introspection

##### Final Checklist
- [ ] Annotations for key libraries (PyTorch, Numpy, etc.)
- [ ] Collapsed view for “nine experiment modules” plus one “ablation” module

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration
    Orchestrator["Orchestration & CLI\n(main.py)"]:::orchestrator

    subgraph "Per-Problem Module (e.g., 1_Wave_1D)"
        DataLayer["Data Layer\n(dataset.py, data/)"]:::data
        FeatureMapping["Preprocessing &\nFeature Mapping\n(RBF_kernels.py, Utils.py)"]:::feature
        PINN["PINN Model\n(network.py)"]:::model
        Trainer["Training Engine\n(trainer.py)"]:::trainer
        Logger["Logger & Persistence\n(RBF.pt)"]:::logger
        Viz["Visualization & Results\n(plot_wave.py, results/)"]:::viz
    end

    subgraph "Ablation Studies"
        Ablation1["Compact Support Variant"]:::feature
        Ablation2["Surjectivity Variant"]:::feature
        Ablation1 --> FeatureMapping
        Ablation2 --> FeatureMapping
    end

    %% Connections
    Orchestrator -->|“initialize pipeline”| DataLayer
    Orchestrator -->|“trigger training”| Trainer

    DataLayer -->|"sample collocation points"| FeatureMapping
    FeatureMapping -->|"compute RBF features"| PINN
    PINN -->|"forward pass"| Trainer
    Trainer -->|"compute physics residual"| Trainer
    Trainer -->|"checkpoint model"| Logger
    Trainer -->|"log metrics"| Logger
    Logger -->|"store metrics"| Viz
    Viz -->|"generate plots"| Viz

    %% Click Events
    click DataLayer "https://github.com/simonzeng7108/rbf-pinn/blob/master/1_Wave_1D/dataset.py"
    click DataLayer "https://github.com/simonzeng7108/rbf-pinn/tree/master/1_Wave_1D/data/"
    click FeatureMapping "https://github.com/simonzeng7108/rbf-pinn/blob/master/1_Wave_1D/RBF_kernels.py"
    click FeatureMapping "https://github.com/simonzeng7108/rbf-pinn/blob/master/1_Wave_1D/Utils.py"
    click PINN "https://github.com/simonzeng7108/rbf-pinn/blob/master/1_Wave_1D/network.py"
    click Trainer "https://github.com/simonzeng7108/rbf-pinn/blob/master/1_Wave_1D/trainer.py"
    click Orchestrator "https://github.com/simonzeng7108/rbf-pinn/blob/master/1_Wave_1D/main.py"
    click Logger "https://github.com/simonzeng7108/rbf-pinn/blob/master/1_Wave_1D/logs/models/RBF.pt"
    click Viz "https://github.com/simonzeng7108/rbf-pinn/tree/master/1_Wave_1D/results/"
    click Viz "https://github.com/simonzeng7108/rbf-pinn/blob/master/1_Wave_1D/plot_wave.py"

    %% Styles
    classDef data fill:#a2cffe,stroke:#1f77b4,color:#000;
    classDef feature fill:#c2f0f4,stroke:#17a2b8,color:#000;
    classDef model fill:#d4f7d4,stroke:#2ca02c,color:#000;
    classDef trainer fill:#ffe5b4,stroke:#ff7f0e,color:#000;
    classDef logger fill:#fff9b6,stroke:#bcbd22,color:#000;
    classDef viz fill:#e4d5f9,stroke:#9467bd,color:#000;
    classDef orchestrator fill:#dddddd,stroke:#7f7f7f,color:#000;
```
