HydroPol2D: Distributed 2D Hydrologic-Hydrodynamic and Water Quality Model

April 28, 2026 · View on GitHub

HydroPol2D is an open-source, high-resolution 2D model built in MATLAB for simulating overland flow, infiltration, groundwater-surface water interactions, and pollutant transport. Developed with performance and flexibility in mind, it supports both CPU and GPU computations and can handle diverse forcing conditions such as spatially distributed rainfall, satellite-derived precipitation, design storms, and hydrograph inputs.

The model is particularly suited for urban, peri-urban, and rural catchments in both gauged and data-scarce regions.

Key Features

  • 2D overland flow via Local-Inertial Model or Cellular-Automata
  • Fully distributed infiltration with Green-Ampt or Darcy's law
  • Groundwater recharge and shallow aquifer flow using Darcy's law and 2D Boussinesq Dynamics
  • Flexible rainfall input: gauges, satellite, interpolated, synthetic hyetographs, rasters
  • Snow accumulation and melt with mass balance tracking
  • Dynamic reservoir and dam-break modeling
  • Pollutant simulation: 1 pollutant per simulation with build-up/wash-off dynamics
  • Mass-conserving adaptive time stepping (Courant-based)
  • Output visualizations in .tif, .mp4, .csv, .pdf, and .png

Installation & Dependencies

MATLAB Requirements:

  • MATLAB R2020a or newer
  • Required Toolboxes:
    • Mapping Toolbox
    • Parallel Computing Toolbox (for GPU mode)
  • NVIDIA GPU with at least 2 GB VRAM and compute capability > 3.5
  • 8+ GB RAM for CPU mode

External Tools:

  • Microsoft Excel (for parameter configuration). Alternatively, users can only edit files in /config for rapid parametrization without requiring filling parameters/inputs in the Excel spreadsheets
  • QGIS, Google Earth Engine, or R for raster preprocessing (DEM, LULC, soils, etc.)
  • Documentation fully available with examples in the HydroPol2D - Docs.

Getting Started

1 Clone the Repository

git clone https://github.com/marcusnobrega-eng/HydroPol2D.git
cd HydroPol2D

Alternatively, download the ZIP from GitHub and extract it to your desired directory.

2. Open MATLAB and Navigate to the Model Folder

cd('path/to/your/model/folder')
addpath(genpath(pwd))
savepath

Replace path/to/your/model/folder with the location where you cloned the repository.

3. Verify Required Files

Ensure the following are present in your working directory:

  • HydroPol2D_V115.m (main model script)
  • /config/ folder (parameters and flags)
  • /HydroPol2D_functions
  • /topotoolbox folder
  • Input_Spreadsheets (if excel version is used)

4. Set Up MATLAB

Open MATLAB or directly go in your model folder and open the file HydroPol2D_V115.m that MATLAB will automatically path to the model folder.

5. Configure the Model

Edit inputs in:

  • /config/ folder. In particular, the file input_data_bypass_script.m. In case your forcing or other inputs do not follow the folder structure of the model, you may change the filepaths by editing input_paths_bypass.m in the same folder.
  • Edit the HydroPol2D_V115.m file to define the run_mode, the input_excel_file defining the General_Data.xlsx if Excel mode is activated, the topo_path_user defining the path of the topotoolbox folder, and the HydroPol2D functions defined by the hydropol2d_tools_user path.
  • Excel parameter files located in the \Input_Data_Sheets if you are running the model under the Excel mode, defined in the HydroPol2D_V115.m file.

6. Run the Model

HydroPol2D_V115.m

If you have access to HPC systems, you can alternatively submit a job using the file HP2D_HPC_Config.sbatch and specify GPU/CPU configurations and memory.

Example

Example of a rain-on-the-grid simulation of a 1 in 50-year rainfall in an urban area with the influence of urban drainage - Sao Paulo, Brazil.

Example of a total dam-break collapse scenario in a city in Pernambuco, Northeast - Brazil.

dam_break

Example of Rainfall-Runoff event in a catchment near Palo Alto -CA.

https://github.com/user-attachments/assets/739e39eb-18e8-4ec3-bee6-a7a647793774

