PADR-Net Flood Forecasting

PADR-Net is the flood-forecasting application module in BaseAttentive. It provides a small, validated public API for building a Physics-Aware Depth-Response Network with either TensorFlow or PyTorch while keeping the same configuration object, output contract, and hydrological helper functions.

The model is intended for event-scale flood forecasting where dynamic forcing histories, optional static basin descriptors, and physics-aware diagnostics must be handled together. Typical inputs include rainfall, antecedent precipitation, soil-moisture proxies, runoff or river-stage history, topographic descriptors, land-cover summaries, and basin area or slope metadata.

Why PADR-Net?

BaseAttentive is a general sequence model. PADR-Net is more specific: it is designed around flood depth, flood-threshold exceedance, and hydrological consistency. This makes it useful when the result should be interpreted as a water-depth forecast rather than an arbitrary sequence prediction.

PADR-Net is useful when you need to combine attention-based sequence modelling [PADRG3] with hydrological response diagnostics [PADRG1], [PADRG2]. In practice, this means you can:

predict multi-step flood depth from forcing histories;
keep a stable public API across TensorFlow and PyTorch;
expose exceedance probabilities from a configured flood threshold;
combine statistical accuracy with physics-aware penalties;
report hydrological metrics such as NSE, CSI, TSS, and mass bias.

Conceptual Model 

Let \(\mathbf{X}_{1:T}\) denote a dynamic sequence of forcing and state variables, and let \(\mathbf{s}\) denote optional static descriptors for the basin, region, or grid cell. PADR-Net learns a latent temporal representation

\[\mathbf{z}_{1:T} = f_{\theta}(\mathbf{X}_{1:T}, \mathbf{s}),\]

then decodes it into a non-negative multi-horizon depth forecast:

\[\hat{\mathbf{h}}_{1:H} = \operatorname{softplus} \left(g_{\theta}(\mathbf{z}_{1:T})\right).\]

The model also computes a smooth flood-threshold exceedance probability,

\[p_t = \sigma \left( \frac{\hat{h}_t - h_{\mathrm{crit}}}{\alpha} \right),\]

where \(h_{\mathrm{crit}}\) is the configured flood threshold and \(\alpha\) controls how sharp the transition is around the threshold.

Physics-Aware Objective 

PADR-Net itself returns model predictions. Training code can combine the prediction loss with physics-aware regularization terms:

\[\mathcal{L} = \mathcal{L}_{\mathrm{pred}} + \lambda_{\mathrm{phys}} \lVert r_{\mathrm{phys}} \rVert_2^2 + \lambda_{\mathrm{mass}} \lvert \Delta M \rvert + \lambda_{\mathrm{smooth}} \lVert \nabla_t \hat{\mathbf{h}} \rVert_2^2 .\]

For a simple rainfall-storage response, a residual can be written as

\[r_t = \frac{d h_t}{d t} - \left( \gamma P_t - \frac{h_t}{\tau} \right),\]

with rainfall forcing \(P_t\), rainfall-depth gain \(\gamma\), and reservoir response time \(\tau\). The helper functions in base_attentive.applications.flood.physics provide reusable forms of these diagnostics.

Input and Output Contract 

The public model factory is PADRNet. It accepts a PADRNetConfig and returns a concrete backend model.

Object	Shape	Meaning
`dynamic_inputs`	`(batch, time, input_dim)`	Time-varying forcing and state features.
`static_inputs`	`(batch, static_dim)`	Optional basin, region, or grid-cell descriptors.
`outputs["depth"]`	`(batch, forecast_horizon, 1)`	Forecast flood depth.
`outputs["exceedance_probability"]`	`(batch, forecast_horizon, 1)`	Smooth probability of exceeding the flood threshold.
`outputs["features"]`	Backend-dependent latent shape	Learned temporal event representation.

Configuration 

PADRNetConfig is a validated dataclass. It follows the same validate_params pattern used by the main BaseAttentive API, so invalid dimensionality, negative horizons, incompatible attention heads, and invalid probability-like weights are caught early.

from base_attentive import PADRNetConfig

config = PADRNetConfig(
    input_dim=8,
    static_dim=3,
    hidden_dim=64,
    num_heads=4,
    num_layers=2,
    forecast_horizon=24,
    dropout=0.1,
    lambda_physics=0.1,
    lambda_mass=0.05,
    lambda_smooth=0.01,
    flood_threshold=0.05,
    reservoir_tau=24.0,
)

The most important parameters are:

input_dim: Number of dynamic forcing and state variables at each historical time step.
static_dim: Number of optional time-invariant descriptors. Set this to 0 when no static stream is used.
hidden_dim: Latent channel width used by the temporal encoder and decoder.
num_heads: Number of attention heads. hidden_dim must be divisible by num_heads.
forecast_horizon: Number of future steps predicted by the depth head.
lambda_physics, lambda_mass, lambda_smooth: Weights intended for training-time physics, mass-balance, and temporal smoothness penalties.
flood_threshold: Water-depth threshold used to convert depth into exceedance probability.
reservoir_tau: Response time scale for simple storage-style hydrological diagnostics.

