Lafto/wetspass_modern: WetSpass-M Modern v2.1.0

Abstract

WetSpass-M Modern v2.1.0 Release date: 2026-10-10 Compatible with: QGIS 3.28 – 4.99 Requires: numpy, rasterio, geopandas Highlights This release adds a robust boundary-cropping tool, a climate-zone-based physical cap on total recharge, user-selectable combine methods, and three important fixes to the focused-recharge engine. All previously produced diffusive outputs are reproducible with the same inputs. New features Crop outputs to boundary Replaces the failing QGIS gdal:rasterize "Mask rasters" workflow. That workflow had become unusable on recent QGIS builds: ERROR 1: Duplicate argument -ot on some builds. Silent no-output when the boundary CRS differed from the raster's. Silent no-output when the boundary did not spatially overlap the raster bounding box. The new tool bypasses the GDAL command-line layer entirely and uses rasterio + geopandas, which handle CRS reprojection and boundary-pixel retention correctly. File-selection dialog: tick which rasters to crop. Live filter, Select all / none / invert, "Only annual", "Only Recharge". Auto-reprojects the boundary vector to each raster's CRS (cached per unique CRS). Uses all_touched=True so edge pixels are retained. This is critical for water-balance closure. Writes cropped copies to cropped_to_boundary/. Originals are never modified. Runs on a background thread. Live progress and per-file logging. Climate-zone-based physical cap on total recharge Clicking Recompute from inputs in the Focused Recharge tab: Reads rain1.tif … rain12.tif from the working directory. Computes mean annual precipitation. Classifies it against the standard reference table: | P (mm/yr) | Recharge fraction | Max plausible recharge | |---|---|---| | 100 – 300 | 1 – 5 % | 5 – 15 mm/yr | | 300 – 700 | 5 – 15 % | 15 – 100 mm/yr | | 700 – 1500 | 20 – 35 % | 150 – 500 mm/yr | | 1500 – 3000 | 30 – 50 % | 450 – 1500 mm/yr | | 3000 – 5000 | 40 – 60 % | 1200 – 3000 mm/yr | Sets the recommended cap to the upper bound of the plausible recharge fraction for the matched zone. The cap is optional, can be overridden with a custom value, and a Preview cap effect button reports how many cells would be clipped and what the before/after statistics would be, without writing any file. User-selectable combine method Three options for combining Recharge_diffusive_annual.tif and Recharge_focused_annual.tif: | Method | Formula | When to use | |---|---|---| | Addition (default) | R_diff + R_foc | Standard WetSpass-M. Independent pathways | | Replace-by-max | max(R_diff, R_foc) | Conservative; avoids double-counting | | Focused-over-diffusive | R_foc on stream cells, R_diff elsewhere | If diffusive already includes streambed loss | The previous fixed behavior (replace-by-max) is preserved as an option. Rainfall-driven climate-regime auto-selection When Recompute from inputs is clicked, the climate-regime radio group is auto-selected from mean annual P: | Mean annual P | Regime | |---|---| | < 300 mm/yr | Arid | | 300 – 700 | Semi-arid | | 700 – 1200 | Mixed / transitional | | ≥ 1200 | Humid | The gwdepth-based classifier remains available as a secondary cross-check via the Auto-detect from gwdepth (secondary) button. Fixes Focused recharge — broadcast shape error ValueError: operands could not be broadcast together with shapes (1163, 1111) (1582, 1828) The soil-derived Ks raster was being read at its native resolution while the D8 hydrology grid was decimated for memory reasons. The shapes did not match, and the multiplication failed. The soil raster is now resampled to the D8 grid before the Ks lookup. Focused recharge — mass balance A single outlet cell could be assigned 12,000 mm/yr or more of infiltration because the routing step did not cap the infiltrated volume at the available streamflow. This inflated Recharge_focused_annual.tif with physically impossible outliers, which propagated into Recharge_Total_annual.tif and drove wb_error_annual.tif to values as extreme as −12,000 mm/yr. The engine now enforces V_loss = min(V_loss, V_available) at every cell. Focused recharge — annual depth cap Even without the mass-balance overflow, the annual raster could exceed the physical maximum if monthly values, each bounded by max_daily_depth_mm × flow_days, were simply summed. The annual raster now respects the monthly bound before aggregation. Duplicate -ot argument The call to gdal:rasterize for the channel-width raster passed -ot Float32 both through the DATA_TYPE parameter and again inside the EXTRA string. Removed the duplicate. This eliminates ERROR 1: Duplicate argument -ot on all QGIS builds. Documentation User guide updated to 2.1.0. New chapter on the crop tool. Rewritten Focused Recharge chapter covering the combine methods, the climate cap, and the preview tool. New troubleshooting entries for the crop tool and the cap workflow. core/cropper.py added to the file listing. Code quality All try/except/pass patterns replaced with contextlib.suppress or explicit early returns. Full Bandit scan reports No issues identified across 11,184 lines of code. No # nosec suppressions needed. Installation From the QGIS plugin repository Open QGIS. Plugins → Manage and Install Plugins → All. Search for WetSpass-M Modern. Click Install Plugin. From source Copy the wetspass_modern folder into your QGIS plugin directory: Windows: %APPDATA%\QGIS\QGIS3\profiles\default\python\plugins\ Linux: ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/ macOS: ~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/ If geopandas is not installed, in the OSGeo4W shell: pip install geopandas Compatibility No changes to the diffusive model physics. Diffusive outputs for given inputs and starting state are identical to version 2.0.5. The default combine method changed from replace-by-max to addition. To reproduce 2.0.5 behavior, select Replace-by-max in the Focused Recharge tab before clicking Combine → Total recharge. Checkpoints from 2.0.5 are not compatible with 2.1.0 and will be discarded on resume. Run a fresh simulation or delete wetspass_checkpoint.json from the output folder. Credits Original Wetspass-M 2016 model: K. Abdollahi, I. Bashir, O. Batelaan (Vrije Universiteit Brussel). Modernization and QGIS integration: M. G. Gurmu.