# aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework architecture

> Architecture diagram of the GitHub repository aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework
- Repository: https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework

## Overview

##### Main Components
- Coupler/Driver Code: The core integration happens in src/main.cpp. This module orchestrates the simulation by reading configuration files (via src/reading_config.cpp and its header) and dispatching settings to the two models.
- CSSWM Module: Represented by the CSSWM directory. This module encapsulates the cubed-sphere shallow water model’s logic and configurations.
- 2DVVM Module: Represented by the 2DVVM directory. This contains the vector vorticity cloud resolving model.
- Configuration Handler: The config.txt file is used to set essential simulation parameters (e.g., coupling times, output paths, and model-specific parameters). The reading_config files are responsible for parsing these.
- Build and Deployment: CMakeLists.txt configures the build environment and dependency management. The project also uses a .gitmodules file (indicating submodules) and shell scripts (TMIF.sh for running the simulation and various scripts under the scripts folder) to facilitate execution and automation.
- Utility/Automation Scripts: Scripts such as generate_cases.sh, setup.sh, and submit_all_cases.sh are present in the scripts folder to assist with result visualization (e.g., Python visualization scripts) and case management.

##### Relationships and Data Flow
- Startup & Execution: The user typically runs the simulation via TMIF.sh, which calls the main executable compiled with CMake.
- Configuration Loading: On startup, the coupler (in src/main.cpp) invokes routines in reading_config to load simulation and model parameters from config.txt.
- Data Output and Visualization: Output files (such as .ctl files used for GrADs or Python visualization code outputs from the scripts folder) are generated by the model modules during simulation.
- Build Management: CMakeLists.txt serves as a central build configuration file for compiling both the coupler and any parts of the modules that are built together.

##### Architectural Patterns and Design Principles
- Modular Design: The simulation framework separates concerns between the coupling logic (in src) and the specialized simulation models (CSSWM and 2DVVM). This modularity facilitates easier code modifications – especially as indicated by the “Guidance for Code Modification” section.
- Configuration-Driven Behavior: The behavior and parameters of each module are externally controlled via config.txt, ensuring that the framework remains flexible and user-configurable.
- Scripted Automation: The inclusion of automation scripts suggests a design that supports reproducibility and eases running multiple simulation cases.

##### Relevant Technologies and Frameworks
- C++ (compiled with C++11 or higher)
- CMake for build automation
- Optional dependencies: netcdf-cxx4 (with hdf5 and netcdf-c), PETSc, and Eigen (bundled in the include folder)
- Shell scripting (for TMIF.sh and other helper scripts)
- Visualization tools (GrADs, Python visualization scripts)

##### Essential Elements
- From config.txt → reading_config → Coupler.
- From Coupler → CSSWM and Coupler → 2DVVM.
- From the simulation modules → Output/Visualization.
- Main simulation logic vs. supporting utilities.
- Input components vs. output components.
- Modular boundaries (indicating potential areas for extension or modification).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deployment Subgraph
    subgraph "Build & Deployment"
        BD1["CMakeLists.txt"]:::build
        BD2[".gitmodules"]:::build
        BD3["TMIF.sh"]:::build
    end

    %% Configuration Handler Subgraph
    subgraph "Configuration Handler"
        CF["config.txt"]:::config
        RCpp["reading_config.cpp"]:::config
        RCppH["reading_config.hpp"]:::config
    end

    %% Coupler Node
    C["Coupler (src/main.cpp)"]:::coupler

    %% Simulation Models Subgraph
    subgraph "Simulation Models"
        CSSWM["CSSWM Module (CSSWM)"]:::model
        VVM["2DVVM Module (2DVVM)"]:::model
    end

    %% Output/Visualization Node
    OUT["Output/Visualization"]:::output

    %% Utility/Automation Scripts Subgraph
    subgraph "Utility/Automation Scripts"
        GS["generate_cases.sh"]:::script
        SS["setup.sh"]:::script
        SAS["submit_all_cases.sh"]:::script
    end

    %% Connections
    BD1 --> C
    BD2 --> C
    BD3 --> C

    CF --> C
    RCpp --> C
    RCppH --> C

    C -->|"sends simulation parameters"| CSSWM
    C -->|"sends simulation parameters"| VVM

    CSSWM -->|"produces output"| OUT
    VVM -->|"produces output"| OUT

    GS -->|"processes outputs"| OUT
    SS -->|"processes outputs"| OUT
    SAS -->|"processes outputs"| OUT

    %% Click Events
    click C "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/blob/main/src/main.cpp"
    click CF "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/blob/main/config.txt"
    click RCpp "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/blob/main/src/reading_config.cpp"
    click RCppH "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/blob/main/src/reading_config.hpp"
    click CSSWM "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/tree/main/CSSWM"
    click VVM "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/tree/main/2DVVM"
    click BD1 "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/blob/main/CMakeLists.txt"
    click BD2 "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/blob/main/.gitmodules"
    click BD3 "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/blob/main/TMIF.sh"
    click GS "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/blob/main/scripts/generate_cases.sh"
    click SS "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/blob/main/scripts/setup.sh"
    click SAS "https://github.com/aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework/blob/main/scripts/submit_all_cases.sh"

    %% Styles
    classDef build fill:#FFCCCC,stroke:#990000,stroke-width:2px;
    classDef config fill:#CCE5FF,stroke:#004080,stroke-width:2px;
    classDef coupler fill:#E6CCFF,stroke:#4B0082,stroke-width:2px;
    classDef model fill:#CCFFCC,stroke:#006600,stroke-width:2px;
    classDef output fill:#CCFFFF,stroke:#008B8B,stroke-width:2px;
    classDef script fill:#FFF2CC,stroke:#CC7A00,stroke-width:2px;
```
