# romaincorbel/airfrans architecture

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

- Interactive diagram: https://gitdiagram.com/romaincorbel/airfrans
- Repository: https://github.com/romaincorbel/airfrans

## Overview

##### Project Type and Purpose
- Type: A research-oriented Python ML framework for training and evaluating graph/neural models on the AirfRANS CFD dataset.
- Purpose: Ingest CFD data, train multiple model architectures (MLP, GraphSAGE, PointNet, GUNet) on various tasks, compute metrics, store scores, and produce visualizations.

##### File Structure
- Top-level scripts
- main.py: CLI entry for training, scoring
- train.py: orchestration of training loops
- dataset.py, naca_generator.py, reorganize.py: data ingestion & preprocessing
- metrics.py, metrics_NACA.py: metric computations & logging
- get_results.py: collate scores from JSON into summaries
- params.yaml: hyperparameters & task configurations
- Directories
- models/: implementations of the four architectures
- metrics/: training logs and plots generated during training
- scores/: JSON score outputs for each task (full, scarce, reynolds, aoa)
- notebooks (.ipynb): dataset_stats.ipynb for data exploration, visualization.ipynb for post-hoc plots

##### README Insights
- CLI usage patterns (main.py arguments)
- Required external dataset folder “Dataset/”
- Output locations: metrics/ for training logs, scores/TASK/ for evaluation results, notebooks for stats and visualizations

##### Main Components & Their Relationships
a. CLI & Config
- User invokes main.py with arguments + params.yaml
b. Data Ingestion & Preprocessing
- naca_generator.py: synthesize NACA airfoil parameter sets
- reorganize.py: restructure raw dataset
- dataset.py: PyTorch Dataset object that loads data from Dataset/
c. Model Layer
- models/MLP.py, GraphSAGE.py, PointNet.py, GUNet.py: define forward pass & architecture
d. Training Engine
- train.py: batches data, calls model, backpropagates, logs metrics via metrics.py
e. Metrics & Logging
- metrics.py & metrics_NACA.py: compute losses, force-coefficient metrics
- metrics/ folder: store logs, plots per epoch
f. Evaluation & Scoring
- main.py with “-s 1” or get_results.py: compute test-set metrics, write JSON in scores/TASK/
g. Visualization & Analysis
- visualization.ipynb: generates plots of force coefficients, boundary layers
- dataset_stats.ipynb: generates basic dataset statistics

