Given the dominant spatial structures and temporal scales of the processes involved in the terrestrial water cycle, and the interconnected nature of the land system with the atmosphere and the ocean, a modular blueprint featuring three framework components is chosen (see Fig. ): a surface layer component encapsulating the dynamics of moisture and energy exchanges between the atmosphere and the Earth's surface, which are amongst the fastest processes in the terrestrial water cycle and predominantly unidirectional (i.e. vertical); a subsurface component to address the movement of water through the soil down to the bedrock, which in comparison tends to be slower and truly tridirectional (i.e. lateral redistribution according to topographic and hydraulic head gradients, and vertical percolation/capillary rise/vegetation uptake); and an open water component for the movement of free water in contact with the atmosphere which is of intermediate speed and predominantly bidirectional along the surface of the Earth towards the seas and oceans. Despite this modularity, each component must be conservative with respect to the quantities in the continuity equations so that these are also conserved across the entire land system.

For existing modelling components to be coupled, outputs from one need to be mapped onto inputs for another: this requires a common bank of defined variables, i.e. an ontology, to guarantee that the output of one is semantically equivalent to the input of the other. Moreover, to maximise the chances of finding compatible models, this calls for a common interface between components that skilfully yet pragmatically subdivides the terrestrial water cycle continuum. Indeed, a compromise must be found between allowing flexibility in model construction and maximising the potential for existing models to be incorporated in the framework. This is why the degrees of freedom offered to the user are intentionally limited and a standard interface between the components of the framework is formulated. This interface is a set of prescribed transfers of information between each pair of components in the blueprint. For instance, the open water component is receiving (i.e. inward transfers) “direct throughfall flux”, “water evaporation flux from open water”, “surface runoff flux delivered to rivers”, and “net subsurface flux to rivers”, while it is sending (i.e. outward transfers) “open water area fraction” and “open water surface height” (see Fig.  and Table ). These interfaces define the relationship between the framework components. They were designed considering the existing structure of land surface models, namely JULES and ORCHIDEE , and are the fruit of considerable consultation. The information transferred through the interface includes the fluxes necessary to fulfil the continuity equations across the entire land system, as well as the diagnostic quantities characterising the state of components which necessarily condition fluxes in other components.

A first implementation of this blueprint is developed in Python as an integrated coupling framework following an object-oriented approach (see Fig.  for a visual overview of the software architecture using the Unified Modelling Language (UML)). Object-oriented programming is ideally suited to efficiently implement such modular software: the inheritance of the core functionalities of a framework component allows for code reuse in the constitution of the various subdivisions of the water cycle, and ultimately the development of community-based component contributions. In this framework, three Component objects are coupled together by a Model object and executed concurrently, so that the order in which the components are called does not have an impact on the outcome of the simulation. The Model is responsible for the exchange of information between components, including their potential temporal accumulation and aggregation and/or their potential spatial remapping (using an Exchanger object), and is responsible for the time advancement of all components (using a Clock object).

The Component object provides infrastructure to support the science component; e.g. reading input (using DataSet objects), writing output (using Record and RecordStream objects), and state memory allocation (using State objects). The Component class itself is subclassed into the actual framework components represented by the SurfaceLayerComponent, SubSurfaceComponent, and OpenWaterComponent classes, which are used to enforce inward and outward transfers corresponding to the framework interfaces. Each accommodates the description of the physical processes of a given part of the terrestrial water cycle (i.e. the science component) following an initialise-run-finalise (IRF) paradigm. The DataComponent and NullComponent classes are also provided as a convenience to allow any of the three framework components to be either replaced with appropriate data or removed. In both cases, the replacement generates outward data transfers: in the former case, from data, in the latter case, zeros. Attempted inward data transfers are quietly ignored.

The framework modularity makes it possible to resolve the processes in each science component at their own temporal and spatial resolutions. Each Component is discretised individually with its own instances of the TimeDomain and SpaceDomain classes defining their temporal and spatial discretisations, respectively.

In the framework, the TimeDomain class limits instances to temporal discretisations that are regularly spaced. While each component could theoretically run on any temporal resolution independent of the resolution of the other components, it is essential to make sure that restarting times exist across the simulation period in case there are unexpected interruptions of the execution. In order to achieve this, the Clock object makes sure that the temporal resolutions are constrained such that, across the three components, the component temporal resolutions are required to be integer multiples of each other and the component temporal extents to span the same simulation period. These temporal discretisations act as a contract signed between the components and the framework to guarantee that the latter can orchestrate the simulation, but this does not need to preclude components from employing sub-time steps or adaptive time-stepping schemes internally.

