Figure 1 shows the architecture of the EVB framework. In brief, it is built on the following premises: (a) the tools subpackage, which provides foundational functions to support the core operations of other modules; (b) the workflow for VIC model deployment, along with the associated seven modules; and (c) the Evb_dir class for managing the directory structure of the generated files. Through this architecture, the EVB framework enables users to deploy the VIC model with flexibility across diverse configurations.

Here, we highlight the advantages of this architectural design, specifically its object-oriented programming and loosely coupled structure. This is achieved by decomposing various functionalities into separate classes, functions, modules, and subpackages, allowing the users to modify and extend the framework as needed at any time. For example, the addition of a new forcing data source can be accommodated by overriding the relevant methods of the data processing class, without modifying other components. These design choices are consistent with the principles of reproducibility, grouping, isolation, and sharing highlighted by Hamman et al. (2018) and Knoben et al. (2022). Below, we introduce several classes that constitute the core of the EVB architecture, along with the underlying concepts.

The EVB framework is fully developed in Python and entails certain basic environmental requirements. All the required environments are open-source and easily accessible. To assist users in configuration, we grouped the required environments into three categories based on their functionality: (a) basic computation and visualization, (b) geospatial data processing, and (c) optimization. Table 1 lists the names and sources of these Python packages. We also provide a pyproject.toml file in the source code, aligned with the latest Python standards, to simplify the environment setup.

The Multiscale Parameter Regionalization (MPR) technique was pioneered by Samaniego et al. (2010), with the aim of proposing a method for the parameter estimation of distributed hydrological models at multiple scales. A distinctive feature of MPR is the combination of the transfer function and scaling operator. Following the information level division approach described earlier, at level-0, basin characteristics such as soil properties are transferred into effective parameters via the transfer function, after which the scaling operator is applied to scale these parameters to level-1. During this process, a set of spatially invariant, quasi-scale independent, scalar global parameters is used (hereafter referred to as g-parameters), making calibration possible and enhancing its applicability.

Notably, the feasible ranges of the g-parameters are constrained based on previous transfer-function studies, ensuring physically meaningful parameter bounds rather than arbitrary assignments. For example, according to the work of Cosby et al. (1984), the relationship between saturated hydraulic conductivity (KS) and soil texture can be expressed as follows: 1log⁡Ks=0.0126fsand-0.0064fclay-0.6, where fsand denotes the sand content fraction and fclay denotes the clay content fraction. Using this empirical relationship as prior knowledge, a transfer function incorporating the g-parameters can be established, allowing KS to be inferred from soil texture: 2Ks=10g1+g2fsand+g3fclay, where g represents the g-parameters, and their feasible ranges (Table A1) can be obtained by proportionally scaling the coefficients from the original equation. Here, g1, g2, and g3 correspond to g6, g7, and g8 in Table A1, respectively.

Additionally, we extended the transfer functions to include parameters of the routing-module. Specifically, the flow velocity and diffusion coefficient were regionalized based on grid-level river network information using mapping relationships reported in previous studies (Chen et al., 2019; Yang et al., 2016), resulting in spatially distributed parameter fields as formulated below: 3v=g1accg2Sg3,4D=g4dv, where acc is the accumulated upstream area, and S denotes the mean slope angle, d is the flow distance within each grid.

The MPR technique has been successfully applied to parameter estimation in various distribution hydrological models, including but not limited to the VIC and mHM models (Rakovec et al., 2016; Zink et al., 2017). All these studies have consistently demonstrated that the parameters estimated by MPR exhibit a certain degree of transferability. A recent study by Mizukami et al. (2017) is an important starting point for this study. They implemented the MPR technique for the VIC model using Fortran and generated parameter estimates for a large sample of basins across the CONUS. The EVB framework proposed here partially builds upon the transfer functions they used, with one improvement being its implementation in Python and in a modular, object-oriented manner rather than the original Fortran functional programming approach. The transfer functions used for the VIC model-specific parameterization in this study are detailed in Table A2 in the Appendix.

Within the EVB framework, the MPR method serves as a core module for VIC parameter estimation during the model deployment process. It offers the following advantages: (1) a user-friendly parameter estimation approach, with all parameter-related knowledge aggregated within the transfer function; (2) some extent of parameter transferability across scales and regions; and (3) the consideration of the influence of basin characteristics on parameters, making them more physically meaningful.

