Hapi: A Multivariable Land-Surface Transformer for Medium-Range Hydrological Forecasting at Continental Scale
Organizations: Argonne National Laboratory, Lemont, IL 60439, USA
Abstract
Accurate flood forecasts several days in advance are essential for flood control, water-resource management, and emergency response. A central challenge is to produce high-resolution forecasts across continental domains where hydrological behavior varies widely from place to place. We developed Hapi, a U-Net Swin Transformer that uses fine three-dimensional patches and hierarchical shifted-window attention to forecast river discharge, surface runoff, snow water equivalent, and soil wetness index across the contiguous United States. The model produces medium-range forecasts (24--72~h) at resolution with adaptive task weighting and required only 0.11 seconds for a four-variable 72-h CONUS forecast on one A100 GPU. In a held-out 2024 potential-skill evaluation with ERA5-Land inputs prescribed over the forecast horizon, Hapi achieved the highest F1-score for floods in 20 of 21 comparisons across seven GloFAS return periods and three forecast leads. Independent validation against observed daily discharge at 3{,}881 U.S. Geological Survey gauges showed that Hapi achieved the highest median Nash--Sutcliffe efficiency at every lead, supported by regional-cluster bootstrap intervals. In a matched 24-h comparison of loss formulations, adaptive task balancing produced the lowest discharge errors and the highest F1-score for floods.
Figures & tables
| Role | Source | Variables and units |
|---|---|---|
| Prognostic | GloFAS reanalysis | River discharge, m 3 s -1 ; runoff water equivalent, mm; snow water equivalent, mm; soil wetness index, dimensionless |
| Forcing | ERA5-Land | Total runoff, ro , m; precipitation, tp , m; evaporation, e , m; soil water in layer 1, swvl1 , m 3 m -3 ; solar radiation, ssrd , J m -2 ; 2 m air temperature, t2m , K |
| Static | DEM; GloFAS v4.0 | Surface elevation, m; upstream drainage area, m 2 |
| Return period, years | ||||||||
|---|---|---|---|---|---|---|---|---|
| Model | Lead | 1.5 | 2 | 5 | 10 | 20 | 50 | 100 |
| persistence | 24 h | 0.836 | 0.799 | 0.709 | 0.627 | 0.562 | 0.496 | 0.470 |
| GloFAS | 24 h | 0.773 | 0.718 | 0.584 | 0.473 | 0.396 | 0.306 | 0.264 |
| RiverMamba | 24 h | 0.728 | 0.660 | 0.479 | 0.347 | 0.259 | 0.187 | 0.145 |
| Hapi | 24 h | 0.885 | 0.863 | 0.786 | 0.700 | 0.612 | 0.524 | 0.468 |
| persistence | 48 h | 0.726 | 0.671 | 0.544 | 0.434 | 0.353 | 0.275 | 0.233 |
| 24 h lead | 48 h lead | 72 h lead | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Model | MAE | RMSE | NSE | KGE | MAE | RMSE | NSE | KGE | MAE | RMSE | NSE | KGE |
| persistence | 2.43 | 41.64 | 0.996 | 0.998 | 4.55 | 78.38 | 0.985 | 0.992 | 6.30 | 109.68 | 0.970 | 0.985 |
| GloFAS | 2.79 | 43.29 | 0.995 | 0.997 | 2.94 | 44.59 | 0.995 | 0.997 | 3.15 | 46.90 | 0.995 | 0.997 |
| RiverMamba | 2.11 | 35.67 | 0.997 | 0.997 | 3.05 | 54.53 | 0.993 | 0.993 | 3.80 | 70.46 | 0.988 | 0.986 |
| Hapi | 1.57 | 32.30 | 0.997 | 0.990 | 2.94 | 63.19 | 0.990 | 0.980 | 4.08 | 89.72 | 0.980 | 0.976 |
| Lead | Model | Median NSE | Median KGE | Median | Hapi wins vs. | |
|---|---|---|---|---|---|---|
| % cells | median NSE | |||||
| 24 h | Hapi | 0.902 | 0.891 | 0.973 | – | – |
| persistence | 0.823 | 0.911 | 1.000 | 89.4% | +0.054 | |
| GloFAS | 0.698 | 0.804 | 0.993 | 93.0% | +0.142 | |
| 48 h | Hapi | 0.823 | 0.832 | 0.967 | – | – |
| persistence | 0.560 | 0.779 | 1.000 | 91.5% | +0.217 | |
| Lead | Model | NSE | KGE | RMSE | PBIAS | ||
|---|---|---|---|---|---|---|---|
| median | median | m 3 /s | % | % | % | ||
| 24 h | Hapi | 0.160 | 0.310 | 19.4 | +1.2 | 59.7 | 23.2 |
| GloFAS | 0.076 | 0.273 | 20.6 | +4.8 | 54.7 | 20.9 | |
| persistence | 0.070 | 0.271 | 20.9 | +5.3 | 54.8 | 18.6 | |
| 48 h | Hapi | 0.165 | 0.312 | 19.3 | +0.5 | 59.7 | 23.4 |
| GloFAS | 0.064 | 0.271 | 20.8 | +4.7 | 54.4 | 20.0 |
| F1 by GloFAS return period, yr | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Variant | MAE | RMSE | NSE | KGE | 1.5 | 2 | 5 | 10 | 20 | 50 | 100 |
| Full Hapi | 1.57 | 32.30 | 0.997 | 0.990 | 0.885 | 0.863 | 0.786 | 0.700 | 0.612 | 0.524 | 0.468 |
| Discharge-only | 2.07 | 41.14 | 0.996 | 0.992 | 0.869 | 0.842 | 0.761 | 0.672 | 0.593 | 0.522 | 0.481 |
| F1 by GloFAS return period, yr | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Variant | MAE | RMSE | NSE | KGE | 1.5 | 2 | 5 | 10 | 20 | 50 | 100 |
| Learned task scales | 1.59 | 30.94 | 0.998 | 0.990 | 0.877 | 0.856 | 0.779 | 0.690 | 0.601 | 0.513 | 0.460 |
| Uniform task weights | 1.97 | 38.71 | 0.996 | 0.985 | 0.830 | 0.802 | 0.710 | 0.607 | 0.505 | 0.410 | 0.345 |
| Fixed task scales | 1.64 | 31.77 | 0.997 | 0.987 | 0.856 | 0.835 | 0.748 | 0.647 | 0.544 | 0.445 | 0.382 |
| Variable | Lead | Model | RMSE | MAE | NSE | KGE |
| Runoff water equivalent, 418,792 cells | ||||||
| 24 h | Hapi | 1.8580 | 0.2850 | 0.3281 | ||
| persistence | 0.4156 | |||||
| 48 h | Hapi | 1.8900 | 0.2999 | 0.3107 | 0.3365 | |
| persistence | ||||||
| 72 h | Hapi | 1.9070 | 0.3105 | 0.2980 | 0.3327 | |
| Subset | Lead | Model | 1.5-yr | 2-yr | 5-yr | 10-yr | 20-yr | 50-yr | 100-yr |
|---|---|---|---|---|---|---|---|---|---|
| AIFAS | 24 h | Hapi | 0.895 | 0.870 | 0.785 | 0.690 | 0.585 | 0.461 | 0.366 |
| RM | 0.755 | 0.681 | 0.505 | 0.366 | 0.282 | 0.212 | 0.159 | ||
| 48 h | Hapi | 0.846 | 0.807 | 0.687 | 0.551 | 0.420 | 0.259 | 0.174 | |
| RM | 0.722 | 0.641 | 0.459 | 0.321 | 0.236 | 0.158 | 0.101 | ||
| 72 h | Hapi | 0.816 | 0.767 | 0.633 | 0.481 | 0.344 | 0.182 | 0.116 | |
| RM | 0.679 | 0.604 | 0.420 | 0.289 | 0.212 | 0.131 | 0.084 |
| Log-noise amplitude | |||||
|---|---|---|---|---|---|
| Lead | Metric | 0.00 | 0.20 | 0.50 | 1.00 |
| 48 h | F1 @ 1.5-yr | 0.833 | 0.827 | 0.800 | 0.709 |
| F1 @ 5-yr | 0.691 | 0.677 | 0.602 | 0.357 | |
| F1 @ 20-yr | 0.460 | 0.442 | 0.334 | 0.114 | |
| F1 @ 100-yr | 0.269 | 0.254 | 0.168 | 0.039 | |
| NSE | 0.990 | 0.990 | 0.990 | 0.987 | |
| System | Spatial units | Params | Leads | Time | Memory | Normalized time |
|---|---|---|---|---|---|---|
| M | GB | s/unit/lead | ||||
| Hapi | 589,824 grid cells | 43.96 | 3 | 109.5 ms | 1.69 | 0.062 |
| RiverMamba | 6,221,926 river points | 4.38 | 7 | 13.75 s | 13.33 | 0.316 |
Appendix figures & tables17 assets
Supplementary material from the paper’s appendix.
Appendix
| Variable | Norm | Skew | Zero % | Max/Med | Rationale |
|---|---|---|---|---|---|
| River discharge | log1p | 38.9 | 35% | Extreme skew, 6 orders of magnitude | |
| Runoff water equiv. | log1p | 10.5 | 33% | Heavy right skew | |
| Snow water equivalent | log1p | 118.5 | 78% | † | Extreme skew and seasonal absence |
| Soil wetness index | identity | 0.0 | 0% | 2.2 | Already bounded in |
| Runoff | log1p | 11.7 | 4% | Heavy right skew | |
| Total precipitation | log1p | 5.8 | 8% | Heavy right skew |
| Hyperparameter | Values |
|---|---|
| Encoder depth schedule | , , , , , , |
| Embedding dimension | 48, 96, 192, 240 |
| Patch size | 2, 4 |
| Window size | 4, 8 |
| Component | Tokens | Width | MACs, billion |
| Backbone, 2 blocks | 147,456 | 192 | 148.6 |
| Backbone, 4 blocks | 36,864 | 384 | 289.9 |
| Backbone, 4 blocks | 9,216 | 768 | 286.3 |
| Patch embedding | 147,456 | 192 | 2.7 |
| Merge, unmerge, and skip projections | — | — | 65.2 |
| Output expansion and projection | — | — | 22.2 |
| Return period (years) | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| Lead | 1.5 | 2 | 5 | 10 | 20 | 50 | 100 | 200 | 500 |
| 96 h (4 d) | 0.580 | 0.542 | 0.352 | 0.224 | 0.146 | 0.078 | 0.049 | 0.030 | 0.017 |
| 120 h (5 d) | 0.566 | 0.518 | 0.328 | 0.200 | 0.124 | 0.063 | 0.036 | 0.022 | 0.013 |
| 144 h (6 d) | 0.571 | 0.490 | 0.283 | 0.160 | 0.090 | 0.041 | 0.024 | 0.014 | 0.009 |
| 168 h (7 d) | 0.477 | 0.458 | 0.268 | 0.151 | 0.084 | 0.037 | 0.023 | 0.016 | 0.010 |
| Model | Lead | 200-yr F1 | 500-yr F1 |
|---|---|---|---|
| persistence | 24 h | 0.459 | 0.431 |
| GloFAS | 24 h | 0.234 | 0.196 |
| RiverMamba | 24 h | 0.114 | 0.086 |
| Hapi | 24 h | 0.429 | 0.367 |
| persistence | 48 h | 0.199 | 0.149 |
| GloFAS | 48 h | 0.154 | 0.117 |
| 24 h | 48 h | 72 h | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Subset | Model | MAE | NSE | KGE | MAE | NSE | KGE | MAE | NSE | KGE |
| AIFAS | Hapi | 4.14 | 1.00 | 0.99 | 7.84 | 0.99 | 0.98 | 10.91 | 0.98 | 0.98 |
| RM | 5.39 | 1.00 | 1.00 | 7.89 | 0.99 | 0.99 | 9.91 | 0.99 | 0.99 | |
| flood-active | Hapi | 1.56 | 0.99 | 0.97 | 2.77 | 0.97 | 0.95 | 3.67 | 0.96 | 0.93 |
| RM | 2.90 | 0.98 | 0.99 | 4.10 | 0.95 | 0.97 | 4.83 | 0.94 | 0.97 | |
| Small rivers | Hapi | 0.10 | 0.82 | 0.82 | 0.13 | 0.78 | 0.81 | 0.15 | 0.76 | 0.80 |
| Return period (yr) | 1.5 | 2 | 5 | 10 | 20 | 50 | 100 |
|---|---|---|---|---|---|---|---|
| Exceeding cells per day | 7,883 | 3,453 | 689 | 270 | 126 | 59 | 36 |
| Lag-1 autocorrelation | 0.938 | 0.908 | 0.847 | 0.747 | 0.652 | 0.614 | 0.594 |
| (d) | 42.3 | 25.7 | 10.0 | 4.8 | 3.5 | 3.0 | 2.7 |
| Block length | 7 d | 15 d | 21 d | 30 d | 45 d | 60 d |
|---|---|---|---|---|---|---|
| F1, Hapi – persistence | 14 | 14 | 14 | 14 | 12 | 13 |
| F1, Hapi – GloFAS | 17 | 17 | 17 | 18 | 17 | 21 |
| F1, Hapi – RiverMamba | 21 | 21 | 21 | 21 | 21 | 21 |
| SEDI, Hapi – persistence | 12 | 12 | 12 | 12 | 12 | 12 |
| SEDI, Hapi – GloFAS | 17 | 16 | 16 | 17 | 16 | 19 |
| SEDI, Hapi – RiverMamba | 7 | 7 | 6 | 6 | 6 | 6 |
| Return period (years) | ||||||||
| Model | Lead | 1.5 | 2 | 5 | 10 | 20 | 50 | 100 |
| Precision | ||||||||
| persistence | 24 h | 0.836 | 0.800 | 0.709 | 0.627 | 0.562 | 0.496 | 0.470 |
| persistence | 48 h | 0.726 | 0.672 | 0.544 | 0.434 | 0.353 | 0.275 | 0.233 |
| persistence | 72 h | 0.653 | 0.590 | 0.447 | 0.334 | 0.256 | 0.177 | 0.140 |
| GloFAS | 24 h | 0.778 | 0.723 | 0.590 | 0.478 | 0.405 | 0.314 | 0.267 |