This paper presents WHETGEO and its 1D deployment: a new physically based
model simulating the water and energy budgets in a soil column. The purpose of
this contribution is twofold. First, we discuss the mathematical and numerical
issues involved in solving the Richardson–Richards equation, conventionally
known as the Richards equation, and the heat equation in heterogeneous soils. In
particular, for the Richardson–Richards equation (

The Earth's critical zone (CZ) is defined as the heterogeneous near-surface
environment in which complex interactions involving rock, soil, water, air,
and living organisms regulate the natural habitat and determine the
availability of life-sustaining resources

It is generally accepted in the field that the motion of water in soil is
regulated by a Darcian–Stokesian flow, meaning that any force is immediately
dissipated and water under a gradient of generalized forces acquires a
velocity (the Darcy velocity) which is linearly proportional to the gradient
of the generalized force. This law is known as the Darcy–Buckingham law and
reads

Firstly, pores in soils are not bundles of well-defined capillaries of a single diameter; in fact, they can have quite random structures, as revealed, for instance, by tomography

Secondly, logic and pore scale simulations, as in

A set of relatively large pores can, in certain conditions, preferentially drive the flow of water in a short timescale according to laminar viscous flow driven by gravity before any redistribution happens

The role of living matter, such as bacteria, animals, fungi, vegetation, and roots, is usually eliminated from the hydrological picture, but it should have a relevant place

Capillary forces are not the only ones acting at the microscale

Temperature affects water viscosity; infiltration is faster at warm temperatures and slower at cold ones

In high-latitude and high-elevation environments, soils may be subject to freezing and thawing processes which affect pore volume and water dynamics

Requirement I – without entering into further details, we can observe that the aforementioned issues have consequences that would require new software to include the possibility of adopting new parameterizations of SWRCs and hydraulic conductivity quickly, easily, and neatly.

The flow of water obeys the general laws of physics for conservation of mass
and momentum, but, since the seminal works of

Requirement II – the boundary conditions hard-wired into algorithm implementation should be removed in favour of a simultaneous treatment of the three compartments (surface waters, vadose zone, and groundwater).

Fortunately,

Furthermore, switching from Richards to shallow water was made possible in the equation writing thanks to, for example,

As remarked in point 6 above, temperature affects water viscosity, which
effectively doubles in passing from 5 to 20

Requirement III – to account for thermodynamic effects, temperature should at least be present in the

Finally, there is a great urge to model solute transport according to the
water movements. The range of applications for solute, tracers, and pollutants spans
from agriculture to industry to research itself. In fact, in recent years
there has been a tumultuous increase in the number of studies using tracers to assess the
various pathways of water

Under the conditions defined above, the governing equation for the transport
of energy in variably saturated porous media is given by the following energy
conservation equation:

Amateurism in software (model) building may be reflected in an incorrect analysis
of the hydrological processes, threatening the development of science from the
offset. Also, in recent years a new paradigm in evaluating scientific
productivity, and therefore software productivity, has gained importance
(see e.g. project

As discussed in

Moreover, WHETGEO-1D has been integrated into the Object Modelling System v3
(OMS3) framework

WHETGEO is also part of GEOframe

This paper describes the implementation and content of the WHETGEO-1D (Water,
HEat and Transport in GEOframe) software, in observance of Requirements I to
III and aware of the hydrologic facts described in points 1 to 7 of
Sect.

Further requirements derive from numerics and mathematics. In fact,
translating the

Moreover, WHETGEO-1D represents the first brick of a new expandable land-surface model

In the following section we discuss the mathematical issues and the numerics of our implementation. In the subsequent one, we describe the informatics and software engineering issues, as well as how we solved them. Finally, we discuss WHETGEO-1D implementation by testing it against some analytical solutions available for simplified parameterizations and boundary conditions; for details of these see Appendix C.

Translating these equations into numerical discretized codes implies overcoming some challenges, as we illustrate in the next sections by exploring, at first, the issues posed by each of the equations.

Equation (

The “

There is a third form of Eq. (

In WHETGEO, we directly use the conservative form of the

The implicit finite-volume discretization of Eq. (

The definition of the type of surface boundary condition (Neumann
vs. Dirichlet) for the

Scheme of the computational domain to solve the

To overcome this problem we have included an additional computational node at
the soil surface. As will be made clear in the following, for it we prescribe
an “equation state” like that presented in

Equation (

Equation (

Although Eqs. (

As in the case of the water flow, thermal budget issues can be subdivided into three aspects: the discretization of the equation, the inclusion of the appropriate boundary conditions, and the implementation of some closure equation for the thermal capacity and conductivity.

The key feature

At the soil surface the heat equation is driven by the surface energy
balance. The heat flux exchanged between the soil and the atmosphere, the
surface heat flux,

Similarly to the definition of the surface boundary condition for the water
flow, the surface boundary condition for the energy equation is also system-dependent. In fact, in Eq. (

The latent heat flux is taken here as given by a formula of the type

Including the surface energy budget boundary condition requires the
computation of additional quantities such as the incoming radiation fluxes,
the shortwave radiation and the longwave radiation, and the potential
evapotranspiration flux. These quantities can be easily computed within the
GEOframe system in which WHETGEO-1D is embedded. The proper estimation of the
incoming radiation fluxes is far from being a simple task, and it is often
oversimplified in hydrological problems. Our approach is to use the tools
already developed inside the system GEOframe, which were tested independently
and accurately

By using a numerical method, here the finite-volume method, a partial
differential equation is transformed into a system of nonlinear algebraic
equations, as has already been shown. The system has to be solved with
iterative methods, and, at their core, these reduce the problem to using a
linear system solver. The solver can be of various types, according to the
dimension of the problem. For instance, in 1D, the final system of finite-volume problems we present is tridiagonal and can be conveniently solved with
the Thomas algorithm

However, the reduction of a nonlinear system to a linear one is not
trivial. We illustrate the issues by taking the

As clearly pointed out by

Let us start again from the nonlinear system

Having assumed that the

By making use of Eq. (

It is necessary here to point out exactly how the nonlinear system in
Eq. (

Graphical representation of the Jordan decomposition for soil water content using the SWRC model by

Instead, when we consider the water depth function to describe the
computational node at the soil surface, the vectorial function is defined as

This aspect, the use of two different equation states, and the fact that the
NCZ algorithm can be successfully re-used to solve other problems

The concepts and requirements previously illustrated must be cast into software whose usability, expandability, and inspectability are demanded by good software design, which adds further requirements. The software design requirements and the software deployment are explained below.

One of the major difficulties encountered by a research group concerns the
development and re-use of scientific software

An object-oriented programming approach, with the adoption of standard design
patterns (DPs)

The design principles followed by the WHETGEO-1D software can be summarized as follows.

The software should be open-source to allow inspection and improvements by third parties.

For the same reason it should be organized into parts, each with a clear functional meaning and possibly a single responsibility.

The software can be extended with minimal effort and without modifications (according to the “open to extensions, closed to modifications” principle;

The largest set of boundary conditions should be smoothly manageable.

The implementation of equations should be abstract, according to the principle of “programming to interfaces and not to concrete classes”, which is the core of contemporary OOP

The implementation of algorithms should not depend on the data formats of inputs and outputs.

Another requirement has to do with the user experience. In fact, solvers of
partial differential equations (PDEs)

To simplify this situation, WHETGEO-1D has to be implemented is such a way that any of the alternative implementations must come only with their own parameters and variables, as well as appear to the user to be as simple as possible, though not too simple.

There is finally a last requirement to consider.

For computational and research purposes, there will be one-, two-, and three-dimensional (1D, 2D, 3D) implementations of the aforementioned equations. Therefore, as much of the code as possible should be shared across these. In particular, the NCZ and Newton algorithms should be shareable across the various applications.

This requirement implies that the geometry of the domain, as well as the topology, should be specified in an abstract manner to cope with the specifics of each dimensionality.The rest of this section is organized to respond to points (a) to (h). Point (a) is actually responded to in the next section describing where the software can be downloaded and with which open license. Points (b) and (c) are accomplished by studying an appropriate design of classes and the use of design patterns

To respond to the issues raised in (f) and (g), WHETGEO-1D is implemented as
various components of OMS3, as shown below, each one with its own
inputs. Therefore, the number of flags to check and the number of unused
inputs are reduced to the minimum required by the solvers and
parameterizations that the user chooses. If users want to solve the

Point (h) is solved by deploying new components for the 1D, 2D, and 3D cases. In
the following section we mainly deal with points (b) to (e). Before discussing
details of some classes, a few general choices have to be reported. Data of
any type are stored internally in vectors of doubles, which in turn encapsulated in
appropriate Java objects. OOP good practice would suggest that an object
should be immutable

The more visible effect of our choices is that we have built various OMS3 components.

whetgeo1d-1.0-beta

netcdf-1.0-beta

closureequation-1.0-beta

buffer-1.0-beta

numerical-1.0-beta

In order to improve the re-usability of the Java code we adopted a generic
programming approach

Another requirement regards the division of software classes into three main
groups, as the lack of a proper separation between the parameterization of
physical processes and their numerical solutions has been recognized as one of
the weak points of existing land-surface models

The classes used, and their repository for third-party inspection, are illustrated in the 00_Notebooks referred to in Sect. 4 and in the Supplement. However, there are three pivotal groups of classes that we want to mention here: these contain the description of the geometry of the integration domain, the closure equation, and the state equation.

One of the key aspects to have in a generic solver regards the management of the grid and, in particular, the definition of its topology, or how grid elements are connected to each other. In the 1D case the description of the topology is quite simple since it can be implicitly contained in the vector representation: each element of the vector corresponds to a control volume of the grid, and it is only connected with the elements preceding and following it. It is worth noting that this approach is peculiar to 1D problems and cannot be adopted for the 2D and 3D domains, where, especially when unstructured grids are used, the grid topology requires a smart implementation of the incidence and adjacency matrices.

For each control volume it is necessary to store its geometrical quantities, their position and dimension, its variables, its parameter set, and the form of the equation to be solved there, referred to in the following as “equation state”. The appropriate arrangement of information, together with the internal design of the classes, allows us to create a generic finite-volume solver.

The

An abstract class,

UML class diagram for the Java Simple Factory applied for the choice of the SWRC model. The

The Simple Factory pattern

The

UML class diagram for the Java Simple Factory applied for the choice of the

Notably, the solver of a PDE problem can refer to the abstract class and to
its abstract object without implying the specific concrete equation to be
solved or its concrete parameterizations. Moreover, the compositionality of
the

In our code design the

As explained in Sect.

Let us consider, for example, the case of the

Adopting a procedural approach, the computation of the equation states is hard-wired into the code. The behaviour of each control volume is determined by an

Adopting the OOP and generic programming approach
(Fig.

Adopting OOP with a generic programming approach, the computation of the equation states is independent from the grid. In fact, the behaviour of each control volume is determined by the vector eSID –

The NCZ algorithm has been implemented in the

UML class diagram of the

The example has been illustrated in 1D, but it becomes even more effective when working in 2D or 3D, especially with an unstructured grid.

While most of what has been written so far is of general application, the
deployment shown here is 1D. Information on WHETGEO-1D for users and
developers is provided in the Supplement, where there is a Jupyter Notebook
that contains the guidelines for executing the codes for any of the
components. Its name starts with “00_”, and we call it “Notebook Zero” of
the components. The latest executable code can be downloaded from

For further information about input and output formats for WHETGEO-1D, please see the Notebook 00_WHETGEO1D_Richards.ipynb in the folder documentation of the Zenodo distribution.

Examples of uses of WHETGEO-1D can be found in the form of Python Notebooks in
the directory Notebooks/Jupyter. Documentation can be found in the form of Python
Notebooks in the directory documentation. Simulations with WHETGEO-1D are run
as OMS3 simulations. Therefore, the first operation to accomplish is to
prepare the appropriate .sim files. For new users, many simulation files are
available in the directory simulation of the Zenodo distribution. As shown in
Fig.

Input data can be broadly classified into time series, computational grid
data, and simulation parameters. Time series are used to specify the boundary
conditions of the problem. Time series are contained in .csv files with a
specific format that is OMS3-compliant

For the design of the output workflow we took advantage of the OMS3 system
that allows the user to connect stand-alone
components. Figure

The choice of including the

Workflow of WHETGEO-1D. The boundary condition readers, computational grid reader,

WHETGEO-1D can be integrated with the built-in calibration component

Workflow of WHETGEO-1D integrated with

Here, as an example, we present how to add the Brooks–Corey

The standard approach to adding a new SWRC parameterization, here the Brooks
and Corey model, requires the definition of a new class that extends the abstract
class

In order to use the Brooks–Corey model in the Richards equation it is
necessary to define a new class,

In this paper we discussed the issues raised by implementing a new expandable system to model the Earth's CZ, WHETGEO, the core of which is a reliable and robust integrator of the Richards–Richardson equation and the associated energy budget.

We would like to stress the following.

WHETGEO makes available the NCZ algorithm, which has a priori convergence ensured for any choice of time step and for a great variety of boundary and initial conditions.

The coupling between the

The application of our methods could benefit a large range of Earth science models, which at present require complicated workarounds

The adoption of the mixed form of the equation allows the joint modelling of the saturated and unsaturated soil and groundwater conditions.

Moreover, the coupling strategy with ponding water makes WHETGEO naturally suitable to investigate the partitioning of infiltration and surface runoff without any of the issues documented for other software (e.g.

The implementation of WHETGEO has been shown to solve three software requirements
and the (a) to (h) design specifications. Each of these was analysed and thus
influenced the choice of algorithms and code implementation. Of the
hydrological issues presented in seven observations, the issues 1 to 4 were also
solved, and the code provided some answers for observations 5 to 7 because of the following.

The code allows for the easy changing of soil water retention curves; therefore, for instance, it would be easy to implement new ones taking more accurate account of the different processes in the various ranges of suction. A description of how to add a new soil water retention curve is presented in Sect.

The effect of temperature on viscosity has been included, and, in the Supplement, we have shown that temperature changes in soil have relevant effects on infiltration and runoff production.

Freezing and thawing processes coupled with the

The flexibility of the code was obtained with the creation of the

The first deployment of the concepts was the 1D stand-alone water budget as well as
the coupled water and energy budget WHETGEO versions. The water budget was
tested against analytical solutions presented in

The model is an entirely new code that was accurately designed to allow easy
inspection and to support code literacy and class re-use. It is open-source
and built with open-source tools. It and its documentation fulfil the
requirements of open science

WHETGEO-1D was implemented as a Java component within the GEOframe, an
open-source, component-based hydrological modelling system. Within GEOframe,
each part of the hydrological cycle is implemented in a self-contained
building block, an OMS3 component

geomorphic and DEM analyses;

spatial extrapolation or interpolation of meteorological variables;

estimation of the radiation budget;

estimation of evapotranspiration;

estimation of runoff production with integral distributed models;

channel routing;

travel time analysis;

calibration algorithms.

The Object Modelling System v.3 (OMS3) is a component-based environmental
modelling framework that provides a consistent and efficient way to (1)
create science simulation components; (2) develop, parameterize, and evaluate
environmental models, as well as modify and adjust them as science advances; and (3)
re-purpose environmental models for emerging customer requirements

In OMS3 the term component refers to self-contained, separate software units
that implement independent functions in a context-independent manner

Compared to other environmental modelling frameworks (EMFs), OMS3 is
characterized by being a noninvasive and lightweight framework

Besides the technical aspects, the adoption of a software framework has a
positive effect on “nonfunctional” quality attributes, such as
maintainability, portability, re-usability, and understandability

Also, the adoption of an environmental modelling framework promotes the
concept of reproducible research, easing third-party inspection and
providing consistent and verifiable model results

Another advantage of using OMS3 is represented by the opportunity to keep the code development transparent to the user.

In this section we test the solver of the

We consider a one-dimensional homogeneous soil layer of

Comparison between the analytical and numerical solutions for the test problem TP1.

Relative water suction error for the test problem TP1.

In this numerical problem (TP2) we consider one-dimensional vertical
infiltration toward the water table through a layered soil. The initial
condition is determined by imposing as a lower boundary condition

Comparison between the analytical and numerical solutions for the test problem TP2.

Comparison of relative water suction error

The next test case was defined by

Hydraulic properties for the three soil types used in the Vanderborght test case (TP3).

Comparison between the analytical and the numerical solution for the test problem TP3. The three panels show the vertical profile of water suction at steady state for a constant flow rate of

The definition of the surface boundary condition is a nontrivial task since it
is a system-dependent boundary condition. The infiltration rate through the
soil surface depends on precipitation, rainfall intensity

The infiltration excess or Horton runoff occurs when the rainfall intensity is
larger than the infiltration capacity of the soil:

The saturation excess or Dunnian runoff occurs when the soil is saturated and additional water exfiltrates at the soil surface. Saturation excess generally occurs with long-duration, moderate rainfall or with a series of successive precipitation events. In this case the soil depth or the presence of shallow fragipan is the determining factor for saturation excess. Another possible cause is the rise of the water table up to the soil surface.

In this numerical experiment we consider a homogeneous soil of

Hydraulic properties of the silty clay loam soil

The initial condition is assumed to be hydrostatic with

Figure

In this section we present two numerical experiments to simulate the
saturation excess process. Saturation excess is more critical, in terms of
simulation stability, than the infiltration excess

Firstly, we consider a layered soil of

Hydraulic properties of the loam layer and clay layer in

Hydraulic properties of the loamy sand layer and clay layer in

Secondly, we consider a layered soil of

Repeating the above numerical experiment with a thicker loam–sandy layer
(Fig.

In this numerical experiment there is no saturation excess since the greater thickness of the uppermost layer ensures sufficient water storage capacity for the forcing rainfall.

Here we present a behavioural test case on the pure heat conduction
considering the surface energy balance. The purpose of this simulation is
twofold. First, we show an application of WHETGEO-1D that exploits existing
GEOframe components to model the external components of the surface energy
budget, specifically the incoming shortwave radiation

The soil column is

Behavioural test case of pure heat conduction in soil considering the surface energy budget.

Parameters of the SFC model.

Behavioural test case of pure heat conduction in soil considering the surface energy budget and the phase change of water.

By including the closure equation of the SFC presented by

Figure

The source code is written in Java using the object-oriented programming paradigm. The source code can be found at

The simulations and data presented here can be found
at

The supplement related to this article is available online at:

RR and NT were responsible for conceptualization. NT and RR developed the methodology. NT and RR were responsible for software engineering. NT performed code writing. RR and NT performed code revision. NT was responsible for data curation and simulations. NT and RR contributed to paper writing, review, and editing. NT and RR were responsible for documentation. RR acquired funding.

The contact author has declared that neither they nor their co-author has any competing interests.

Publisher's note: Copernicus Publications remains neutral with regard to jurisdictional claims in published maps and institutional affiliations.

The authors would like to thank Professor Vincenzo Casulli and Professor Michael Dumbser of the Department of Civil, Environmental and Mechanics Engineering at the University of Trento for their fruitful discussions on the numerical aspects of the work. We thank Concetta D'Amato for the help in preparing the supporting material. We would like to thank Joseph Eamonn Tomasi for his invaluable help with the linguistic revision. We especially thank the two anonymous reviewers for their constructive comments that helped to improve our paper.

This work has been partially supported by a PhD grant by the Department of Civil, Environmental and Mechanics Engineering at the University of Trento and by the Italian MIUR project (PRIN 2017) “WATer mixing in the critical ZONe: observations and predictions under environmental changes-WATZON” (project code: 2017SL7ABC).

This paper was edited by Min-Hui Lo and reviewed by three anonymous referees.