Mapping every drop: Introducing Hydro Stack
Authors: Shubham Kumar, Aaditeshwar Seth
06 November 2026
Why watersheds matter?
Almost every decision about land and water management for any region, from flood planning to irrigation, to siting for a check dam, etc. comes down to the question of tracking the flow of water across the topography of the region. A watershed is the land area that drains to a common outlet, and a micro-watershed is typically a few hundred to a few thousands hectares (1 sq. kms. to tens of sq. kms.), is the smallest unit for environment planning. It is also the practical scale at which villages and local organisations can actually act.
Where admin boundaries were more or less created by humans, watersheds and micro-watersheds are something that are natural divisions based on topography. It is true that as the topography changes these boundaries will shift accordingly. So, planning for climate action should happen based on these natural divides as compared to something that is based on administrative convenience.
There exists global hydrographic products such as HydroSHEDS which provide basin, sub-basins and watersheds level delineation but even at their lowest level of hierarchy, micro-watersheds level delineation is not covered. It could be because of computational prohibitiveness of producing global level products covering such granular level delineation of micro-watershdes. We extend the framework of HydroSHEDS by providing micro-watershed level delineation starting from a HydroSHEDS basin.
Fig 1: Area distribution graph for HydroSHEDS level 12(the lowest hierarchical level) basins corresponding to Asia. We can see that the distribution of basin polygons is centered around ~20,000 ha which is too large for planning purposes
Fig2: Area distribution graph for HydroSHEDS level 12(the lowest hierarchical level) basins corresponding to North America. We can see that the distribution of basin polygons is centered around ~24,000 ha which is again too large for planning purposes.
The gap in global datasets: Limitations of HydroSHEDS / HydroBASINS
HydroSHEDS and basin delineations based on it, HydroBASINS are useful references for basin-scale analysis. Because they were aimed at producing near global coverage, they used a fixed resolution, fixed starting topographic product (i.e. Digital Elevation Map) and uniform thresholds that are not tuned to any one region. Also, their methodology is not exposed publicly, so that it cannot be reused and adapted particularly for a region or scale of analysis. So, they are static products. They also do not directly offer the layers watershed planners need, such as natural depressions, catchment with stream order embedded in it, etc.
These are the gaps Hydro Stack was built to fill. We take a HydroSHEDS basin (specifically level 5 basin) and delineate micro-watersheds and provide other hydro-geomorphic layers along with it.
What Hydro Stack does
Hydro Stack is an open-source, containerized workflow built for hydrological processing for any land region in the world. It uses tools from GRASS GIS for basic hydrological algorithms and adds custom algorithms designed by us like micro-watershed merging algorithm and others that helps in generating the end products that we need.
The flow of the fully automated workflow goes like:
- It first picks a right UTM (Universal Transverse Mercator) projection for the study area.
- Downloads and mosaics elevation data from OpenTopography (SRTM 1 arc-second by default, with other sources available there as options).
- Conditions the DEM using Priority Flood Algorithm,
- Computes flow direction and flow accumulation.
- Produces initial delineations of micro-watersheds which are later passed through a merging procedure to make the micro-watersheds fall within the distribution from 500 hectares to 1500 hectares.
- Produces the other sets of hydrological layers in the same run.
The full set of layers produced by the workflow are: natural depressions, micro-watershed boundaries, drainage lines with Strahler ordering, pour points, catchment area, and catchment-level stream order. The micro-watershed layer is augmented with the information from the micro-watershed connectivity graph.
Fig 3: Micro-watershed layer corresponding to the HydroSHEDS v1 level 5 basin with Hybas ID: 4051065250. This region lies south of the Godavari river near Maharashtra-Telangana-Chhatisgarh border. Further drainage networks and pour points are laid over it.
Fig4: Natural depression corresponding to the same input HydroSHEDS basin. Also the path of the river channel comes naturally in the depressions map.
Fig5: Catchment with stream ordering map for the same level 5 HydroSHEDS basin. Each cell / region is assigned the stream order of the immediate stream it drains into.
Some highlights of the workflow
Depressions as information. Filling sinks is standard for routing flow, but many sinks are real ponds, sinkholes and closed basins (endorheic basins). Hydro Stack compares the filled and original DEMs to recover depression depth, producing a map of candidate sites for water harvesting or recharge.
Flow-aware basin merging procedure. Standard threshold-based delineation yields many tiny basins and few much larger basins that are uncontrolled for. Keeping a high threshold makes the larger basins delineated to become even much larger. The challenge was to keep the distribution of the micro-watersheds fall within a certain range. Hydro Stack starts with a small threshold and gradually merges the small basins so that the micro-watersheds fall much close to the target size distribution (500 ha minimum, 1500 ha maximum by default). A small basin is absorbed into the one it drains, so the drainage structure is preserved. If that isn’t possible, it merges with an upstream neighbor instead. It does not forces merging if the size of the resulting micro-watersheds will grow beyond 1500 ha. This process repeats until there are no possible merges left. Thus, the drainage topology is kept intact.
Built-in connectivity. Each micro-watershed is tagged with its downstream neighbor, its upstream contributors, and the direction of the downstream neighbor. Planners can query the micro-watershed map and also the drainage network with a simple attribute lookup, with no graph traversal needed. These information matters because an intervention in one unit, effects its neighbors.
How it fares computationally
The team ran the workflow on the HydroSHEDS level-5 basins that intersect India, benchmarking at each decile of the basin size. Basins as large as roughly 167,000 sq. kms. at 30 m resolution were processed in a few hours on a single workstation. A small basin of about 28 sq. kms. took just 15 seconds.
On the output side, most micro-watersheds landed around the intended range. Some stayed smaller where no valid merge was available. A few ended up larger, mostly in flat terrain where flow accumulates slowly even after much traversal on the terrain.
Fig 6: Area distribution graph for the micro-watershed delineated corresponding to 100th percentile level 5 basin overlapping with India.
How it is being used
Hydro Stack will generate the base layers for the CoRE Stack (Commoning for Resilience and Equity), a digital public good that helps communities and civil society organizations plan local hydrological and other interventions. Tools built on these layers, like Commons Connect, help them make evidence-based demands from local government.
CoRE Stack is currently being utilized by a network of 19 Civil Society Organizations (CSOs) across 5 Indian states: Odisha, Rajasthan, Bihar, Jharkhand, and Karnataka. The demand for similar support was being raised by many partners.
Hydro Stack will help in automatically generating the base hydro-geomorphic layers on which other interoperable layers will be integrated and thus CoRE Stack can be instantiated for any region in the world according to the need. This makes the evidence-based watershed and resource management approach of CoRE Stack available in a distributed fashion without need for a centralized authority.
Limitations of Hydro Stack
Some of the limitations that exist with Hydro Stack is that the initial delineation threshold is a fixed heuristic value. Also, the outputs have not been validated against reference delineation. Depression handling is limited to filling, and large basins need a lot of RAM.
Future work includes breaching, maybe also including stream burning or hybrid conditioning approaches, validation of the products, and continental-scale runs.
Try it yourself
Everything is containerized with Docker, so anyone can reproduce the results or adapt the pipeline to a new region or parameter set. The code is at github.com/mastershubham/hydro_stack. When a delineation drives real decisions, being able to inspect it, re-run it and challenge it is as important as the map or the final product itself.
Where to engage further
Usage Docs: https://github.com/mastershubham/hydro_stack/blob/main/README.md
Developer Docs: https://github.com/mastershubham/hydro_stack/wiki/Hydro-Stack
Link to the Paper: https://eartharxiv.org/repository/view/15893/
