How shud-system/rshud works
Project Type and Purpose
• Type: An open-source R toolbox (R package) supplemented by C++ (via Rcpp) for computationally intensive tasks.
• Purpose: Prepare, configure, and analyze SHUD (Simulator for Hydrological Unstructured Domain) models—handling GIS data ingestion, mesh generation, SHUD input/output, calibration, time-series analysis, and visualization.
Main Architectural Components
a. R Layer (Core Toolbox)
• Submodules under R/:
– Data Ingestion & Filtering (DataFilter.R, Func_Get.R, read*.R)
– GIS Processing (Func_GIS.R, GIS_*.R, NLCD.R)
– Mesh & Domain Generation (MeshDomain.R, triangulate.R, triTopology.cpp wrapper)
– Model Configuration & I/O (ModelConfigure.R, writeInput.R, readout.R, write.*.R)
– Calibration & Parameter Tools (Func_PTF.R, ModelBC.R)
– Time-Series & Analysis (Hydro_obs.R, readTSD.R, ts2*.R)
– Visualization & Plotting (plot.R, plotMap.R, demo scripts)
b. Native Layer (C++ via Rcpp)
• src/polygonArea.cpp, src/triTopology.cpp – performance-critical geometry routines
• RcppExports.cpp – glue code between R and C++
c. External Dependencies & Services
• GDAL/PROJ (vector/raster reprojection, shapefile, raster I/O)
• RTriangle (Delaunay triangulation)
• netCDF4 (reading/writing NetCDF climate/forcing data)
• R packages: sp, gstat, ncdf4, raster, etc.
d. Data Stores & Artifacts
• /data – sample .rda datasets
• SHUD input files (.riv, .ic, .forc, mesh files)
• SHUD output files (time-series, NetCDF)
• Shapefiles/Rasters generated by GIS routines
e. Demo & Examples
• /demo – end-to-end scripts that orchestrate data ingestion → mesh building → model file writing → result plotting
Relationships & Data Flows
• Ingestion Layer reads raw spatial (raster/vector) and time-series data → hands off to GIS Processing.
• GIS Processing calls GDAL/PROJ to standardize projections → outputs cleaned spatial layers.
• Mesh Generation invokes RTriangle and C++ geometry routines (via Rcpp) → creates unstructured triangular mesh.
• Model Configuration assembles mesh + parameter sets → writes SHUD input files.
• SHUD engine (external process) runs on input files (not inside this package).
• I/O Layer reads SHUD output (NetCDF or text) → feeds into analysis (time-series) and visualization modules.
• Demo scripts orchestrate and display end-to-end workflows.
Architectural Patterns & Design Principles
• Modular separation: each functional area (GIS, mesh, I/O, analysis) is a distinct R namespace.
• Hybrid computation: heavy geometry tasks offloaded to C++/Rcpp.
• Extensibility: new GIS formats or mesh algorithms can be plugged in by adding R functions or C++ modules.
• Data-centric flow: clearly delineated layers moving from raw inputs to processed outputs.
Technologies, Frameworks & Libraries
• R + devtools/testthat for package development and testing
• Rcpp for native integration
• GDAL/PROJ for spatial I/O and reprojection
• RTriangle for triangulation
• ncdf4 for NetCDF handling
• sp, raster, gstat, hydroGOF, xts for analysis/plotting