# quercushernandez/thermodynamicsgnn architecture

> Architecture diagram of the GitHub repository quercushernandez/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/quercushernandez/thermodynamicsgnn
- Repository: https://github.com/quercushernandez/thermodynamicsgnn

## Overview

##### Main Components
- Core Execution Module: The main.py file acts as the “orchestrator” that interprets command-line arguments (e.g., system name, training mode) and starts either training or testing.
- Model Definition: The model.py file encapsulates the definition of the Graph Neural Network (GNN) architecture, including the layers and message passing blocks. This is where the thermodynamics-informed GNN is defined.
- Solver/Training Logic: The solver.py file (in combination with dataset.py) contains the routines to load data, execute training loops, handle loss functions (integrating both data loss and physics-based losses), and update parameters.
- Utilities: The utilities folder (with plot.py and utils.py) provides additional functions for visualization (e.g., generating .gif outputs of simulations) and other helper functions.

##### Relationships and Interactions
- Command Input → main.py: The system is kicked off via main.py with command-line parameters that specify the simulation type (sys_name) and mode (training or testing).
- Model Instantiation: main.py calls model.py to instantiate the gnn model whose architecture is built to consider both the geometrical (graph-based) and thermodynamics biases.
- Training/Inference Cycle: The solver.py manages communication between the dataset, the GNN model (from model.py), and optimization routines. The training arguments (hidden layers, message passing iterations, learning rate, etc.) are fed in at this level.
- Visualization: Post training or testing, results are passed to utilities/plot.py, which handles plotting and creating animation (.gif) files that are then stored in the outputs folder.
- External Scripts: The executables scripts wrap around these calls for ease-of-use, ensuring a consistent execution environment.

##### Architectural Patterns and Design Principles
- Modular Design: Each functionality (data handling, model definition, solving/training, and utilities) is isolated into separate modules, ensuring clear separation of concerns.
- Command-Line Interface: main.py serves as the central entry point and uses command-line options to adapt behavior (full-stack, modular arguments).
- Reusability: The existence of shell scripts for each simulation case, coupled with configurable parameters, underlines the design for easy experimentation and extension.
- Domain-Specific Abstraction: The system is framed around thermodynamics and graph-based messages. The “physical laws” and integration of dissipation (GENERIC structure) are inherently baked into how the model and solver are defined.

##### Relevant Technologies and Libraries
- Python 3.9 is the targeted runtime.
- PyTorch is used for deep learning, with additional support from torch-geometric and torch-scatter which are critical for GNN operations.
- NumPy, SciPy, and Matplotlib are employed for numerical processing and visualization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Input
    T("Command Line Input"):::external

    %% Data Management Layer
    subgraph "Data Management"
        D("Data (Preprocessed & Pretrained Networks)"):::data
    end

    %% Core Execution Layer
    subgraph "Core Execution"
        M("main.py (CLI Entry Point)"):::core
        MP("model.py (Thermo-informed GNN Model)"):::core
        DS("dataset.py (Data Loader)"):::core
        S("solver.py (Training/Inference)"):::core
    end

    %% Utilities Layer
    subgraph "Utilities"
        U("utilities (Plotting & Helper Functions)"):::utils
    end

    %% Experiment Scripts Layer
    subgraph "Experiment Scripts"
        E("executables (Shell Scripts)"):::scripts
    end

    %% Data Flow
    T -->|"inputParams"| M
    E -->|"trigger"| M
    D -->|"loadsData"| DS
    M -->|"callsLoader"| DS
    M -->|"instantiatesModel"| MP
    M -->|"orchestrates"| S
    DS -->|"providesData"| S
    MP -->|"suppliesModel"| S
    S -->|"sendsOutputs"| U

    %% Click Events
    click D "https://github.com/quercushernandez/thermodynamicsgnn/tree/main/data/"
    click M "https://github.com/quercushernandez/thermodynamicsgnn/blob/main/main.py"
    click MP "https://github.com/quercushernandez/thermodynamicsgnn/blob/main/model.py"
    click DS "https://github.com/quercushernandez/thermodynamicsgnn/blob/main/dataset.py"
    click S "https://github.com/quercushernandez/thermodynamicsgnn/blob/main/solver.py"
    click U "https://github.com/quercushernandez/thermodynamicsgnn/tree/main/utilities/"
    click E "https://github.com/quercushernandez/thermodynamicsgnn/tree/main/executables/"

    %% Class Styles
    classDef external fill:#cce5ff,stroke:#1f78b4,stroke-width:2px;
    classDef data fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef utils fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef scripts fill:#e6e6e6,stroke:#666666,stroke-width:2px;
```
