Hydrological models are indispensable tools for understanding the functioning of hydrosystems, flood and low-flow forecasting, sustainable water management and infrastructure design, environmental protection, and adaptation to a changing climate. Indeed, measurements of hydrological responses are not ubiquitously available (e.g., ), while “everywhere relevant” estimation of hydrological state fluxes is expected. A model is hence needed to extend and predict those quantities of interest based on available data.

High-resolution spatial datasets have become increasingly accessible, often on a global scale, and enable the description of topography–soil–vegetation properties and atmospheric variables. Examples include the ECMWF atmospheric reanalysis version 5 (ERA5) and Multi-Source Weighted-Ensemble Precipitation (MSWEP) rainfall product , flow directions IHU from MERIT terrain elevations , the SoilGrids pedology , and daily discharge from Caravan-CAMELS , which are used hereafter. Such data can be directly exploited by grid-based spatially distributed hydrological models, whose development at “hyper-resolution” (1km2 or finer) is recognized as a “grand challenge for hydrology” to address water problems facing society .

Hydrological responses result from combined nonlinear vertical and lateral physical processes occurring at multiple scales in the critical zone, and their limited observability e.g., makes hydrological modeling uncertain and difficult e.g.,). In the absence of directly exploitable first principles in hydrology (e.g., ), as opposed to flow mechanistic equations in continuous media such as river hydraulics, meteorology, or oceanography, and given the high heterogeneities of continental hydrosystem compartments and the lack of “scale-relevant theories” , process-based hydrological models generally include a certain amount of empiricism. This represents an avenue for the fusion of data assimilation (DA) and uncertainty quantification (UQ) with machine learning (ML) and deep learning (DL) techniques to better exploit the informative richness of multi-source data.

The differentiability of the forward numerical model is a key enabler for gradient-based optimization of high-dimensional parameter vectors, for example, in variational data assimilation for 1D or 2D hydraulic models or in spatialized hydrology . While differentiability may appear unnecessary for simple lumped hydrological models with only a few parameters, where sampling-based calibration or gradient-free methods remain efficient, the situation changes drastically for spatially distributed models involving thousands of parameters. In such high-dimensional settings, exhaustive sampling becomes computationally infeasible. Numerical differentiability enables the computation of accurate gradients of the cost function or model outputs with respect to high-dimensional parameters, thereby facilitating the use of efficient gradient-based optimization methods. This is particularly important when coupling physical models with neural networks requiring accurate gradients, as demonstrated in recent work on learnable regionalization and internal flux correction , with large-scale evaluations in . These approaches rely on numerically differentiable solvers and accurate gradients, enabling thousands of parameters to be trained effectively. This perspective aligns with , who emphasize the importance and potential of differentiable modeling in geosciences, highlighting how it can enhance learning, inference, and integration of physical knowledge within hybrid modeling frameworks.

The “resolution–complexity continuum” has been explored over the past 5 decades through various modeling approaches, ranging from point-scale processes numerically integrated at larger scales to spatially lumped representations of system responses . Among the diverse hydrological models and their underlying hypotheses, components generally describe water storage and transfer (e.g., ) through various combinations and parameterizations of vertical and lateral storage-flux operators. Several model comparison experiments have analyzed differences between various modeling approaches, evaluating performance in terms of streamflow modeling and internal states such as soil moisture . concluded that “added complexity does not necessarily lead to improved performance of hydrological models”. Notably, parsimonious conceptual models, whether lumped or semi-lumped, have performed efficiently in large-sample studies (e.g., the Génie Rural (GR) model in , GRSD model in , GR and MORDOR models in , FUSE models in , and references therein). Large-sample studies have also been undertaken with spatially distributed models, including variable infiltration capacity (VIC) with a multiscale parameter regionalization (MPR) or with pixel-wise calibration on global maps of streamflow characteristics , a gridded version of Hydrologiska Byråns Vattenbalansavdelning (HBV) applied with MPR-like descriptor-to-parameter regressions on a global dataset , GloFas , National Hydrologic Model (NHM) , Wflow , and runoff-relevant parameters of Energy Exascale Earth System Model (E3SM) using a surrogate-assisted Bayesian framework . Differentiable numerical hydrological modeling has made significant progress in recent years (spatially distributed variational data assimilation (VDA) in ) for large catchment sample studies with hybrid physics–AI, both with lumped approaches (e.g., ) and with high-resolution spatially distributed frameworks . These large-sample studies enable more general and statistically sound analyses of model performances , addressing large-scale challenges with consistent methodologies across various scales and conditions.

