# snigenigmatic/chaospinn architecture

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

## Overview

##### Main Components
a. PINN Module:
- Folder: PINN-Model
- Contents: It contains the implementation files for the neural network (model.py), evaluation tools (load_and_evaluate.py), and supplementary scripts (paste.py).
- Role: Core training and prediction using PyTorch with autograd-based physics loss functions.

b. Baseline Numerical Solver:
- Folder: baseline
- Contents: Files like baseline.py and deepxde_baseline.py.
- Role: Implements traditional numerical solvers (using FDM) to benchmark PINN performance; includes visualization of results.

c. Data Management:
- Folders: Data and visualization/data
- Contents: ZIP archives containing datasets (KS equation specifics such as “lyapexpts_ksoddperiodic.zip” and “lyapexpts_ksperiodic.zip”).
- Role: Provides the ground truth scenarios and initial conditions required for training and testing.

d. Training & Execution Scripts:
- Files: main.py, model_fit.py
- Role: Likely coordinate overall training, integration of PINN and baseline components, and possibly hyperparameter tuning.

e. Visualization:
- Folder: visualization
- Contents: Contains scripts (initial_visualization.py) and additional data for producing visual outputs (e.g., heatmaps, 3D surface plots).
- Role: Generates real-time chaotic wave animations and comparative plots of PINN predictions versus numerical solutions.

f. Supplementary and Versioning Files:
- Files such as .gitignore, .python-version, pyproject.toml, and uv.lock ensure proper environment configuration and dependency management.

##### Relationships and Data Flows
- Data flows from raw data files (in Data and visualization/data) into training and testing routines provided by both the PINN modules and baseline solvers.
- The PINN-Model component interacts with PyTorch to compute physics-informed losses, informed by the KS-equation’s residuals.
- The training scripts (main.py/model_fit.py) trigger the PINN training process, while evaluation and visualization scripts (load_and_evaluate.py, initial_visualization.py) are used to compare outputs from PINN and traditional solvers.
- The baseline solver runs in parallel to provide a classical numerical solution for performance and validity comparisons.
- Visualizations are created using libraries like Matplotlib and Plotly to produce rich 2D/3D animations and plots.

##### Architectural Patterns
- Separation of Concerns: distinct modules for PINN training, baseline (numerical solver) computations, and visualization.
- Modularity: Scripts and folders are organized based on core functionalities which makes it easier to extend with additional chaotic system analyses.
- Integration of Data-Driven and Physics-Based Approaches: The design reflects a hybrid approach combining neural network training (data-driven) with physics-based loss constraints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Input Layer"
        data_raw("Data (ZIP Datasets)"):::data
        vis_data("Visualization Data"):::data
    end

    subgraph "Training & Execution Layer"
        main_py("main.py"):::train
        model_fit("model_fit.py"):::train
    end

    subgraph "Computation Layer"
        subgraph "PINN Module"
            pinn_model("model.py"):::compute
            pinn_eval("load_and_evaluate.py"):::compute
            pinn_paste("paste.py"):::compute
        end
        subgraph "Baseline Numerical Solver"
            baseline_main("baseline.py"):::compute
            baseline_ddx("deepxde_baseline.py"):::compute
        end
    end

    subgraph "Evaluation & Comparison Layer"
        evaluator("Evaluator (Comparison)"):::eval
    end

    subgraph "Visualization Layer"
        init_vis("initial_visualization.py"):::vis
    end

    subgraph "Environment & Configurations"
        gitignore(".gitignore"):::env
        python_version(".python-version"):::env
        pyproject("pyproject.toml"):::env
        uv_lock("uv.lock"):::env
    end

    subgraph "External Dependencies"
        pytorch("PyTorch"):::external
        mplot("Matplotlib/Plotly"):::external
    end

    %% Data flows to training layer
    data_raw -->|"TrainingData"| main_py
    data_raw -->|"BaselineData"| baseline_main
    vis_data -->|"SupplementaryData"| init_vis

    %% Training scripts trigger computations
    main_py -->|"RunPINN"| pinn_model
    main_py -->|"RunBaseline"| baseline_main

    %% Computation to Evaluation
    pinn_eval -->|"PINNPredictions"| evaluator
    baseline_main -->|"NumericalResults"| evaluator

    %% Evaluation feeds into Visualization
    evaluator -->|"ComparisonResults"| init_vis

    %% External dependencies usage
    pinn_model -->|"UsesAutograd"| pytorch
    init_vis -->|"UsesPlotting"| mplot

    %% Styling definitions
    classDef data fill:#FFD700,stroke:#DAA520,color:#000000;
    classDef train fill:#87CEFA,stroke:#4682B4,color:#000000;
    classDef compute fill:#ADD8E6,stroke:#00008B,color:#000000;
    classDef eval fill:#90EE90,stroke:#006400,color:#000000;
    classDef vis fill:#FFB6C1,stroke:#FF69B4,color:#000000;
    classDef env fill:#D3D3D3,stroke:#696969,color:#000000;
    classDef external fill:#E6E6FA,stroke:#8A2BE2,color:#000000;

click pinn_model "https://github.com/snigenigmatic/chaospinn/blob/main/PINN-Model/model.py"
click pinn_eval "https://github.com/snigenigmatic/chaospinn/blob/main/PINN-Model/load_and_evaluate.py"
click pinn_paste "https://github.com/snigenigmatic/chaospinn/blob/main/PINN-Model/paste.py"
click baseline_main "https://github.com/snigenigmatic/chaospinn/blob/main/baseline/baseline.py"
click baseline_ddx "https://github.com/snigenigmatic/chaospinn/blob/main/baseline/deepxde_baseline.py"
click data_raw "https://github.com/snigenigmatic/chaospinn/tree/main/Data"
click vis_data "https://github.com/snigenigmatic/chaospinn/tree/main/visualization/data"
click main_py "https://github.com/snigenigmatic/chaospinn/blob/main/main.py"
click model_fit "https://github.com/snigenigmatic/chaospinn/blob/main/model_fit.py"
click init_vis "https://github.com/snigenigmatic/chaospinn/blob/main/visualization/initial_visualization.py"
click gitignore "https://github.com/snigenigmatic/chaospinn/blob/main/.gitignore"
click python_version "https://github.com/snigenigmatic/chaospinn/blob/main/.python-version"
click pyproject "https://github.com/snigenigmatic/chaospinn/blob/main/pyproject.toml"
click uv_lock "https://github.com/snigenigmatic/chaospinn/blob/main/uv.lock"
```