In the framework, the SpaceDomain class is subclassed into a Grid, intended to encompass all structured gridded spatial discretisation. The distinction between SpaceDomain and Grid is done in anticipation of additional subclasses to be created in the future (e.g. unstructured grids). The Grid class itself currently features three subclasses corresponding to two discretisations on spherical coordinate systems (latitude–longitude and rotated-pole latitude–longitude) as well as one discretisation on a Cartesian (projected) coordinate system (the British national grid), but additional subclasses can easily be developed. Internal spatial remapping between differing component discretisations relies on the remapping functionality provided by ESMF . If components are to be resolved on different spatial discretisations, not only must the components conserve the quantities in the continuity equations, but the remapping operation must also be conservative. With discontinuities being intrinsic to the land system, e.g. in land cover or soil properties, it appears unrealistic to directly apply traditional interpolation methods for the remapping since they assume continuity, whereas supermeshing techniques , where a supermesh is the union of the components meshes, offer solutions to remain conservative in the remapping without the need for a continuity assumption. Since the current implementation of the framework does not yet feature an explicit supermeshing technique across the three components, the Compass object makes sure that components are discretised using space domains of the same class (i.e. in the same coordinate system), that they span the same region, and that their spatial resolutions are encapsulated in one another, which effectively guarantees that for each pair of coupled components, one is the supermesh for both of them.

Alongside the framework infrastructure itself, an initial library of open source science components complying with the standard framework interface is available. This allows users to explore alternative combinations of components as alternative solutions to simulate the terrestrial water cycle.

Additional components can be exploited by the framework as long as they comply, or can be made to comply, with the framework interface via a particular Python class template (see Listing ).

Land system and hydrological modellers are encouraged to become contributors to the framework by sharing their science components with the rest of the community. These contributions can be implemented purely in Python, but can also rely on Fortran, C, or C++ programs called by interface middleware. Contributors need not handle basic functionalities such as memory allocation nor input/output operations, as these are handled by the framework. Ideally, the use of the framework will simplify model development allowing framework contributors to focus on scientific development (see Sect. ).

The interface specification is effectively a data specification. To guarantee the unambiguous specification of that interface, as well as bringing a full awareness of the physical meaning and spatio-temporal context of input and output data to the framework and to users alike, the NetCDF Climate and Forecast (CF) Metadata Conventions are exploited in the framework. These conventions provide a robust guide for describing, processing, and sharing geophysical data files. They are used in a variety of applications, including for global model intercomparison efforts such as CMIPs e.g.. In particular, the list of CF standard names provides the main ontology followed for the naming of the fields in the framework interfaces, although given that it does not include some concepts relevant specifically for hydrology, some digression from this ontology exists in the framework until these concepts are submitted for inclusion in the list of CF standard names.

The DataSet class responsible for providing each Component with input data relies on reading CF–NetCDF files. This enables the framework to check the compatibility between the data and the configured component, both physically and spatio-temporally. In addition, all record files and dump files are generated as CF–NetCDF files. Such CF–NetCDF files are processed with the package cf-python .

In this subsection, the framework configuration workflow is presented. The user can configure the framework by using either the Application Programming Interface (API) directly or an intermediate YAML (Yet Another Markup Language) configuration file (summarised on the right-hand side and on the left-hand side of Fig. , respectively). These two configuration alternatives are presented in turn below.

A configured Model can then be used to start model spin-up cycle(s) and/or to start a simulation run over the entire simulation period specified in the time domains of the components (Listing ). The spin-up period can either be within or outside of the simulation period, as long as the datasets given to the components contain data for it.

Both spin-up and simulation runs can produce dump files, i.e. files containing intermediate snapshots in the simulation period with all the information required to resume the simulation in case of an unexpected interruption. The user can specify a dumping frequency to choose how often such snapshots should be saved. Once the Model is re-instantiated using its configuration file created through Listing , the simulation can be resumed using any snapshot in these dump files. Moreover, these files can be used to provide initial conditions for the component states in replacement or in addition to the spin-up cycles.

Note that detailed documentation is available online and accessible at https://unifhy-org.github.io/unifhy (last access: 20 December 2022).

A selection of existing models have already been refactored into science components compatible with the framework. These include the Artemis , RFM , and SMART (Soil Moisture Accounting and Routing for Transport) models.

The Artemis model provides a simple runoff production model designed to be comparable with the runoff-production models typically embedded within climate models, which combines Penman–Monteith evaporation with Rutter–Gash canopy interception , TOPMODEL-based runoff production , and a degree-day-based snow accumulation and melting model . The River Flow Model (RFM) is a runoff-routing model based on a discrete approximation of the one-directional kinematic wave with lateral inflow . The SMART model is a bucket-style rainfall–runoff model based on the soil layers concept .

