Supplement of Implementing the Water, HEat and Transport model in GEOframe (WHETGEO-1D v.1.0): algorithms, informatics, design patterns, open science features, and 1D deployment

Abstract. 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 (R2) we take advantage of
the nested Newton–Casulli–Zanolli (NCZ) algorithm that ensures the convergence
of the numerical solution in any condition. Second, starting from numerical
and modelling needs, we present the design of software that is intended to
be the first building block of a new customizable land-surface model that is
integrated with process-based hydrology. WHETGEO is developed as an
open-source code, adopting the object-oriented paradigm and a generic
programming approach in order to improve its usability and
expandability. WHETGEO is fully integrated into the GEOframe/OMS3 system,
allowing the use of the many ancillary tools it provides. Finally, the paper
presents the 1D deployment of WHETGEO, WHETGEO-1D, which has been tested
against the available analytical solutions presented in the Appendix.



Homogeneous soil
We consider a one-dimension homogeneous soil layer of 1 [m] depth (TP1). The saturated hydraulic conductivity value is assumed to be 1.0

Effect of temperature on water viscosity
Temperature affects water viscosity, which effectively doubles in passing from 5 to 20 [ • C] (Eisenberg et al., 2005), with a positive feedback on the infiltration process. This has been clearly observed in natural systems (Eisenberg et al., 2005;Engeler et al., 2011;Ronan et al., 1998) where infiltration rates follow diurnal and seasonal temperature-cycles. In fact, according to (Muskat and Meres, 1936), the unsaturated hydraulic conductivity can be expressed as where κ r (θ) [−] is the relative permeability, κ [L 2 ] is the intrinsic permeability, ρ [L 3 M −1 ] is the liquid density, g is the acceleration of gravity, and ν [L 2 T −1 ] is the kinematic viscosity of the liquid. Thus, for constant θ, variations in K(θ) due to temperature can be accounted as (Constantz and Murphy, 1991): In Eq. (2), T 1 is a reference temperature while T 2 is the soil water temperature. Based on this equation the value of K(θ) increase by over three-fold between 5 to 60 [ • C] (Constantz and Murphy, 1991). Below we repeat the synthetic experiment presented in Section C3.1 C3.2 regarding respectively the infiltration excess and saturation excess processes, taking into account different soil temperatures. In these simulation temperature is kept constant over time.

Infiltration excess
In this numerical experiment we consider a homogeneous soil of 3 [m] depth. Soil hydraulic properties are described with the Van Genuchten's model, Table (1).
The initial condition is assumed to be hydrostatic with ψ = 0 [m] at the bottom. The surface boundary condition is a synthetic rainfall, as in because the hydraulic conductivity is lower the reference value, whereas when temperature is higher the infiltration is faster. Although the saturated hydraulic conductivity does not change by order of magnitude with temperature, the relative small variations in its values are amplified by the capillary gradient.

Saturation excess
We

Rain [mm]
Figure 4: In this numerical experiment the run-off varies with soil temperature. As the soil becomes colder the maximum for water ponding increases and water takes more time to infiltrate.
As temperature increase the ponding water at the soil surface is smaller. The depth of ponding water when T = 30 [ • C] is almost one third compared to that for T = 5 [ • C].

Introduction
GEOframe-NewAge is an open-source, semi-distributed, component-based hydrological modeling system. It was developed in Java and based on the environmental modeling framework Object Modeling System V3 (OMS3).
The core of the project was born from the idea of Professor Rigon and mainly developed at the Department of Civil, Environmental and Mechanical Engineering of University of Trento, Italy. During the last decade, GEOframe community grew and now is made of many scienNsts around the world who share their work, codes, knowledge and experiences for the benefit of all GEOframe users, whilst pursuing their individual research interests and careers.
Therefore, giving appropriate credits for the intellectual input through co-authorships or citations should be the proper functioning of the community.
This document sets out how members of the GEOframe community should recognise the intellectual contribution of the GEOframe community's members.

Principal web references
In the following, the principal GEOframe web references, where you can find the latest achievements, developments, publications, code versions, courses and ideas are reported: • http://abouthydrology.blogspot.com/search/label/GEOFRAME

General principles
The formal, legal condiNons that govern the use of GEOframe at present are given by the G.P.L. v 3. Each GEOframe component can have its own license though.
This Policy applies to all uses of GEOframe products, including but not limited to data and computer code, for research and teaching. It is not intended to restrict what can be done with them, rather to ensure appropriate acknowledgement and communication between users and developers. This policy will be updated regularly.
A developer is any person whose expertise has either significantly influenced the design of GE-Oframe code or who has written code, with no distinction between scientific and technical inputs. Developers are encouraged to publish their work in reasonable time, while potential users should approach developers early in their study to avoid duplication or wasted effort on new developments. Developers may reserve the right for the first scientific application of their scheme and will be able to advise if and when co-authorship, citation or acknowledgement is appropriate.
A list of new developments and the scientists responsible for them will be maintained on the GEOframe website. These contributions should be recognised by citations.
When writing the source code of a component, GEOframe developers should consider the following: • Provide a brief description of what the program does.
• State the authors of the code and the following modifiers.
• Describe the input required to run the component and its output.
• Some notes concerning the limitations, and the algorithms used within the component. A wishlist for the future version and/or information.
• Articles or books which have inspired the codex or justified its necessity. Users are encouraged to cite these papers in their own work • If you want to contribute code or documentation, create pull requests, we will consider them.
Ideally a committed code should conform to the rules required by Joss. Acknowledgments should be considered for a wider list of scientists who contributed to the modelling system, but whose contributions may not be documented in publications. A list of such scientists will be maintained on the GEOframe web page.
When writing a paper, GEOframe users and developers should consider the following:

Co-authorship
• Is expected if your published research benefited from a new development, i.e. the development influenced your study to the extent that it was discussed in the paper.
• Is expected if your research required substantial direct input from a developer, e.g. to make substantial modifications to the code that you used, to help design the experiments etc.
• Should be considered for a wider list of scientists who contributed to the modelling system, but whose contributions may not be documented in publications. A list of such scientists will be maintained on the GEOframe web page

Acknowledgements
• Should be considered for scientists involved in GEOframe code developments that have become established.

Citation of a published paper
• Is expected if a citable paper describing a development exists. A narrative description of the model and a list of papers describing developments will be maintained on the GEOframe web page.
Please be generous in offering credit for other people's work, as everyone benefits in the end. Use best judgement and, if in doubt, error the side of inclusiveness.