Add docs, benchmarks, and user guide notebook for flood module

- docs/source/reference/flood.rst: API reference (autosummary)
- benchmarks/benchmarks/flood.py: ASV benchmarks for all four functions
- examples/user_guide/12_Flood_Analysis.ipynb: walkthrough notebook
  covering HAND-based inundation, flood depth, CN runoff, and travel time
- README.md: add Flood section to the feature matrix
- docs/source/reference/index.rst: register flood in toctree

Author: brendancol

README.md

@@ -255,6 +255,17 @@ In the GIS world, rasters are used for representing continuous phenomena (e.g. e
 
 -----------
 
+### **Flood**
+
+| Name | Description | NumPy xr.DataArray | Dask xr.DataArray | CuPy GPU xr.DataArray | Dask GPU xr.DataArray |
+|:----------:|:------------|:----------------------:|:--------------------:|:-------------------:|:------:|
+| [Flood Depth](xrspatial/flood.py) | Computes water depth above terrain from a HAND raster and water level | ✅️ | ✅️ | ✅️ | ✅️ |
+| [Inundation](xrspatial/flood.py) | Produces a binary flood/no-flood mask from a HAND raster and water level | ✅️ | ✅️ | ✅️ | ✅️ |
+| [Curve Number Runoff](xrspatial/flood.py) | Estimates runoff depth from rainfall using the SCS/NRCS curve number method | ✅️ | ✅️ | ✅️ | ✅️ |
+| [Travel Time](xrspatial/flood.py) | Estimates overland flow travel time via simplified Manning's equation | ✅️ | ✅️ | ✅️ | ✅️ |
+
+-----------
+
 ### **Zonal**
 
 | Name | Description | NumPy xr.DataArray | Dask xr.DataArray | CuPy GPU xr.DataArray | Dask GPU xr.DataArray |

benchmarks/benchmarks/flood.py

@@ -0,0 +1,106 @@
+from xrspatial import (
+    flow_direction, flow_accumulation, hand, slope, flow_length,
+)
+from xrspatial.flood import (
+    flood_depth, inundation, curve_number_runoff, travel_time,
+)
+
+from .common import get_xr_dataarray
+
+
+class FloodDepth:
+    params = ([100, 300, 1000], ["numpy", "dask"])
+    param_names = ("nx", "type")
+
+    def setup(self, nx, type):
+        ny = nx // 2
+        elev = get_xr_dataarray((ny, nx), "numpy")
+        flow_dir = flow_direction(elev)
+        flow_accum = flow_accumulation(flow_dir)
+        self.hand_agg = hand(flow_dir, flow_accum, elev)
+
+        if type == "dask":
+            import dask.array as da
+            chunks = (max(1, ny // 2), max(1, nx // 2))
+            self.hand_agg.data = da.from_array(
+                self.hand_agg.data, chunks=chunks,
+            )
+
+    def time_flood_depth(self, nx, type):
+        result = flood_depth(self.hand_agg, water_level=5.0)
+        if hasattr(result.data, 'compute'):
+            result.data.compute()
+
+
+class Inundation:
+    params = ([100, 300, 1000], ["numpy", "dask"])
+    param_names = ("nx", "type")
+
+    def setup(self, nx, type):
+        ny = nx // 2
+        elev = get_xr_dataarray((ny, nx), "numpy")
+        flow_dir = flow_direction(elev)
+        flow_accum = flow_accumulation(flow_dir)
+        self.hand_agg = hand(flow_dir, flow_accum, elev)
+
+        if type == "dask":
+            import dask.array as da
+            chunks = (max(1, ny // 2), max(1, nx // 2))
+            self.hand_agg.data = da.from_array(
+                self.hand_agg.data, chunks=chunks,
+            )
+
+    def time_inundation(self, nx, type):
+        result = inundation(self.hand_agg, water_level=5.0)
+        if hasattr(result.data, 'compute'):
+            result.data.compute()
+
+
+class CurveNumberRunoff:
+    params = ([100, 300, 1000], ["numpy", "dask"])
+    param_names = ("nx", "type")
+
+    def setup(self, nx, type):
+        ny = nx // 2
+        self.rainfall = get_xr_dataarray((ny, nx), type)
+        # Make all values positive for rainfall
+        import numpy as np
+        if type == "numpy":
+            self.rainfall.data = np.abs(self.rainfall.data) + 1.0
+        else:
+            import dask.array as da
+            self.rainfall.data = da.abs(self.rainfall.data) + 1.0
+
+    def time_curve_number_runoff(self, nx, type):
+        result = curve_number_runoff(self.rainfall, curve_number=80.0)
+        if hasattr(result.data, 'compute'):
+            result.data.compute()
+
+
+class TravelTime:
+    params = ([100, 300, 1000], ["numpy", "dask"])
+    param_names = ("nx", "type")
+
+    def setup(self, nx, type):
+        ny = nx // 2
+        elev = get_xr_dataarray((ny, nx), "numpy")
+        flow_dir = flow_direction(elev)
+        self.slope_agg = slope(elev)
+        self.flow_length_agg = flow_length(flow_dir)
+
+        if type == "dask":
+            import dask.array as da
+            chunks = (max(1, ny // 2), max(1, nx // 2))
+            self.slope_agg.data = da.from_array(
+                self.slope_agg.data, chunks=chunks,
+            )
+            self.flow_length_agg.data = da.from_array(
+                self.flow_length_agg.data, chunks=chunks,
+            )
+
+    def time_travel_time(self, nx, type):
+        result = travel_time(
+            self.flow_length_agg, self.slope_agg, mannings_n=0.03,
+        )
+        if hasattr(result.data, 'compute'):
+            result.data.compute()

docs/source/reference/flood.rst

@@ -0,0 +1,33 @@
+..  _reference.flood:
+
+*****
+Flood
+*****
+
+Flood Depth
+===========
+.. autosummary::
+    :toctree: _autosummary
+
+    xrspatial.flood.flood_depth
+
+Inundation
+==========
+.. autosummary::
+    :toctree: _autosummary
+
+    xrspatial.flood.inundation
+
+Curve Number Runoff
+===================
+.. autosummary::
+    :toctree: _autosummary
+
+    xrspatial.flood.curve_number_runoff
+
+Travel Time
+===========
+.. autosummary::
+    :toctree: _autosummary
+
+    xrspatial.flood.travel_time

docs/source/reference/index.rst

@@ -8,6 +8,7 @@ Reference
    :maxdepth: 2
 
    classification
+   flood
    focal
    multispectral
    pathfinding