##### Architectural Patterns & Principles
- Modular separation: data / model / training / evaluation / visualization
- Config-driven: params.yaml lets you tweak hyperparameters and task type
- Extensible: adding a new model means dropping its .py into models/ and invoking via CLI
- File-based pipelines: input raw data → preprocess → training → metric logs → score JSON → notebook visualization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI and Config
    CLI["CLI Interface\n(main.py)"]:::cli
    Config["Configuration Store\n(params.yaml)"]:::config

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawData["Raw Dataset\n(Dataset/)"]:::data
        Preprocess["Preprocessing Scripts\n(naca_generator.py, reorganize.py)"]:::data
        DatasetLoader["PyTorch Dataset Loader\n(dataset.py)"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        MLP["Multi-Layer Perceptron\n(models/MLP.py)"]:::model_training
        GraphSAGE["GraphSAGE Model\n(models/GraphSAGE.py)"]:::model_training
        PointNet["PointNet Model\n(models/PointNet.py)"]:::model_training
        GUNet["GUNet Model\n(models/GUNet.py)"]:::model_training
        NNUtils["Base Model Utilities\n(models/NN.py)"]:::model_training
    end

    %% Training Engine
    subgraph "Training Engine"
        direction TB
        Train["Training Orchestration\n(train.py)"]:::model_training
        MetricsCore["Metrics Core\n(metrics.py)"]:::model_training
        MetricsNACA["NACA Metrics\n(metrics_NACA.py)"]:::model_training
    end

    %% Metrics Store
    MetricsStore["Metrics Store\n(metrics/)"]:::model_training

    %% Evaluation & Scoring
    subgraph "Evaluation & Scoring"
        direction TB
        Scoring["CLI-driven Scoring\n(main.py -s)"]:::eval
        GetResults["Results Aggregator\n(get_results.py)"]:::eval
    end

    %% Scores Store
    subgraph "Scores Store"
        direction TB
        ScoresFull["Full Eval Scores\n(scores/full/)"]:::eval
        ScoresScarce["Scarce-data Scores\n(scores/scarce/)"]:::eval
        ScoresReynolds["Reynolds Scores\n(scores/reynolds/)"]:::eval
        ScoresAOA["AOA Scores\n(scores/aoa/)"]:::eval
    end

    %% Visualization & Analysis
    subgraph "Visualization & Analysis"
        direction TB
        Stats["Dataset Statistics\n(dataset_stats.ipynb)"]:::viz
        Viz["Post-training Visualizations\n(visualization.ipynb)"]:::viz
    end

    %% Connections
    CLI --> Config
    CLI --> Preprocess
    CLI --> DatasetLoader
    Preprocess --> DatasetLoader
    DatasetLoader --> MLP
    DatasetLoader --> GraphSAGE
    DatasetLoader --> PointNet
    DatasetLoader --> GUNet
    DatasetLoader --> NNUtils
    MLP --> Train
    GraphSAGE --> Train
    PointNet --> Train
    GUNet --> Train
    NNUtils --> Train
    Train --> MetricsCore
    Train --> MetricsNACA
    MetricsCore --> MetricsStore
    MetricsNACA --> MetricsStore
    CLI --> Scoring
    Scoring --> GetResults
    GetResults --> ScoresFull
    GetResults --> ScoresScarce
    GetResults --> ScoresReynolds
    GetResults --> ScoresAOA
    MetricsStore --> Stats
    MetricsStore --> Viz
    ScoresFull --> Stats
    ScoresScarce --> Stats
    ScoresReynolds --> Stats
    ScoresAOA --> Stats
    ScoresFull --> Viz
    ScoresScarce --> Viz
    ScoresReynolds --> Viz
    ScoresAOA --> Viz

    %% Click Events
    click CLI "https://github.com/romaincorbel/airfrans/blob/main/main.py"
    click Config "https://github.com/romaincorbel/airfrans/blob/main/params.yaml"
    click NACAgen "https://github.com/romaincorbel/airfrans/blob/main/naca_generator.py"
    click Reorganize "https://github.com/romaincorbel/airfrans/blob/main/reorganize.py"
    click DatasetLoader "https://github.com/romaincorbel/airfrans/blob/main/dataset.py"
    click MLP "https://github.com/romaincorbel/airfrans/blob/main/models/MLP.py"
    click GraphSAGE "https://github.com/romaincorbel/airfrans/blob/main/models/GraphSAGE.py"
    click PointNet "https://github.com/romaincorbel/airfrans/blob/main/models/PointNet.py"
    click GUNet "https://github.com/romaincorbel/airfrans/blob/main/models/GUNet.py"
    click NNUtils "https://github.com/romaincorbel/airfrans/blob/main/models/NN.py"
    click Train "https://github.com/romaincorbel/airfrans/blob/main/train.py"
    click MetricsCore "https://github.com/romaincorbel/airfrans/blob/main/metrics.py"
    click MetricsNACA "https://github.com/romaincorbel/airfrans/blob/main/metrics_NACA.py"
    click MetricsStore "https://github.com/romaincorbel/airfrans/tree/main/metrics/"
    click GetResults "https://github.com/romaincorbel/airfrans/blob/main/get_results.py"
    click ScoresFull "https://github.com/romaincorbel/airfrans/tree/main/scores/full/"
    click ScoresScarce "https://github.com/romaincorbel/airfrans/tree/main/scores/scarce/"
    click ScoresReynolds "https://github.com/romaincorbel/airfrans/tree/main/scores/reynolds/"
    click ScoresAOA "https://github.com/romaincorbel/airfrans/tree/main/scores/aoa/"
    click Stats "https://github.com/romaincorbel/airfrans/blob/main/dataset_stats.ipynb"
    click Viz "https://github.com/romaincorbel/airfrans/blob/main/visualization.ipynb"

    %% Styles
    classDef cli fill:#F0F8FF,stroke:#000,stroke-width:1px
    classDef config fill:#E0E0E0,stroke:#000,stroke-width:1px
    classDef data fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef model_training fill:#90EE90,stroke:#000,stroke-width:1px
    classDef eval fill:#FFA500,stroke:#000,stroke-width:1px
    classDef viz fill:#DDA0DD,stroke:#000,stroke-width:1px
```
