How shud-system/shud works
Project type and purpose
• SHUD is a command‐line, C/C++ hydrologic simulation tool that couples surface and subsurface flow using a semi‐discrete Finite Volume Method. It is driven by file‐based GIS, time‐series and configuration inputs, uses the CVODE solver from SUNDIALS for ODE integration, and parallelizes with OpenMP. Auxiliary R scripts in rAnalysis/ provide post‐processing and visualization.
File structure
• Top level
• src/ – core simulation code, subdivided into:
– classes/ – data structures and I/O (e.g., IO.cpp/IO.hpp, CommandIn, ModelConfigure, Element, River, Lake, TimeSeriesData)
– ModelData/ – routines to read, initialize, update model state (MD_readin, MD_initialize, MD_update, etc.)
– Equations/ – FVM formulae, flux computations, CVODE configuration (cvode_config.cpp/hpp), function implementations
– Model/ – high‐level orchestration (shud.cpp, f.cpp)
– main.cpp and src/inputFile.txt – entry point and sample input reference
• input/ – per‐watershed folders (ccw/, heihe/, qhh/), each containing: GIS shapefiles (.shp/.dbf/.prj/.shx), CSV forcing, and .cfg/.para/.sp/.tsd configuration files
• rAnalysis/ – R scripts for loading and analyzing SHUD outputs (ccw.R, heihe.R, qhh.R)
• Script/ – helper scripts (e.g., installSundials.sh)
• Build & config: configure, Makefile
• Documentation/figures: README.md, Fig/, VersionUpdate.md
README for additional insights
• Emphasizes multi‐process, multi‐scale coupling, use of CVODE, OpenMP, and flexible spatial/temporal resolution.
Main components & their interactions
a. Input Data Store
– GIS layers, time‐series and parameter/config files in input/<watershed>/
b. Preprocessing & Build Layer
– configure script downloads & builds SUNDIALS/CVODE
– Makefile compiles SHUD sources (src/) into shud executable
c. I/O & Configuration Module
– classes/IO reads all input files and populates in‐memory data structures
– classes/CommandIn and ModelConfigure parse command‐line and config parameters
d. Model Initialization & Mesh Construction
– Constructs mesh elements, nodes, river segments, lake elements via classes/Element, River, Lake, Node
– Initializes time‐series data via TabularData and TimeSeriesData classes
e. ModelData Layer
– Data management routines (MD_readin, MD_initialize, MD_ElementFlux, MD_update, etc.) maintain state vectors for soil moisture, groundwater, river stage, ponding depth
f. Equation Solver Layer
– FVM discretization and flux calculations in Equations/
– CVODE interface (cvode_config) sets up and calls the external SUNDIALS library
– OpenMP pragmas in computational loops for parallel execution
g. Simulation Engine
– Model/shud.cpp orchestrates time‐stepping loop:
Input → Initialize → Assemble ODE system → Call CVODE → Update state → Loop
h. Output Layer
– State variables and fluxes written out (e.g., output/<watershed>.out) via classes/IO
i. Post‐Processing & Visualization
– R scripts in rAnalysis/ read outputs for statistical analysis and plotting
Architectural patterns and design principles
• Layered modular design separating I/O, data management, numerical methods, and orchestration
• Dependency on external library (SUNDIALS CVODE) isolated behind cvode_config interface
• Data‐driven execution: all parameters and spatial data come from files, no hard‐coded constants
• Parallelization at the computational kernel level (OpenMP in FVM loops)