# haozhongkai/gnot architecture

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

- Interactive diagram: https://gitdiagram.com/haozhongkai/gnot
- Repository: https://github.com/haozhongkai/gnot

## Overview

##### Project Type and Purpose
- The project implements GNOT—a General Neural Operator Transformer designed for operator learning, which is specifically useful for simulating physical fields like fluids, heat, and electromagnetism using neural networks.
- It is a deep learning research codebase that trains transformer-based models, with training scripts, model definitions, data utilities, and result visualization.

##### Analyzing the File Tree
- Top-level files like args.py, train.py, data_utils.py, utils.py, and visualize_result.py indicate scripts for configuration, training, data handling, utility functions, and visualization respectively.
- The models/ directory holds various model definitions: different transformer variants (cgpt, mgpt, mmgpt) and additional components (mlp, optimizer), suggesting a modular model architecture.
- The data_generation/ directory hints at functionalities for creating or augmenting datasets.
- The resources/ directory contains figures (e.g., fig1.png) and other assets used for documentation or possibly during training/inference.
- Other items like gnot_exp.sh are likely helper scripts to run experiments.

##### Insights from the README
- The README clearly describes GNOT’s capabilities, how to run training, the nature of the models, and detailed dataset formats. It mentions the architecture’s scalability, handling multiple inputs (irregular mesh, multi-scale objectives), and integration with real-world FEM/FVM simulation data.
- The README also explains the usage of different datasets and provides command-line examples, further clarifying the overall workflow—from loading dataset files to training and finally visualizing results.

a. Main Components to Include:
- Configuration & Entry Points:
- args.py: Contains hyperparameters and runtime configurations.
- Command-line interface via train.py.
- Data Handling:
- Data Generation: Represented by the data_generation/ module.
- Data Preprocessing/Loading: data_utils.py (including dataset formatting as described).
- External Dataset Storage: Mention the expected “data” directory structure (logs and checkpoints) as described in the README.
- Model Architectures:
- Models Layer: Encompassing the modules inside the models/ folder (cgpt, mgpt, mlp, mmgpt, optimizer) that define the neural architectures.
- Training Pipeline:
- Core training script (train.py): Handles the training loop, optimization (using optimizers like AdamW as referenced), and model saving/loading.
- Visualization & Results:
- visualize_result.py: For post-training visualization to validate model outputs.
- Utilities & External Scripts:
- utils.py: Provides additional helper functions.
- gnot_exp.sh: A shell script likely used to run experiments.

b. Relationships and Interactions:
- Data preprocessing then feeds the Training Pipeline (train.py) where the models, defined under models/, are instantiated.
- The configuration parameters from args.py direct the training process.
- The optimization process (utilizing modules like optimizer.py) is part of the training loop.
- Results from the training flow into the Visualization component.

c. Architectural Patterns and Technologies:
- Demonstrate the modular MVC-like separation: configuration (args.py), business logic (training in train.py and model definitions), and output (visualization).
- That the models have multiple variants (CGPT, MGPT, etc.), which implies extensibility and experimentation with different architectures.
- Point out that the system’s design supports scalability and complex inputs (irregular meshes, multi-input outputs).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Title
    A["Architecture of GNOT: General Neural Operator Transformer"]:::title

    %% Layer 1: External Resources
    subgraph "Layer 1: External Resources"
        ext["External Data (Datasets & Checkpoints)"]:::external
    end

    %% Layer 2: Configuration & Data Handling
    subgraph "Layer 2: Configuration & Data Handling"
        subgraph "Configuration"
            configArgs["args.py"]:::config
        end
        subgraph "Data Handling"
            dataGen["data_generation/"]:::data
            dataPre["data_utils.py"]:::data
        end
    end

    %% Layer 3: Training Pipeline & Model Definitions
    subgraph "Layer 3: Training & Models"
        train["train.py"]:::training
        subgraph "Model Definitions (Transformer-based)"
            modelCGPT["models/cgpt.py"]:::model
            modelMGPT["models/mgpt.py"]:::model
            modelMLP["models/mlp.py"]:::model
            modelMMGPT["models/mmgpt.py"]:::model
            modelOpt["models/optimizer.py"]:::model
        end
    end

    %% Layer 4: Visualization & Utilities
    subgraph "Layer 4: Visualization & Utilities"
        viz["visualize_result.py"]:::visualization
        util["utils.py"]:::utility
        exp["gnot_exp.sh"]:::utility
    end

    %% Connections - Data Flow
    ext -->|"raw_data"| dataGen
    dataGen -->|"processed_data"| dataPre

    %% Connections - Configuration and Training
    configArgs -->|"config_params"| train
    dataPre -->|"preprocessed_data"| train

    %% Connections - Training to Model Definitions
    train -->|"instantiates"| modelCGPT
    train -->|"instantiates"| modelMGPT
    train -->|"instantiates"| modelMLP
    train -->|"instantiates"| modelMMGPT
    train -->|"optimizer"| modelOpt

    %% Connections - Training to Visualization
    train -->|"results_output"| viz

    %% Connections - Support Utilities
    util -->|"helper_functions"| train
    exp -->|"experiment_trigger"| train

    %% Classes and Styles
    classDef title fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef config fill:#E1F5FE,stroke:#0277BD,stroke-width:2px;
    classDef data fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef training fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef model fill:#D1C4E9,stroke:#673AB7,stroke-width:2px;
    classDef visualization fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef utility fill:#F0F4C3,stroke:#827717,stroke-width:2px;
    classDef external fill:#CFD8DC,stroke:#37474F,stroke-width:2px;

    %% Click Events
    click configArgs "https://github.com/haozhongkai/gnot/blob/master/args.py"
    click train "https://github.com/haozhongkai/gnot/blob/master/train.py"
    click dataGen "https://github.com/haozhongkai/gnot/tree/master/data_generation/"
    click dataPre "https://github.com/haozhongkai/gnot/blob/master/data_utils.py"
    click modelCGPT "https://github.com/haozhongkai/gnot/blob/master/models/cgpt.py"
    click modelMGPT "https://github.com/haozhongkai/gnot/blob/master/models/mgpt.py"
    click modelMLP "https://github.com/haozhongkai/gnot/blob/master/models/mlp.py"
    click modelMMGPT "https://github.com/haozhongkai/gnot/blob/master/models/mmgpt.py"
    click modelOpt "https://github.com/haozhongkai/gnot/blob/master/models/optimizer.py"
    click viz "https://github.com/haozhongkai/gnot/blob/master/visualize_result.py"
    click util "https://github.com/haozhongkai/gnot/blob/master/utils.py"
    click exp "https://github.com/haozhongkai/gnot/blob/master/gnot_exp.sh"
```
