# shud-system/shud architecture

> Architecture diagram of the GitHub repository shud-system/shud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shud-system/shud
- Repository: https://github.com/shud-system/shud

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Stores
    Input[(Input Data Store)]:::datastore
    Output[(Output Store)]:::datastore

    %% Layers
    subgraph "Preprocessing & Build Layer"
        Configure["configure"]:::module
        Makefile["Makefile"]:::module
        Install["installSundials.sh"]:::module
    end

    subgraph "I/O & Configuration Module"
        IO_cpp["IO.cpp"]:::module
        IO_hpp["IO.hpp"]:::module
        CmdIn_cpp["CommandIn.cpp"]:::module
        CmdIn_hpp["CommandIn.hpp"]:::module
        ModelCfg_cpp["ModelConfigure.cpp"]:::module
        ModelCfg_hpp["ModelConfigure.hpp"]:::module
    end

    subgraph "Model Initialization & Mesh Construction"
        Element_cpp["Element.cpp"]:::module
        Element_hpp["Element.hpp"]:::module
        River_cpp["River.cpp"]:::module
        River_hpp["River.hpp"]:::module
        Lake_cpp["Lake.cpp"]:::module
        Lake_hpp["Lake.hpp"]:::module
        Node_cpp["Node.cpp"]:::module
        Node_hpp["Node.hpp"]:::module
        Tabular_cpp["TabularData.cpp"]:::module
        Tabular_hpp["TabularData.hpp"]:::module
        TS_cpp["TimeSeriesData.cpp"]:::module
        TS_hpp["TimeSeriesData.hpp"]:::module
    end

    subgraph "ModelData Layer"
        ModelData["src/ModelData/"]:::module
    end

    subgraph "Equation Solver Layer"
        Equations["src/Equations/"]:::module
    end

    subgraph "Simulation Engine"
        Shud_cpp["shud.cpp"]:::module
        Shud_hpp["shud.hpp"]:::module
        F_cpp["f.cpp"]:::module
        F_hpp["f.hpp"]:::module
        Main_cpp["main.cpp"]:::module
    end

    subgraph "Post-Processing & Visualization"
        RAnalysis["rAnalysis/"]:::analysis
    end

    subgraph "External Dependencies"
        SUNDIALS["SUNDIALS/CVODE"]:::external
        OpenMP["OpenMP"]:::external
        R["R"]:::external
    end

    %% Connections
    Input -->|reads| IO_cpp
    Input -->|reads| IO_hpp

    Configure -->|configures/builds| SUNDIALS
    Makefile -->|compiles| Shud_cpp
    Install -->|installs| SUNDIALS

    IO_cpp -->|"populates"| ModelData
    IO_hpp -->|"populates"| ModelData
    IO_cpp -->|"provides params"| Equations
    IO_hpp -->|"provides params"| Equations

    ModelData -->|"state vectors"| Shud_cpp
    Equations -->|"FVM & flux"| ModelData
    SUNDIALS -->|"solves ODEs"| Equations
    OpenMP -->|"parallelizes"| Equations

    Shud_cpp -->|"controls loop"| ModelData
    Shud_cpp -->|"calls"| Equations
    Shud_cpp -->|"writes"| Output

    Output -->|feeds| RAnalysis
    R -->|executes| RAnalysis

    %% Click Events
    click Input "https://github.com/shud-system/shud/tree/master/input/"
    click Configure "https://github.com/shud-system/shud/tree/master/configure"
    click Makefile "https://github.com/shud-system/shud/tree/master/Makefile"
    click Install "https://github.com/shud-system/shud/blob/master/Script/installSundials.sh"
    click IO_cpp "https://github.com/shud-system/shud/blob/master/src/classes/IO.cpp"
    click IO_hpp "https://github.com/shud-system/shud/blob/master/src/classes/IO.hpp"
    click CmdIn_cpp "https://github.com/shud-system/shud/blob/master/src/classes/CommandIn.cpp"
    click CmdIn_hpp "https://github.com/shud-system/shud/blob/master/src/classes/CommandIn.hpp"
    click ModelCfg_cpp "https://github.com/shud-system/shud/blob/master/src/classes/ModelConfigure.cpp"
    click ModelCfg_hpp "https://github.com/shud-system/shud/blob/master/src/classes/ModelConfigure.hpp"
    click Element_cpp "https://github.com/shud-system/shud/blob/master/src/classes/Element.cpp"
    click Element_hpp "https://github.com/shud-system/shud/blob/master/src/classes/Element.hpp"
    click River_cpp "https://github.com/shud-system/shud/blob/master/src/classes/River.cpp"
    click River_hpp "https://github.com/shud-system/shud/blob/master/src/classes/River.hpp"
    click Lake_cpp "https://github.com/shud-system/shud/blob/master/src/classes/Lake.cpp"
    click Lake_hpp "https://github.com/shud-system/shud/blob/master/src/classes/Lake.hpp"
    click Node_cpp "https://github.com/shud-system/shud/blob/master/src/classes/Node.cpp"
    click Node_hpp "https://github.com/shud-system/shud/blob/master/src/classes/Node.hpp"
    click Tabular_cpp "https://github.com/shud-system/shud/blob/master/src/classes/TabularData.cpp"
    click Tabular_hpp "https://github.com/shud-system/shud/blob/master/src/classes/TabularData.hpp"
    click TS_cpp "https://github.com/shud-system/shud/blob/master/src/classes/TimeSeriesData.cpp"
    click TS_hpp "https://github.com/shud-system/shud/blob/master/src/classes/TimeSeriesData.hpp"
    click ModelData "https://github.com/shud-system/shud/tree/master/src/ModelData/"
    click Equations "https://github.com/shud-system/shud/tree/master/src/Equations/"
    click Shud_cpp "https://github.com/shud-system/shud/blob/master/src/Model/shud.cpp"
    click Shud_hpp "https://github.com/shud-system/shud/blob/master/src/Model/shud.hpp"
    click F_cpp "https://github.com/shud-system/shud/blob/master/src/Model/f.cpp"
    click F_hpp "https://github.com/shud-system/shud/blob/master/src/Model/f.hpp"
    click Main_cpp "https://github.com/shud-system/shud/blob/master/src/main.cpp"
    click RAnalysis "https://github.com/shud-system/shud/tree/master/rAnalysis/"

    %% Styles
    classDef datastore fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef module fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px;
    classDef analysis fill:#dda0dd,stroke:#333,stroke-width:1px;
```
