rSHUD --- A toolbox for SHUD modeling system

• Lele Shu (shulele@lzb.ac.cn)
• www.shud.xyz
• SHUD-System/rSHUD

SHUD

The Simulator for Hydrological Unstructured Domain (SHUD) is a multiprocess, multi-scale hydrologic model where the major hydrological processes are fully coupled using the semi-discrete finite volume method.

This package can be used with the AutoSHUD project, which can build modeling domains automatically.

Version Policy

• rSHUD 2.5.0 is the current v2 release-preparation target.
• This release target uses terra and sf for the modern spatial workflow.
• AutoSHUD v2.5.0 should be used with matching rSHUD v2.5.0 release artifacts for release workflows.
• Formal v3.0.0 release is not part of this release candidate. It remains blocked on separate team review.
• Release notes and maintainer checklists are under docs/release/.

Purpose of the package:

1. Convert geospatial data into SHUD format. The toolkit can process raster and vector data, then build the unstructured triangular mesh domain.
2. Write/read SHUD input files.
3. Read SHUD output files.
4. Generate calibration parameter sets.
5. Analyze hydrologic time-series data.
6. Produce two-dimensional and three-dimensional plots.
7. Perform GIS analysis. Convert unstructured data into spatial data (Shapefile, sf, or terra raster).

Installation

If you work on Ubuntu platform, you must install the software below before installing rSHUD and packages.

sudo apt -y install gdal-bin libgdal-dev libproj-dev libgeos-dev libudunits2-dev
sudo apt -y install gcc g++ gfortran
sudo apt -y install r-cran-systemfonts r-cran-textshaping

We suggest users install the dependent packages before installing rSHUD.

libs = c('terra', 'sf', 'reshape2', 'xts', 'hydroGOF', 'zoo', 'RTriangle',
         'proj4', 'gstat', 'abind', 'lubridate', 'geometry', 'testthat',
         'rmarkdown', 'ncdf4', 'blogdown', 'doParallel', 'knitr', 'deldir',
         'devtools')

for(i in seq_along(libs)){
  message(i, '/', length(libs), '\t', libs[i])
  if(!require(libs[i], character.only = TRUE)){
    install.packages(libs[i], dependencies = TRUE, INSTALL_opts = '--no-lock')
  }
}

if(!require(devtools)){
  install.packages("devtools", dependencies = TRUE, INSTALL_opts = '--no-lock')
}
devtools::install_github("shulele/RTriangle", subdir = "pkg")

Then you may install rSHUD directly from GitHub.

if(!require(devtools)){ install.packages("devtools") }

# After the v2.5.0 tag is published from merged master:
devtools::install_github("SHUD-System/rSHUD@v2.5.0")

# During release-candidate review or for current master:
devtools::install_github("SHUD-System/rSHUD")

The modern spatial workflow requires:

1. R >= 4.0
2. terra >= 1.7-0
3. sf >= 1.0-0

The retired rgeos and rgdal packages are not required by the modern workflow.

Notes for migration

Modern APIs use terra/sf objects and snake_case function names, for example auto_build_model(), read_mesh(), read_river(), mesh_to_sf(), and mesh_to_raster(). Deprecated wrappers are retained only as migration compatibility entry points.

For details, see NEWS.md, inst/MIGRATION_GUIDE.md, and the package vignettes.

Documentation

• Function help: use ?function_name in R.
• Example code: see the demo/ directory.
• Process and governance documents: see docs/README.md.
• Chinese README: README_cn.md.

Contributing

Issues and Pull Requests are welcome. Please make sure:

1. Code follows R package development standards.
2. New functions include documentation and tests.
3. The project coding style is followed.

For detailed contributing guidelines, see CONTRIBUTING_cn.md.

License

This project is licensed under the MIT License. See LICENSE.