# panda000001/windassimilation architecture

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

- Interactive diagram: https://gitdiagram.com/panda000001/windassimilation
- Repository: https://github.com/panda000001/windassimilation

## Overview

##### Project Type and Purpose
- This is a research-oriented machine learning pipeline, not a web or mobile app.
- It integrates Computational Fluid Dynamics (CFD) simulation (via SOWFA), data ingestion, PINN training (PyTorch), hyperparameter search (Weights & Biases), inference/reconstruction, transfer learning, and visualization.

##### File Structure
- Top-level directories and files:
- SOWFA.script: contains CFD case setup, mesh definition, boundary/initial conditions, solver control dictionaries, mesh refinement, sampling plans, and job submission scripts (sub1_pre.sh, sub2_run.sh).
- Sensor.U8.XY.h5: HDF5 outputs from SOWFA containing raw flow data for various probes and lidar measurements.
- Visualization: Jupyter notebooks or static assets for figures and GIFs.
- Python scripts:
- read_data.py: ingests and preprocesses CFD/HDF5 data.
- pinn_model.py: defines the PINN architecture and physics constraints in PyTorch.
- main.py: orchestrates training loop, logging, hyperparameter search (wandb).
- pred_write.py: runs inference to reconstruct flow fields and writes HDF5 outputs.
- transfer.py: implements online transfer learning for real-time data assimilation.
- requirement.txt: lists dependencies (PyTorch, h5py, wandb, etc.)

##### Extract Insights from README
- Workflow stages:
a. Generate or use pre-computed CFD data via SOWFA.script.
b. Read and preprocess data (read_data.py).
c. Train PINN with physics constraints (main.py + pinn_model.py), using wandb for HPO.
d. Reconstruct or predict flow fields (pred_write.py).
e. Deploy and continually fine-tune with transfer learning on incoming measurements (transfer.py).
- External integrations: SOWFA CFD engine, HDF5 data format, wandb service.

##### Main Components and Their Interactions
- Component A: SOWFA Simulation Subsystem
- Generates ground-truth flow fields.
- Outputs HDF5 files under Sensor.U8.XY.h5.
- Component B: Data Ingestion & Preprocessing
- read_data.py reads HDF5, extracts probe/velocity/pressure fields, builds tensors.
- Component C: PINN Model Definition
- pinn_model.py defines neural network layers and physics‐based loss components (RANS equations, eddy viscosity).
- Component D: Training Orchestrator
- main.py sets up training loops, optimizer, scheduling, wandb logging and HPO.
- Component E: Inference & Reconstruction
- pred_write.py loads trained model, runs on spatial grid or new data, writes reconstructed fields to HDF5.
- Component F: Transfer Learning Module
- transfer.py ingest streaming data, fine-tunes the pre-trained PINN for online deployment.
- Component G: Results Storage & Visualization
- Visualization assets generate static plots and animations (GIFs) from HDF5 results.
- External Service: wandb for hyperparameter search, experiment tracking.

##### Relationships and Data Flow
- SOWFA.script → HDF5 Data Store
- HDF5 → read_data.py → Tensor Datasets
- Datasets → main.py + pinn_model.py → Trained Model
- Trained Model → pred_write.py → Reconstructed HDF5
- Streaming Measurements → transfer.py + Trained Model → Updated Model → New HDF5
- All models, metrics, logs → wandb
- Final HDF5 → Visualization tools → Figures/GIFs

##### Architectural Patterns and Principles
- Pipeline Pattern: clear sequential stages from data generation to visualization.
- Modular Design: separate scripts for ingestion, model definition, training, inference, transfer learning.
- Single Responsibility: each component has one well-defined role.
- Extensibility: new measurement types or physics constraints can be added by extending read_data or pinn_model.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Generation"
        SOWFA["SOWFA.script"]:::dataSource
    end
    SOWFA -->|HDF5| HDF5Store(("Sensor.U8.XY.h5")):::dataStore
    click SOWFA "https://github.com/panda000001/windassimilation/tree/main/SOWFA.script/"
    click HDF5Store "https://github.com/panda000001/windassimilation/blob/main/Sensor.U8.XY.h5"

    subgraph "Data Ingestion & Preprocessing"
        Read["read_data.py"]:::processing
    end
    click Read "https://github.com/panda000001/windassimilation/blob/main/read_data.py"
    HDF5Store -->|HDF5| Read -->|tensors| Dataset(("Tensor Datasets")):::dataStore

    subgraph "PINN Model Definition & Training"
        ModelDef["pinn_model.py"]:::processing
        Trainer["main.py"]:::processing
    end
    click ModelDef "https://github.com/panda000001/windassimilation/blob/main/pinn_model.py"
    click Trainer "https://github.com/panda000001/windassimilation/blob/main/main.py"
    Dataset -->|tensors| ModelDef -->|model architecture| Trainer
    Trainer -->|model weights| TrainedModel(("Trained PINN Model")):::dataStore

    subgraph "Inference & Reconstruction"
        Infer["pred_write.py"]:::processing
    end
    click Infer "https://github.com/panda000001/windassimilation/blob/main/pred_write.py"
    TrainedModel -->|model weights| Infer -->|HDF5| ReconStore(("Reconstructed.h5")):::dataStore

    subgraph "Transfer Learning (Streaming)"
        Transfer["transfer.py"]:::processing
    end
    click Transfer "https://github.com/panda000001/windassimilation/blob/main/transfer.py"
    Streaming(("Streaming Measurements")):::dataSource
    Streaming -->|stream| Transfer -->|updated weights| TrainedModel
    Transfer -->|HDF5| NewRecon(("Updated_Recon.h5")):::dataStore

    subgraph "Results Visualization"
        Viz["Visualization/"]:::viz
    end
    click Viz "https://github.com/panda000001/windassimilation/tree/main/Visualization/"
    ReconStore -->|HDF5| Viz
    NewRecon -->|HDF5| Viz

    External["wandb"]:::external
    Trainer -->|logs,metrics,HPO| External
    Dataset -->|HPO configs| External

    classDef dataSource fill:#D0E6FF,stroke:#0366d6;
    classDef dataStore fill:#DFF2BF,stroke:#4F8A10;
    classDef processing fill:#FFF2CC,stroke:#B8860B;
    classDef external fill:#FFD2D2,stroke:#D32F2F;
    classDef viz fill:#E6E6FA,stroke:#9370DB;
```
