# a-tierz/local-thermodynamicsgnn architecture

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

- Interactive diagram: https://gitdiagram.com/a-tierz/local-thermodynamicsgnn
- Repository: https://github.com/a-tierz/local-thermodynamicsgnn

## Overview

##### Project Type and Purpose
- This is not a typical full-stack web application but rather a scientific simulation and machine learning framework integrating advanced physics-informed neural network components.
- Its goal is to provide a scalable, locally informed GNN architecture that respects thermodynamic laws (i.e. generically enforcing the first and second laws via the GENERIC formalism) to improve prediction accuracy in solid and fluid mechanics applications.

##### Analyzing the File Structure
- Top-level files include the research assets like LICENSE, README, and requirements.txt.
- The “data” directory holds datasets, JSON configuration files (e.g., dataset_Beam3D.json), pretrained weights, and resource images—for both visualization of results and as inputs to the pipelines.
- The “src” directory contains the main source code:
- Callbacks (src/callbacks.py) that possibly manage training events.
- Data loader (src/dataLoader/dataset.py) for feeding in the experiments’ datasets.
- The main GNN implementation (src/gnn_nodal.py) which is at the core of the methodology.
- Supporting modules including evaluation (src/evaluate.py) and utility functions/plots (src/utils/plots.py and src/utils/utils.py).
- Scripts at the root level (main_train.py, main_inference.py) serve as entry points to either train the model or run inference using the provided configuration files.

##### Main Components
a. Data & Configuration:
- Dataset Files: Show a block representing the “data” directory with sub-blocks for datasets (Beam3D_train.pt, etc.), JSON configuration files, weights, and resource/visualization assets.
b. Preprocessing and Utilities:
- A block for the data loading module (src/dataLoader/dataset.py) that takes in dataset and JSON config files.
- Another block covering utility functions and plotting (src/utils/).
c. Model Architecture:
- GNN implementation (src/gnn_nodal.py) which embodies the “local TIGNN” model that enforces thermodynamic constraints.
- Encode–process–decode pipeline, either as separate stages within the model or annotating the corresponding processing within the same block.
d. Training Pipeline:
- Main_train.py as the orchestrator of training, linked with callbacks (src/callbacks.py) and evaluation (src/evaluate.py) modules.
e. Inference Pipeline:
f. Monitoring/Experiment Tracking:
- Given the instructions for Weights & Biases installation, include an optional block or annotation for experiment tracking and logging (external services integration).

##### Interactions and Data Flow
- From this core module, branch out to evaluation and visualization components (src/evaluate.py and src/utils/plots.py) that help in monitoring performance during training and inference.
- Feedback loop from the training pipeline (via callbacks and logging) into model updates.

##### Architectural Patterns and Design Principles
- Stress the importance of the local enforcement of thermodynamic consistency without reassembling global matrices, which preserves the nodal integrity.
- Separation of concerns: distinct modules for data processing, model computation (GNN), training loops, and evaluation.
- Annotations that identify the use of “physics-informed bias”, “encode–process–decode architecture”, and modular design that supports both training and inference paths.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data & Configuration"
        Data_Config["Data & Configuration"]:::data
    end

    subgraph "Preprocessing and Utilities"
        Data_Loader["Data Loader Module"]:::module
        Utilities["Utilities & Plotting"]:::utils
    end

    subgraph "Model Core"
        GNN_Model["GNN Model (Local TIGNN)"]:::module
    end

    subgraph "Training Pipeline"
        Train_Script["Training Script (main_train.py)"]:::script
        Callbacks["Callbacks"]:::module
        Evaluation["Evaluation"]:::module
    end

    subgraph "Inference Pipeline"
        Inference["Inference Engine (main_inference.py)"]:::script
    end

    %% Data flow connections
    Data_Config -->|"Dataset&Config"| Data_Loader
    Data_Loader -->|"FeatureExtraction"| GNN_Model
    GNN_Model -->|"ModelTraining"| Train_Script
    Train_Script -->|"TriggerCallbacks"| Callbacks
    Train_Script -->|"RunEvaluation"| Evaluation
    Evaluation -->|"Feedback"| GNN_Model
    GNN_Model -->|"GenerateInference"| Inference
    Inference -->|"VisualizeResults"| Utilities

    %% Optional external experiment tracking
    Inference -.->|"ExperimentTracking"| External[Weights & Biases]:::external

    %% Click Events
    click Data_Config "https://github.com/a-tierz/local-thermodynamicsgnn/tree/main/data/"
    click Data_Loader "https://github.com/a-tierz/local-thermodynamicsgnn/blob/main/src/dataLoader/dataset.py"
    click Utilities "https://github.com/a-tierz/local-thermodynamicsgnn/tree/main/src/utils/"
    click GNN_Model "https://github.com/a-tierz/local-thermodynamicsgnn/blob/main/src/gnn_nodal.py"
    click Train_Script "https://github.com/a-tierz/local-thermodynamicsgnn/blob/main/main_train.py"
    click Callbacks "https://github.com/a-tierz/local-thermodynamicsgnn/blob/main/src/callbacks.py"
    click Evaluation "https://github.com/a-tierz/local-thermodynamicsgnn/blob/main/src/evaluate.py"
    click Inference "https://github.com/a-tierz/local-thermodynamicsgnn/blob/main/main_inference.py"

    %% Styles
    classDef data fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef module fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef script fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef utils fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#c0392b,stroke-width:2px,stroke-dasharray:5,5
```