The Unit Hydrograph (UH) concept is a classical concept in hydrology, first introduced by Sherman (1932). Fundamentally, the rainfall–streamflow transformation is represented using a convolution-based transfer function model (TFM). Owing to its simple structure and computational efficiency, it can serve as an effective black-box routing approach. The RVIC routing model integrated within the VIC source code is a variant of the UH (Lohmann et al., 1996), which requires a grid UH for its parameter derivation.

Over the past decades, various forms of UH have been developed, such as the Nash UH based on a two-parameter Gamma distribution and the Soil Conservation Service (SCS) dimensionless UH. Among these forms, a General UH (GUH) introduced by Guo (2022) has a particular appeal as it has explicit analytical expressions: 5u(t)=dgdt=μtpx(1+mx)-(1+1/m),6g(t)=1-(1+mx)-1/m,7x(t)=exp⁡μttp-1, where tp is the peak flow time; m is a dimensionless recessing coefficient determined by downstream water surface conditions; and μ is the rising coefficient related to the basin characteristics. This analytical expression provides high flexibility to the GUH and has been demonstrated to exhibit high consistency with traditional methods (Guo, 2022). In this study, the GUH is employed as the default grid UH to derive the RVIC parameters. Its shape is controlled by the above three parameters, which are treated as free parameters to be calibrated. To enhance flexibility and user configurability, the Nash UH is also implemented as an optional alternative.