All hydrological models are inherently conceptual, and calibration or learning is generally required due to limitations and uncertainties in their structure, parameter representativity, data availability, and initial and boundary conditions. These models are typically calibrated and validated using discharge time series at the catchment outlet(s) . However, calibrating hydrological model parameters from sparse and integrative discharge data is a challenging inverse problem complicated by equifinality issues , especially for distributed models with a large number of cells and parameters (“curse of dimensionality”). Using spatially uniform parameters may not be the best way to exploit a spatially distributed model (under-parameterization), while fully distributed parameter calibration, which requires a gradient-based approach , faces over-parameterization. Therefore, a parameter regionalization approach using multi-linear descriptor-to-parameter transfer functions has been proposed for distributed models . More recently, this approach has been advanced with regionalization neural networks integrated into the differentiable spatialized smash model , which is the focus of the present article, introducing a new numerical code and conducting original tests on a large sample of catchments with open-source data. This approach also enables learning via cost functions based on hydrological signatures, which are obtained using automatic signal analysis algorithms applicable to large samples with smash .

This article presents the computational framework smash dedicated to Spatially distributed Modeling and ASsimilation for Hydrology. The smash framework combines vertical and lateral flow operators, either process-based conceptual or hybrid with neural networks (which allows learning regionalization relations between descriptors and parameters), and performs high-dimensional optimization from multi-source data. It is based on an efficient and automatically differentiable Fortran solver enabling CPU parallel computing, which is interfaced in Python using f90wrap (https://github.com/jameskermode/f90wrap, last access: 25 July 2025). This open-source smash code, version v1.0 (https://github.com/DassHydro/smash, last access: 25 July 2025), is presented here in terms of mathematical formulation, numerical modeling approach, and functionalities, and full details can be found in our research articles from which this software stems and in the online documentation (https://smash.recover.inrae.fr, last access: 25 July 2025). Note that smash has also been developed for operational applications. It is the core solver of the French flash flood forecasting system . The proposed framework leverages adjoint-based VDA, enabling the simultaneous inference of high-dimensional and spatially distributed parameters (as illustrated) and initial states (implementation available and tested in smash v1.0 but not shown), applicable at both long and short timescales.

This article is organized as follows. Section  describes the smash forward model and the inverse algorithm. In Sect.  we describe the smash build system framework, documentation, and computational performance. Some applications of smash are demonstrated in Sect.  using open-source datasets, focusing on the contiguous US (CONUS) and on a high-resolution flash-flood-prone case study in France. Section  illustrates other aspects of smash not presented in Sect. , followed by conclusions in Sect. .

The smash framework contains various hydrological model structures with varying vertical and lateral flow operators and spatialized routing schemes. It is designed to simulate discharge hydrographs and hydrological states at any spatial location within a structured mesh, and it reproduces the hydrological response of contrasted catchments by taking advantage of spatially distributed meteorological forcings, physiographic data, and hydrometric observations. Cost function gradient maps with respect to tunable parameters are a key feature of smash and can easily be combined to gradients of external operators, such as a regionalization neural network with a chain rule in the context of high-dimensional optimization.

In this section, we focus on code architecture, documentation, and computational performance. smash is based on a computationally efficient Fortran core enabling parallel computations over large domains with OpenMP (https://www.openmp.org, last access: 25 July 2025) and is automatically differentiable with the Tapenade engine to generate the numerical adjoint model. It is interfaced in Python using f90wrap to provide a user-friendly and versatile interface for quick learning and efficient development and to make the wealth of Python modules and libraries (Table ) developed by a large and active community directly accessible (data pre-/post-processing, geographic information system, deep learning, etc.).

In addition to the core differentiable spatialized hydrological solvers and regionalization learning algorithms illustrated above, smash enables performing the following:

automatic hydrograph segmentation and flood detection over large samples ;

The recently released smash framework represents an advancement in modular, regionalizable, and differentiable numerical modeling, as well as in hydrological data assimilation. This conclusion synthesizes the key principles, implementation features, performance indicators, and future prospects of smash, as presented in this article.

smash is built around three foundational principles: a modular operator chaining, enabling flexible representation of vertical and lateral hydrological processes; a regionalization mapping through hybrid approaches, combining conceptual models with descriptor-to-parameter neural networks; and a robust inverse algorithm that supports VDA.

The software leverages automatic differentiation to facilitate gradient-based calibration. Its seamless integration with Python via f90wrap ensures user-friendly access and flexibility, complemented by an automatic build system that simplifies deployment. Furthermore, smash supports parallel computing on CPUs, significantly accelerating computations for large-scale applications.

In terms of hydrological modeling, smash achieves interesting results. Using CAMELS datasets, a median KGE>0.8 is observed in local spatially distributed calibration for daily GR-like and VIC-like model structures at dx=1′30′′ (∼3km). Additionally, regionalization learning across CONUS of conceptual parameters from physical descriptors yields KGE>0.6 in spatiotemporal validation. High-resolution hourly modeling at dx=500m for Mediterranean flash-flood scenarios demonstrates NSE>0.6.

Planned enhancements to smash include the integration of additional differentiable hydrological, hydraulic, and land surface models; the expansion of hybrid physics–AI frameworks; and the refinement of data assimilation techniques. These advancements aim to further improve model accuracy, computational efficiency, and applicability in both research and operational settings.