Backend Examples 

PyTorch 

import torch
from base_attentive import PADRNet, PADRNetConfig

config = PADRNetConfig(
    input_dim=8,
    static_dim=3,
    hidden_dim=64,
    num_heads=4,
    forecast_horizon=24,
)

model = PADRNet(config, backend="torch")

x = torch.zeros(2, 48, 8)
s = torch.zeros(2, 3)
outputs = model(x, s)

depth = outputs["depth"]
exceedance = outputs["exceedance_probability"]

TensorFlow 

import tensorflow as tf
from base_attentive import PADRNet, PADRNetConfig

config = PADRNetConfig(
    input_dim=8,
    static_dim=3,
    hidden_dim=64,
    num_heads=4,
    forecast_horizon=24,
)

model = PADRNet(config, backend="tensorflow")

x = tf.zeros((2, 48, 8))
s = tf.zeros((2, 3))
outputs = model(x, s)

depth = outputs["depth"]
exceedance = outputs["exceedance_probability"]

Metrics and Diagnostics 

PADR-Net is usually evaluated with both continuous depth skill and threshold-event skill. The flood application module exposes helpers for common diagnostics:

from base_attentive.applications.flood import (
    critical_success_index,
    delta_mass,
    nash_sutcliffe_efficiency,
    true_skill_statistic,
)

observed = [0.0, 0.1, 0.2, 0.15]
predicted = [0.0, 0.08, 0.18, 0.12]

nse = nash_sutcliffe_efficiency(observed, predicted)
csi = critical_success_index(
    observed,
    predicted,
    threshold=0.05,
)
tss = true_skill_statistic(
    observed,
    predicted,
    threshold=0.05,
)
mass_bias = delta_mass(observed, predicted)

NSE summarizes continuous depth agreement. CSI and TSS evaluate flooded-threshold detection. delta_mass summarizes the signed difference between predicted and reference water volume or depth accumulation.

Physics Helpers 

The physics helpers are intentionally separate from the model class so that training loops can combine them in different ways:

from base_attentive.applications.flood import (
    exceedance_probability,
    linear_reservoir_response,
    mass_balance_residual,
)

prob = exceedance_probability(
    depth=[0.0, 0.04, 0.08],
    threshold=0.05,
)

response = linear_reservoir_response(
    precipitation=[1.0, 3.0, 2.0],
    tau=24.0,
)

residual = mass_balance_residual(
    precipitation=[1.0, 3.0, 2.0],
    depth=[0.0, 0.04, 0.08],
    tau=24.0,
)

Interpretation Workflow 

A strong flood-forecasting result should usually report three views:

Hydrodynamic agreement: compare PADR-Net peak depth against a reference hydrodynamic or hydrological-model response using a shared water-depth color scale.
Threshold-event skill: report flooded / non-flooded detection with CSI, TSS, hit rate, false-alarm rate, and threshold boundary overlays.
Physical consistency: show whether the prediction respects plausible temporal response, mass-balance tendency, and smoothness constraints. This follows the broader idea that neural flood models should be evaluated not only by point accuracy, but also by whether the learned response remains hydrologically plausible [PADRG4], [PADRG5].

For regional transfer experiments, use the same configuration and evaluation protocol across regions, then report source-region, target-region, and leave-one-region-out skill. This is often more convincing than a single in-region test because it tests whether the learned response transfers beyond the calibration domain.

API Reference Links 

The generated API reference for the flood application is available in API Reference. The most important public objects are base_attentive.applications.flood.PADRNet, base_attentive.applications.flood.PADRNetConfig, base_attentive.applications.flood.create_padrnet(), base_attentive.applications.flood.metrics, and base_attentive.applications.flood.physics.

References 

[PADRG1]

Nash, J. E. and Sutcliffe, J. V. (1970). River flow forecasting through conceptual models part I: A discussion of principles. Journal of Hydrology, 10(3), 282–290.

[PADRG2]

Beven, K. J. (2012). Rainfall-Runoff Modelling: The Primer. Wiley-Blackwell.

[PADRG3]

Vaswani, A., Shazeer, N., Parmar, N., Uszkoreit, J., Jones, L., Gomez, A. N., Kaiser, L., and Polosukhin, I. (2017). Attention is all you need. Advances in Neural Information Processing Systems, 30.

[PADRG4]

Kratzert, F., Klotz, D., Brenner, C., Schulz, K., and Herrnegger, M. (2018). Rainfall-runoff modelling using Long Short-Term Memory networks. Hydrology and Earth System Sciences, 22, 6005–6022.

[PADRG5]

Karniadakis, G. E., Kevrekidis, I. G., Lu, L., Perdikaris, P., Wang, S., and Yang, L. (2021). Physics-informed machine learning. Nature Reviews Physics, 3, 422–440.