Figure 1b presents the VIC model deployment workflow within the EVB framework, which consist of seven sequential steps. This deployment process follows the guidelines outlined in the official VIC documentation (https://vic.readthedocs.io/, last access: 2 November 2026) and focuses on the image driver version of VIC-5. The workflow is described in detail below, with all files involved in the deployment process managed through EVB's built-in Evb_dir class. This class provides unified path management for the definition, modification, and transfer of file and directory paths, thereby ensuring consistent and efficient file handling throughout the deployment.

The workflow first processes the required spatial and attribute data according to the selected modelling domain and spatial discretization. Users construct Grids and Basins instances and provide them to the corresponding dpc instances, where data source-specific extraction and processing are performed. The resulting basin- and grid-level information is stored as instance attributes for subsequent deployment steps. Based on the processed level-1 data, the build_Domain utility then generates the VIC domain file in NetCDF format, including grid area, basin fraction, and grid-edge information.

VIC parameter files are subsequently generated using the MPR-based parameterization scheme embedded in EVB. The scheme maps level-0 basin characteristics to spatially distributed parameters at the selected modelling scale, while the g-parameters can be calibrated to account for basin-specific conditions. Meteorological forcing is generated from the processed dpc instances using the buildMeteForcing function. The required VIC forcing variables are prepared and converted when necessary, for example, deriving vapor pressure from specific humidity and wind speed from its zonal and meridional components. The resulting forcing files are stored in NetCDF format and can be directly used by VIC.

For runoff routing, EVB uses the Python implementation of RVIC to generate routing parameter files. This procedure first derives the hydrological topology from the level-1 DEM and then generates the required routing inputs, including the pour point and unit hydrograph. Users can select either the Nash or GUH unit hydrograph, while flow velocity and diffusion parameters can be regionalized using the MPR scheme and calibrated when required. A global parameter file is finally generated and managed through the GlobalParamParser, which facilitates the specification and modification of model input/output paths and runtime options.

The final step is VIC model calibration. Although MPR provides spatially distributed parameter estimates, calibration remains necessary to account for uncertainties in regionalized parameters and their scaling across spatial resolutions. EVB provides both the Covariance Matrix Adaptation Evolution Strategy (CMA-ES; Hansen and Ostermeier, 2001) and the Non-dominated Sorting Genetic Algorithm II (NSGA-II; Deb et al., 2002) through the DEAP library for single- and multi-objective calibration, respectively, allowing users to calibrate selected model parameters against streamflow and, where available, additional hydrological observations.

In response to the call for large-sample hydrological research highlighted by Gupta et al. (2014), we assess whether the EVB framework can contribute to this research direction. To this end, we selected a case basin from the widely used Catchment Attributes and Meteorology for Large-sample Studies (CAMELS) dataset (Newman et al., 2015; Addor et al., 2017) to demonstrate the implementation of VIC modelling within the EVB framework. Employing a simple model setup with streamflow-only calibration, we investigated the parameter transferability to evaluate the efficiency of applying EVB in large-sample basin contexts. The case basin is located within Missouri, USA, and is known as the Gasconade River Basin (GRB; USGS gauge ID: 06934000), with a total drainage area of approximately 8268 km2. Figure 2 provides an illustrative map of the basin, showcasing the topography, outlet, and land surface properties in the area. The local temperate continental climate is typical and characterized by distinct seasonal variations. Under the combined effects of climate, topography, and vegetation, streamflow in this area exhibits pronounced seasonal variability, with the peak flow occurring in the spring and a low flow observed in the late summer and autumn. Notably, the current EVB implementation, once demonstrated in this case basin, can be seamlessly extended to the entire CAMELS basin collection.

Beyond large-sample applications, we further assess the adaptability of the EVB to the single site-specific basin setup, a typical case in which researchers define or customize their own study domain. Within this setup, a more complex multi-objective calibration was employed, alongside an in-depth examination of the physical plausibility of the spatial parameter distributions. Here, we selected the Jing River Basin (hereafter referred to as JRB), with a drainage area of approximately 45 400 km2, as the case basin. It represents a markedly different hydroclimatic setting compared to GRB, characterized by a typical arid to semi-arid climate and land use condition representative of northern China (Fig. 3).

The VIC model instances were deployed via the EVB framework at multiple spatial resolutions (i.e., 6, 8, and 12 km) in basin setup A, and at a fixed resolution (i.e., 13.8 km) in basin setup B. The spatial resolutions of level-0 and level-2 are determined based on the data availability and are set to 1 km and 0.125°, respectively. The data listed in Table 2 were resampled to the corresponding spatial resolutions, and the input files required for running VIC were generated following the deployment workflow described above.

To provide a full narrative of the VIC deployment, there are two configurations that need to be clarified – data partitioning and parameter calibration. For basin setup A, the period from 1998 to 1999 served as a warm-up period to ensure stable initial conditions. The model was then calibrated using daily streamflow records from 2000 to 2007 to derive the optimal parameter set, with the remaining 3 years reserved for validation. For the objective function, we use the KGE metric on streamflow, which is a widely recognized measure of model performance that integrates bias, variance, and correlation (Gupta et al., 2009). Further evaluation metrics, including NSE and PBIAS, are employed to comprehensively evaluate model performance during the validation period (Mizukami et al., 2019). Formally, these metrics can be calculated using the following formulas: 9KGE=1-(r-1)2+σsimσobs-12+μsimμobs-12,10NSE=1-∑i=1n(Vobsi-Vsimi)2∑i=1n(Vobsi-Vobs‾)2,11PBIAS=∑i=1n(Vobsi-Vsimi)∑i=1nVobsi×100%, where σ is the standard deviation; and μ is the mean; Vi is the target variable (i.e., streamflow) at time step i; and n is the length of the sequence. The subscripts sim and obs denote the simulated and observed values. Both KGE and NSE are formulated such that higher values indicate better model performance, with a value of 1 representing the optimal simulation for each metric. The final metric, PBIAS, is used to evaluate whether the model overestimates (PBIAS<0) or underestimates (PBIAS>0) the observed values.

In the case of basin setup B, the years 2008–2009 were allocated for model warm-up, 2010–2015 for calibration, and 2016–2018 for validation. A special setting in this setup is that multiple objective functions were formulated to improve the simulation performance with respect to various aspects of the VIC model during the calibration process. Besides using KGE to evaluate streamflow and actual evaporation simulation, the model capability to reproduce the patterns of soil moisture was assessed via the Pearson correlation coefficient (R), which is formulated as follows (Wambura et al., 2018): 12R=∑i=1n(Vobsi-Vobs‾)(Vsimi-Vsim‾)∑i=1n(Vobsi-Vobs‾)2∑i=1n(Vsimi-Vsim‾)2, where Vi is the target variable at time step i and the overbar indicates the average.

Both basin setups used a two-year warm-up period to allow the model states, particularly soil moisture, to reach stable initial conditions. This period length was guided by previous studies and established modelling practice. For example, Miao and Wang (2020) found that soil moisture at nine representative grid cells had largely reached equilibrium after two years when developing a VIC based land surface hydrological dataset for China. Several other studies have likewise used warm-up periods of one to three years (Nicolle et al., 2014; Qiu et al., 2017; Mei et al., 2023). Drawing on this evidence and considering data availability, we selected a two-year warm-up period to maintain a practical balance among the warm-up, calibration, and validation periods. Simulated runoff remained relatively stable during the early part of the subsequent simulation period, with no pronounced extreme values, further supporting this choice.

In this study, parameter calibration was performed using the CMA-ES and NSGA-II algorithm implemented in the EVB, as described in Sect. 3.3. The CMA-ES algorithm is configured with a population size of 40, and the initial global step size (σ) is set to 0.4. The NSGA-II algorithm is configured with a population size of 20, a crossover probability of 0.7, and a mutation probability of 0.2. Polynomial mutation and simulated crossover are employed. To mitigate potential identifiability issues arising from a large number of free parameters, we fixed some of the physical parameters and introduced a simplified calibration set, reducing the free parameters from 44 to 15. A substantial body of research (Liang et al., 1994; Gou et al., 2020; Gu et al., 2021; Cortés-Salazar et al., 2023; Yeste et al., 2024), together with widespread VIC modelling practice, supports the selection of this reduced parameter set as comprising parameters commonly identified as sensitive. All 15 free parameters (Table A3) are treated equivalently within a parameter pool and sampled by Latin hypercube sampling (LHS) to partition the parameter space into equiprobable regions with representative samples, thereby ensuring efficient coverage of entire parameter range (McKay et al., 1979).

The optimization was performed for a maximum of 200 generations and stopped upon convergence, with the optimal parameters selected according to the maximum KGE in basin setup A. For the multi-objective calibration in basin setup B, a best Pareto front comprising multiple non-dominated optimal solutions was generated, from which a solution exhibiting a relatively balanced trade-off among objectives was manually selected as the final parameter set. The convergence process of the single-objective calibration and the Pareto front curves from the multi-objective calibration are provided in Figs. B1 and B2, respectively.

Noteworthily, all experiments in this study were performed on a laptop with 32.0 GB of RAM, with an AMD Ryzen 7 8845H 3.80 GHz processor, and running Ubuntu 20.04.1 LTS (virtual machine). To illustrate the computational efficiency of EVB, we used the built-in Logger class to record the average time required for each deployment step across the three spatial resolutions considered in the first case application (i.e., GRB), as described later; the results are reported in Table 3. The Logger class automatically records the execution time of each step and generates messages at predefined logging levels, providing traceability throughout the model deployment process. Building dpc instances (57 % of the total runtime) and processing meteorological forcing data (41 %) are the primary time-consuming steps, but both need to be executed only once for each modelling application and can thereafter be saved to persistent storage for convenient reuse. Because these operations are performed on a grid-cell basis, their computational costs increase approximately linearly with the number of grid cells as the spatial resolution becomes finer.

The rapid growth of hydrological big data has enabled substantial advances in hydrological modelling, particularly in the development of increasingly sophisticated distributed models (Argentin et al., 2025). By explicitly representing the spatial variability of hydrological processes, distributed models can resolve the spatial patterns of hydrological states and fluxes that are unavailable from their lumped counterparts, offering valuable insights for water resources management and flood and drought risk assessment. For example, in this study we found that baseflow was generally more abundant in the southern part of the JRB, indicating potentially greater hydrological capacity to support afforestation in these areas (Fig. 9c). In contrast, the relatively lower baseflow in the northern part suggests that afforestation need to be implemented more cautiously to avoid increasing pressure on local water availability. In this context, integrating the increasingly available data sources for spatial parameter estimation presents new opportunities for fully realizing the potential of distributed hydrological modelling.

Several fundamental challenges hinder the effective estimation of spatially distributed parameters. First, the historical reliance on the concept of “effective parameters” in hydrological modelling has resulted in many models retaining a large number of free parameters that require calibration and are implicitly assumed to be spatially homogeneous, limiting their ability to explicitly represent spatial heterogeneity. Second, introducing spatially varying parameters into traditional calibration frameworks substantially increases the dimensionality of the optimization problem, while the available observations are often insufficient to constrain such high-dimensional parameter spaces, leading to equifinality and ill-posedness. Finally, direct parameter estimation approaches generally require extensive prior information describing the relationships between parameters and environmental characteristics, while establishing such relationships requires extensive experimental investigations and coordinated efforts across multiple disciplines. Against this background, many distributed hydrological models still use spatially uniform parameters to maintain the number of free parameters at a level that can be reliably constrained through calibration, imposing substantial limitations on their capability to represent spatial heterogeneity. Our previous studies have shown that such simplifications create spatial trade-offs that undermine the physical realism of simulations and limit predictive performance (Zheng et al., 2026).

To address these challenges, several strategies have been proposed for estimating spatially distributed parameters. A straightforward approach is to aggregate the modelling domain into spatial units, such as sub-basins, and independently calibrate parameters for each unit while assuming spatial homogeneity within it. This provides an intermediate representation between fully lumped and grid-based parameterizations, with implementations including spatial clustering (Huynh et al., 2024), representative grid sampling (Sun et al., 2021), and hydrological response units (HRUs). Nevertheless, the number of calibration parameters still increases with the number of spatial units, leaving the parameter-dimensionality problem largely unresolved. Another class of approaches can be broadly termed scaling methods, which infer parameter values at one spatial scale and relate them to hydrological processes or parameters at another through scale-invariant or explicitly scale-dependent relationships (Viney and Sivapalan, 2004). For example, Barrios and Frances (2012) demonstrated the feasibility of estimating mesoscale effective parameters by aggregating microscale simulation outputs and solving the inverse problem. Regionalization approaches further extend this concept and exploit similarity principles (Bao et al., 2012), establishing relationships between catchment characteristics and parameters in data-rich regions (donors) and transferring them to data-scarce or ungauged regions (receptors). More importantly, if such relationships are applied consistently across all modelling grids, they can provide an effective pathway for spatial parameter estimation.

Within the regionalization framework, MPR offers several advantages over conventional approaches. As mentioned in Sect. 3.1, MPR establishes environment–parameter relationships using transfer functions informed by existing literature. Compared with standard regionalization (SR) methods based on empirical regression or similarity measures derived from spatial distance or physical attributes, this approach allows prior knowledge from multiple disciplines to be explicitly incorporated into parameter estimation, thereby improving the plausibility and reliability of spatial parameter estimates (Mizukami et al., 2017). Meanwhile, the limited number of adjustable parameters in transfer functions maintains the parameter dimensionality within a practically calibratable range. In terms of cross-scale issues, MPR first derives high-resolution parameter fields and then aggregates them to the target modelling scale, shifting the scale transformation from environmental inputs to parameters across different resolutions. This provides the benefit of minimizing uncertainties associated with environmental data aggregation and improving the representation of subgrid parameter heterogeneity. As evidenced by Samaniego et al. (2010), MPR exhibited superior performance to SR in maintaining water balance and preserving the spatial patterns of simulated variables, whereas the latter introduced larger deviations during the upscaling process. Given these advantages, MPR was selected as the default spatial parameter estimation approach in EVB. Beyond this implementation, we envision that future developments of EVB should further investigate scale-aware parameterization by incorporating scaling factor into transfer functions, allowing nonlinear upscaling relationships to be integrated into the spatial parameter estimation procedure. In our view, advancing spatial parameter estimation approaches in this direction represents one of the key priorities for hydrological model development over the coming decade.

Positioning EVB within the existing VIC deployment ecosystem helps clarify its role and scope. Given the limited number of deployment tools available for VIC, we selected three representative examples, VIC-ASSIST, TONIC, and CyberWater, each briefly introduced in the Introduction, for comparison with EVB. We compiled a feature matrix covering supported VIC versions, implementation languages and distribution forms, approaches to parameter specification and regionalization, workflow reproducibility, and extensibility (Table 5). All three tools in the comparison are freely available, and several are distributed under open-source licenses (e.g. MIT license). This accessibility is consistent with the recommendation of Knoben et al. (2022) to use permissively licensed workflow components that support reuse and extension. However, free access to a deployment tool does not eliminate software dependencies. As noted earlier, VIC-ASSIST depends on MATLAB and ArcGIS, whose commercial licensing requirements may limit its use where these software packages are unavailable.

Functionally, TONIC has the narrowest scope among the four tools. It provides a small set of utility scripts, mainly for NetCDF and ASCII conversion and data visualization. It therefore does not constitute an integrated deployment workflow. VIC-ASSIST focuses on the rapid deployment of VIC 4 and simplifies operation by fixing several model choices, such as data sources and parameter calibration settings. This design is more suitable for new users and educational applications (Wi et al., 2017). By comparison, CyberWater combines a graphical interface with data and model agents, offering a practical balance between ease of use and functional breadth. It is accessible to users with limited programming experience and provides more configuration options than VIC-ASSIST. However, its encapsulated software architecture makes the workflow less straightforward to extend. For example, incorporating a new optimization algorithm may leave users or developers to adapt or reimplement the algorithm in the format expected by the workflow, rather than directly reusing an existing implementation from the broader Python ecosystem. EVB places greater demands on users' Python programming experience. In return, it provides direct control over every stage of the deployment workflow, from data preparation and parameter specification to calibration and parallel execution, supporting a broader range of advanced modelling applications (Table 5). Given the rapid development of large language model based programming tools, such as Codex, we believe that this programming requirement is unlikely to constitute a major barrier to the use of EVB.

Knoben et al. (2022) developed a workflow blueprint for the coupled SUMMA and mizuRoute modelling system as part of the CWARHM initiative. The blueprint has provided a reference for workflow based modelling in the Earth system science community by setting out guidelines for improving reproducibility through four key properties: separability, clarity, modularity, and traceability. Within this broader context, several aspects of the EVB design are consistent with the guidelines. First, EVB follows the separation of concerns (SoC) principle through a modular, loosely coupled, object-oriented design, allowing individual components to be modified or replaced independently. For example, the two basin setups examined here use CONUS SOIL and SoilGrids1km, respectively. The two datasets represent soil profiles using 11 layers spanning 0–250 cm and 6 layers spanning 0–200 cm. During parameter generation, EVB calls the same buildParameter function with two subclasses of SoilLayerResampler, one for each dataset. Each subclass requires only minimal overrides of selected methods, allowing the same function to accommodate both layer schemes without separate construction functions. This degree of component flexibility is not readily available in the other three tools. Consistent module interfaces also support workflow reproducibility. When Model A and Model B use the same data source, the dpc class can reuse the relevant modules within extractData_func without creating conflicts with other methods. Second, a structured directory design facilitates the exchange of workflows within the modelling community. Applications deployed with EVB follow a common directory structure managed by the Evb_dir class (Fig. 1c), allowing users to inspect and rapidly reuse existing studies. This design provides transparency while retaining flexibility for user defined extensions, a combination that is often difficult to achieve in graphical workflow systems. Third, EVB provides flexibility at two levels: runtime configuration of model options and extension beyond the original application scope. Its ability to combine alternative modelling decisions was demonstrated in our previous study (Zheng et al., 2026), in which flexible deployment enabled eight cases with different combinations of spatial discretization and calibration configuration. By contrast, deployment frameworks that do not expose their underlying code may offer only limited scope for extension, with further development often depending primarily on the original developers. Taken together, these features position EVB to improve transparency within the VIC modelling community, facilitate the exchange of computational practices, and reduce duplicated effort across the broader scientific community. By making deployment procedures easier to inspect, reproduce, and extend, EVB may also accelerate the iterative development and refinement of VIC.

Last but not least, the current scope of EVB warrants further consideration. Its reliance on GeoDataFrame structures may become inefficient for very large domains at continental or global scales, where chunked and parallel processing with Dask (https://docs.dask.org, last access: 2 November 2026) or comparable tools may be needed. In addition, the transferability of MPR derived parameter estimates has so far been evaluated over a limited range of spatial scales, and broader testing is therefore needed. Future development will focus on four directions: (1) introducing a standardized data layer between preprocessing stages, thereby allowing framework specific intermediate files to be replaced with interoperable formats, notably GeoTIFF and NetCDF; (2) developing interfaces for conversion between VIC versions to improve backward compatibility; (3) implementing vector-based modelling units to provide more flexible spatial representations; and (4) maintaining consistency with ongoing VIC development, particularly its Python driver, which is currently experimental and remains under development. Future integration with this driver could broaden the scope of EVB, improve compatibility with VIC, and contribute to the continued development of the VIC modelling ecosystem.