v2.3.0 — PADR-Net Flood Forecasting Application

Released: June 2026

Summary

This backward-compatible minor release adds PADR-Net, a physics-aware flood-forecasting application module built on the BaseAttentive API style. It introduces a validated configuration object, TensorFlow and PyTorch backend implementations, hydrological metrics and physics helpers, a dedicated documentation page, and two end-to-end notebooks for standard and advanced flood-forecasting workflows.

The existing BaseAttentive API remains unchanged.

PADR-Net Application API

• New base_attentive.applications.flood package providing a public flood-forecasting application surface:

  • PADRNet — backend-neutral public factory.

  • PADRNetConfig — validated configuration dataclass.

  • create_padrnet — functional factory equivalent to PADRNet(...).

  • metrics.py — hydrological skill metrics.

  • physics.py — lightweight hydrological helper functions.

• Top-level lazy exports added so users can write:

  from base_attentive import PADRNet, PADRNetConfig
  

  without forcing eager backend imports during package import.

• Validated PADR-Net parameter handling follows the same validate_params style used by the main BaseAttentive API. The configuration checks dimensionality, horizon length, attention-head compatibility, dropout bounds, physics weights, flood threshold, and reservoir-response scale.

Backend Implementations

• TensorFlow PADR-Net implementation added under base_attentive.implementations.tensorflow.padrnet.

  The TensorFlow model returns a dictionary with:

  • "depth" — multi-horizon water-depth forecast.

  • "exceedance_probability" — smooth flood-threshold probability.

  • "features" — latent event representation.

• PyTorch PADR-Net implementation added under base_attentive.implementations.torch.padrnet with the same output contract as TensorFlow.

• Backend models inherit the package learner mixin where appropriate, preserving the same parameter-management basis used by existing neural learners.

• TensorFlow/Keras registration compatibility hardened for environments where TensorFlow 2.x and Keras packaging differ. The implementation uses compatible registration paths and layer fallbacks where needed.

Hydrological Metrics and Physics Helpers

• Flood metrics added:

  • nash_sutcliffe_efficiency

  • critical_success_index

  • true_skill_statistic

  • delta_mass

• Backend-neutral physics helpers added:

  • linear_reservoir_response

  • mass_balance_residual

  • exceedance_probability

These helpers are intentionally lightweight. They support examples, diagnostics, and custom training loops while allowing real projects to replace them with richer hydrodynamic or hydrological operators.

Documentation

• Dedicated PADR-Net guide added: docs/padrnet.rst.

  The guide covers model motivation, input and output tensor contracts, physics-aware mathematical formulation, validated configuration, TensorFlow and PyTorch examples, hydrological diagnostics, interpretation workflow, API reference links, and references.

• API reference updated with PADR-Net classes, factory, metrics, and physics helpers.

• Main documentation index updated to include the PADR-Net guide in the user-guide toctree.

• PADR-Net class docstring expanded with rST math, parameter documentation, examples, notes, see-also entries, and references suitable for Sphinx autodoc.

New Example Notebooks

• 14 — PADR-Net Flood Forecasting (examples/14_padrnet_flood_forecasting.ipynb)

  A complete introductory PADR-Net workflow using synthetic regional flood events for WAF, EAF, and SAF:

  • validated PADRNetConfig setup,

  • TensorFlow PADR-Net model creation,

  • custom physics-aware training loop,

  • NSE, CSI, TSS, and mass-bias evaluation,

  • hydrograph interpretation plots,

  • spatial-style 2×3 reference-vs-forecast diagnostic maps,

  • latent event-space visualization,

  • optional PyTorch backend smoke test,

  • exercises for thresholds, physics ablation, transfer, and real data.

• 15 — Advanced PADR-Net Workflow (examples/15_padrnet_advanced_workflow.ipynb)

  An advanced experiment notebook focused on model evidence and reviewer-facing diagnostics:

  • leave-one-region-out transfer testing,

  • physics-loss ablation,

  • flood-threshold calibration curves,

  • Monte-Carlo dropout uncertainty intervals,

  • rainfall-intensification stress testing,

  • exercises for transfer, calibration, uncertainty, and real scenario forcing.

Testing and Validation

• PADR-Net tests added in tests/test_padrnet_flood.py. The tests cover configuration validation, invalid attention-head combinations, backend normalization, flood metrics, hydrological physics helpers, and backend smoke paths where available.

• Notebook smoke checks were run for both PADR-Net notebooks in the TensorFlow environment. The advanced workflow was verified with both reduced and full executions.

Package Metadata

• Package version bumped to 2.3.0.

• Package keywords expanded with flood forecasting, hydrology, and physics-informed learning terms.

Compatibility Notes

• Existing BaseAttentive code remains backward-compatible.

• PADR-Net requires either the TensorFlow extra or the Torch extra for concrete model execution.

• The hydrological helper functions depend only on NumPy and can be used without installing a deep-learning backend.