Example of a continuous simulation of a catchment in Pune - India with spatially-varied rainfall from MSWEP for a period of approximately 22 days.

https://github.com/user-attachments/assets/3ad69bb3-3e24-4df3-b5ff-584aafcc6296

Input Data Structure

HydroPol2D requires the following input data files and parameters, which must be prepared and aligned before running the model:

Raster Inputs (.tif)

  • Digital Elevation Model (DEM): Defines terrain slope, flow direction, and is used for hydrologic routing and terrain preprocessing. Must be gap-filled and optionally smoothed. Elevation in meters.
  • Land Use / Land Cover (LULC): Used to assign surface properties (e.g., roughness, imperviousness, pollutant loading). Each class must be indexed and named consistently with the LULC parameter table.
  • Soil Map: Classifies soils spatially to define infiltration and water balance parameters. Must match indices in the soil parameter table.
  • Depth to aquifer or Depth to Bedrock Constrains the vadose zone depth and surface sub-surface interactions
  • Albedo / Leaf Area Index Constrain the model parametrization for snow melt and evapotranspiration calculations
  • Initial Conditions of Surface Depth, Soil Moisture, and Pollutant Mass Constrain the model to appropriate initial conditions prior to simulations
  • Optional Gridded Maps:
    • Rainfall intensity maps (mm/hr)
    • Potential Evapotranspiration (ETP)
    • Actual Evapotranspiration (ETa)
    • Snow Depth
    • Groundwater Table Depth
    • Subgrid river bathymetry and slope rasters

All rasters must be aligned spatially (same extent, resolution, and coordinate reference, preferably EPSG:3857) or with an Equal Area projection.

Parameter Tables (Excel Sheets)

  • LULC Parameter Table: Each land use class must include:

    • Manning's n roughness coefficient
    • Impervious index (0 or 1)
    • Pollutant loading coefficients: C1 (build-up rate), C2 (capacity), C3 (wash-off rate), C4 (wash-off exponent)

  • Soil Parameter Table: Each soil class must include:

    • Vertical Saturated hydraulic conductivity KsatK_{\mathrm{sat}}
    • van Genutchen nn and α\alpha
    • Initial soil water content θi\theta_{\mathrm{i}}
    • Saturated water content θsat\theta_{\mathrm{sat}}
    • Residual water content θr\theta_{\mathrm{r}}
    • Horizontal Saturated hydraulic conductivity Ksat,gwK_{\mathrm{sat,gw}}

Preprocessing must ensure that all rasters are aligned and projected.

Output Files

HydroPol2D saves results in:

  • Geospatial: .tif rasters (depth, infiltration, pollutant, velocity, recharge, etc.) Alternatively, .nc files can be saved for time series of gridded data.
  • Graphics: .png, .pdf (hydrographs, profiles, maps)
  • Animation: .mp4 (dynamic maps)
  • Numerical: .csv (time series, diagnostics)

Configuration Flags

Flags are configured via Excel and define:

  • Simulation type (rainfall vs hydrograph)
  • Processing mode (CPU vs GPU)
  • Routing method (CA or Local Inertial)
  • Hydrologic modules (baseflow, ET, GW, snow, pollutant)
  • DEM preprocessing routines

Ensure consistency among flags (e.g., only one rainfall mode active).

Performance & Scaling

ModeGrid SizeNotes
CPU< 1 million cellsSingle-core, slower
GPU> 1 million cellsFaster, requires NVIDIA GPU
  • Adaptive time stepping based on Courant number (recommended: 0.3–0.7)

References

Cite HydroPol2D using:

Contributing & Support

For issues, contact:

Repository: https://github.com/marcusnobrega-eng/HydroPol2D

License

This project is licensed under the MIT License — you are free to use, modify, and distribute this software, provided proper credit is given.

Short Course Link with 2-h classes + PPT material (Available upon request): marcusnobrega.engcivil@gmail.com

Acknowledgments

  • University of São Paulo — São Carlos School of Engineering
  • University of Texas at San Antonio — Civil and Environmental Engineering
  • Stanford University — Stanford Doerr School of Sustainability; Department of Earth System Science