r.watersheds: New addon for OpenMP parallel watershed delineation based on Cho (2025)

[HuidaeCho]

This new addon r.watersheds can delineate a large number of watersheds in parallel using OpenMP. It's based on MESHED (Cho, 2025). Its name is just... +s to r.watershed and not very creative.

• r.delineatewatersheds, r.delineate.watersheds, r.watersheddelineation (hmm... too long)
• r.pwatersheds, r.parwatersheds, r.par.watersheds (parallel watersheds)
• r.mpwatersheds, r.mp.watersheds (multi-processing watersheds, but currently no OpenMP modules use any prefix)
• r.midas.watersheds (and rename r.flowaccumulation to r.midas.accumulate)
• Who cares? Just r.watersheds (bash autocompletion hates it because it finds r.watershed first...)

[wenzeslaus]

About the name:

An addon r.pops.spread is using name of the model - PoPS. The group of tools r.futures similarly are using FUTURES in their name. So, r.midas.abc or r.mashed.abc would make sense. However, tools implementing PoPS and FUTURES models are specific models doing their specific forecast or processing steps related to it. The outputs here are general, so I can see the case also for just using more plain name without an algorithm/method name.

We did have addon tools with mp for multiprocessing in their name, but that was only before the parallel code got merged into the main repo to distinguish identical tools which differed only in parallelization. That's not the case here and this seems like "its own thing" as opposed to parallel version of X. So, I would be against the par and mp variants.

[HuidaeCho]

About the name:

An addon r.pops.spread is using name of the model - PoPS. The group of tools r.futures similarly are using FUTURES in their name. So, r.midas.abc or r.mashed.abc would make sense. However, tools implementing PoPS and FUTURES models are specific models doing their specific forecast or processing steps related to it. The outputs here are general, so I can see the case also for just using more plain name without an algorithm/method name.

Yes, both r.flowaccumulation and r.watersheds produce general outputs that can be used with other modules, and r.midas.* wouldn't generate midas-specific datasets. They are just general raster modules for hydrology.

We did have addon tools with mp for multiprocessing in their name, but that was only before the parallel code got merged into the main repo to distinguish identical tools which differed only in parallelization. That's not the case here and this seems like "its own thing" as opposed to parallel version of X. So, I would be against the par and mp variants.

Agreed. For now, I'll keep r.watersheds.

[petrasovaa]

I don't have any idea on the name, but I would find it helpful to explain how to use it in the context of other available tools... The example shows you need r.watershed for the drainage, so it would be good to explain why a user would want to use this tool instead of just r.watershed. Generally speaking, we have a lot hydrology tools, which is great, but it is getting really confusing, so I think we need some overview of (possibly overlapping) functionality, and advantages (speed, more precise) and examples of workflows and use cases (when a certain tool is better, which tools work together etc.)

[HuidaeCho]

I don't have any idea on the name, but I would find it helpful to explain how to use it in the context of other available tools... The example shows you need r.watershed for the drainage, so it would be good to explain why a user would want to use this tool instead of just r.watershed. Generally speaking, we have a lot hydrology tools, which is great, but it is getting really confusing, so I think we need some overview of (possibly overlapping) functionality, and advantages (speed, more precise) and examples of workflows and use cases (when a certain tool is better, which tools work together etc.)

Yes, there are many hydrology modules and it can be confusing. Let me add something to the manual.