Note that the Artemis and RFM model parameters are not optimised, while the SMART model parameters are optimised for each catchment separately using a standalone version of the model and selecting the best performing parameter set from a Latin Hypercube Sampling of 106 parameter sets, using a subset for the period 1998–2007 of the driving and observational data used by , and the modified Kling–Gupta efficiency as objective function.

The capabilities of the framework are demonstrated through three different configurations summarised in Table .

The first configuration puts the Artemis and RFM models together to form a simple land system model. It demonstrates the flexibility in the temporal and the spatial resolutions of the various components. Indeed, the surface layer and the subsurface components are taken from the Artemis model and configured to run at an hourly time step on a 0.5∘ resolution latitude–longitude grid, while the open water component from RFM is used and configured to run at 15 min intervals on a 0.5/60 (∼0.008)∘ resolution on a latitude–longitude grid.

The second configuration demonstrates the possibility to replace science components with datasets. To do so, the surface and subsurface runoff outputs from the JULES model available in the CHESS-land dataset are put together as a DataComponent and used in place of the subsurface component, which is then coupled with the open water component of the RFM model, both on a 1 km resolution on the British National grid. The surface layer component is removed by setting it as a NullComponent.

The third and last configuration puts together the Artemis and SMART models. It demonstrates the possibility to substitute parts of an existing model (i.e. SMART) with parts from another model (i.e. Artemis) and explore the impacts on the model performance. The SMART model is a rainfall–runoff model for application to hydrologically meaningful spatial elements (e.g. catchments, subbasins), for which the existing gridded space domains are irrelevant. However, the model can be run on a single spatial element assumed to represent the whole catchment until more complex geometries are supported in the framework.

Note that the details of the three configurations are available as YAML configuration files in the Supplement.

The three configurations are applied to three British catchments, selected to explore the capabilities of the framework: the upper Severn catchment predominantly located in Wales, the Ouse catchment located in north-east England, and the Tay catchment located in the east of Scotland (see Fig. ). These three catchments cover a range of climatological, topographical, and geological settings. Their baseflow indices (BFIs) are 0.53, 0.39, and 0.64, respectively . The three configurations applied to these three study catchments form nine case studies. The simulation period considered is 2008–2017.

Figure  showcases the river discharge simulated with the three framework configurations described above, focussing on the river discharge at the catchment outlet in the line plots (a, c, e), and the spatial distribution of river discharge at the end of the simulation in the gridded plots (b, d). For reasons of brevity, only the Tay catchment is shown in the main text, figures for the other two study catchments are available in Appendix . These figures qualitatively confirm the plausibility of the framework simulations. Indeed, the overlaid hydrographs suggest that the overall observed discharge pattern is captured by the simulations, while the spatial distributions of river discharge sketch a realistic picture of the catchment river network.

In addition, a quantitative evaluation of the performance of the framework simulations is done with respect to the river discharge at the catchment outlet where observed and simulated time series are compared using the non-parametric Kling–Gupta efficiency (RNP). This is a composite metric made of three equally weighted components, rS, αNP, and β, assessing the agreement in the dynamics (i.e. correlation), the variability, and the volume (i.e. bias) of the discharge time series, respectively . Table  features these metric components computed for the three configurations and the three study catchments using the Python package hydroeval .

The comparative performance of the three configurations for each catchment in turn informs the most suitable combination of components for a given temporal and geographical context. For instance, the third configuration appears to be the most suitable in the Tay catchment, if one is solely interested in simulating the river discharge accurately (RNP of 0.766), while the second configuration would be preferred for the Ouse and Severn catchments (RNP of 0.674 and 0.706, respectively). However, these conclusions are metric-dependent and the analysis of the components of the composite metric can reveal the strengths and weaknesses of a given configuration, e.g. while the third configuration performs highest on the composite metric in the Tay catchment, its ranking on capturing the flow variability is the lowest of the three configurations (αNP of 0.940).

Some caveats in this comparison are that the third configuration used a calibrated model unlike the first and second configurations, and the second configuration used data from a model constrained to conserve mass and energy, unlike the other configurations that only conserve mass. This likely skews the comparison.

This brief analysis of the results is used to demonstrate the potential of the framework to compare alternative combinations of components to simulate the hydrological behaviour for a given region and a given objective; it is not to draw definitive conclusions as to which combinations should be used for the catchments selected here, and more components than those presented in this paper can be developed and used in the framework. Moreover, this analysis focuses on one hydrological variable, the river discharge, but other hydrological variables such as e.g. soil moisture or evaporation could also be considered.