How aaron-hsieh-0129/next-genegration-adaptive-convection-circulation-coupling-framework works
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).