This documentation teaches how to run the OMS Richards 1D integrator.

1. Tubini et al.
LINKERS
OMS Richards 1D integrator
Niccol`o Tubini*†
, Aaron Iemma†
and Francesco Serafin†
*
Correspondence:
niccolo.tubini@unitn.it
Dipartimento di Ingegneria Civile
Ambientale e Meccanica, Trento,
Mesiano di Povo, Trento, IT
Full list of author information is
available at the end of the article
†
Code Author
Abstract
These pages teach how to run the solver for Richards’ equation 1D case inside the
OMS 3 console. Some preliminary knowledge and installation of OMS is mandatory
(see @Also useful). To perform the solution of the nonlinear system a nested Newton’s
type algorithm is used (Casulli and Zanolli, 2010).
@License:
GPL v. 3
@Inputs:
• SWRC model and its own parameters;
• θs (−);
• θr (−);
• Ks (m/s);
• Soil column discretization and initial condition for the water pressure (m);
• Type of the top boundary condition;
• Top boundary condition values;
• Type of the bottom boundary condition;
• Bottom boundary condition values;
• Type of algorithm to solve the nonlinear system;
• Error tolerance solving the nonlinear system.
@Outputs:
• Profile of water suction ψ for each time step of the simulation (m);
• Profile of dimensionless water content θ for each time step of the simulation (−).
@Doc Author: Niccol`o Tubini
@References:
• See References section below
Keywords: OMS; Richards’ equation 1D case

2. Tubini et al. Page 2 of 7
Code Information
Executables
This link points to the jar file that, once downloaded can be used in the OMS console:
https://github.com/GEOframeOMSProjects/OMS_Project_Richards1D/tree/master/
lib
Developer Info
This link points to useful information for the developers, i.e. information about the code
internals, algorithms and the source code
https://github.com/geoframecomponents
Also useful
To run a OMS project it is necessary to know how to use the OMS console. Information
at: ”How to install and run the OMS console”,
https://alm.engr.colostate.edu/cb/project/oms).
JGrasstools are required for preparing some input data (information at:
http://abouthydrology.blogspot.it/2012/11/udig-jgrasstools-resources-in-italian.
html
To visualize results you need a GIS. Use your preferred GIS, following its installation
instructions. To make statistics on the results, you can probably get benefits from R:
http://www.r-project.org/ and follow its installation instruction.
To whom address questions
niccolo.tubini@unitn.it
Authors of documentation
Niccol`o Tubini (niccolo.tubini@unitn.it)
This documentation is released under Creative Commons 4.0 Attribution International

3. Tubini et al. Page 3 of 7
Component Description
To study the time evolution of the water suction and hence of the dimensionless water
content one has to solve Richards’ equation. Richards’ equation for the one-dimensional
case is
∂θ(ψ)
∂t
=
∂
∂z
K(ψ)
∂
∂z
(ψ + z) (1)
where θ(ψ) is the dimensionless water content related to the water suction ψ through a
prescribed parametric function usually referred to as soil water retention curve (SWRC),
K(ψ) is the soil hydraulic conductivity, z is the positive upward vertical coordinate, and t
is time. The above equation is the so called mixed form of the Richards’ equation (Casulli
an Zanolli, 2010).
To solve Eq.(1) is necessary to provide a domain discretization, an initial condition for
the water suction, and two boundary conditions one at the soil surface and one at the
bottom.
Detailed Inputs description
General description
The input file for both the top and bottom boundary condition is a .csv file containing a
header and one series of input data.
The file must have the following header:
• The first 3 rows with general information such as the date of the creation of the file
and the author;
• the fourth and fifth rows contain the ID of the station;
• the sixth row contains the information about the type of the input data (in this
case, one column with the date and one column with double values);
• the seventh row specifies the date format (YYYY-MM-dd HH:mm).
All this information shown in the figure 1.
Figure 1 Heading of the .csv input file for the boundary conditions.
The input file for the initial condition is a .csv file containing two columns: the first
one the depth (m), and the second one the initial condition for the water suction (m).

4. Tubini et al. Page 4 of 7
It is worthwhile to point out that the first line refers to the deepest layer of the soil
column, whilst the last one to the uppermost one. Furthermore, the first column provides
a discretization of the domain. Indeed, the depth refers to the centroid of each control
volume in which the domain is discretized.
Figure 2 Example of a .csv input file for the initial condition.
Initial condition for the water pressure
The initial condition for the water pressure (m) is given for each control volume.
SWRC model
Three types of SWRC models are available: Van Genuchten (Van Genuchten, 1980),
Brooks an Corey (Brooks and Corey, 1964), and two-parameters lognormal distribution
(Kosugi, 1996).
Type of the top boundary condition
It is possible to assign either the water pressure at the soil surface (Dirichlet boundary
condition), or the water flux though the soil surface (Neumann boundary condition).
Top boundary condition
The rainfall time series (mm). In case one wants to assign a Neumann top boundary
condition the code handles the computation of the of the water flux related to the time
series.
Type of the bottom boundary condition
It is possible to assign either the water pressure at the bottom of the soil column (Dirichlet
boundary condition), or the free drainage boundary condition.
Bottom boundary condition
To assign a Dirichlet boundary condition it is necessary to provide a theoretical time
series of the water pressure a the bottom of the domain. This means to hypothesize the
water table time evolution.
When a free drainage boundary condition it is necessary to provide however a time
series, even thou its values will not be taken into account by the the solver (this will be
fixed in the next release).

5. Tubini et al. Page 5 of 7
Algorithm to solve the nonlinear system
It is possible to choose between Newton’s algorithm and the nested Newton’s one. The
first one is faster but its convergence is not alway guaranteed, by the contrast the nested
Newton’s algorithm is slower but always converges.
Algorithm tolerance
Defines a threshold on the error of the system solution.
Detailed Outputs description
water pressure and dimensionless water content
The computed water pressure and dimensionless water content are given as time series.
Respectively, their units are (m) and (−).
Examples
The following .sim file is customized for the use of the solver for Richards’ equation 1D
case. The .sim file can be downloaded from here:
https://github.com/GEOframeOMSProjects/OMS_Project_Richards1D/tree/master/
simulation
/*
* Solver for Richards ’ equation 1D
* water pressure initial condition is assigned by the user
* boundary conditions assigned by the user
*
* Numerical scheme :
* Casulli , Vincenzo , and Paola Zanolli .
* "A nested Newton -type algorithm for finite volume methods
solving Richards ’ equation in mixed form ."
* SIAM Journal on Scientific Computing 32.4 (2010) :
2255 -2273.
*/
import static oms3.SimBuilder.instance as OMS3
def home = oms_prj
// start and end date of the simulation
def startDate= "2017 -01 -01 00:00"
def endDate="2017 -05 -24 00:00"
// time interval of temporal series [ minutes ]
def tTimestep = 5
OMS3.sim {
resource "$oms_prj/lib"
// model () {
model(while : " reader_data_topBC .doProcess" ){
components {
"solver" " Richards1DSolver . Richards1DSolver "
" reader_data_topBC " "org.jgrasstools .gears.io. timedependent .
OmsTimeSeriesIteratorReader "
" reader_data_bottomBC " "org. jgrasstools .gears.io. timedependent .
OmsTimeSeriesIteratorReader "
"read_iC" "readTxt. ReadTxtMultiColumn "
}
parameter {

6. Tubini et al. Page 6 of 7
// hydraulic conductivity at saturation [m/s]
"solver.ks" "0.000000556 "
// dimensionless water content at saturation [-]
"solver.thetaS" "0.38"
// dimensionless residual water content [-]
"solver.thetaR" "0.068"
// parameters of Van Genuchten ’s SWRC model (Van Genuchten ,
1980)
"solver.n" "1.09"
"solver.alpha" "0.8" // [1/m]
// parameters of Brooks ’ and Corey ’s SWRC model ( Brooks and
Corey , 1964)
"solver.psiE" "1.9" // [m]
"solver.lambda" "1.9"
// parameters of two - paramaters lognormal distribution
// for SWRC model (Kosugi , 1996)
// median of the pore size distribution [m]
"solver.rMedian" " 0.0000020781 "
// standard deviation of the pore size distribution
"solver.sigma" "0.6"
// Available SWRC models :
// - "Van Genuchten "
// - " Kosugi "
// - " Brooks and Corey"
"solver. soilHydraulicModel " "Van Genuchten"
// Type of the top boundary condition :
// - "Top Dirichlet " the water pressure value is assigned
// - "Top Neumann " the water flux through the soil surface is
assigned
"solver.topBCType" "Top Dirichlet";
// Type of the bottom boundary condition :
// - " Bottom Dirichlet " the water pressure value is assigned
// - " Bottom Free Drainage " the water flux is controlled only
// by the gravitational gradient
"solver. bottomBCType " "Bottom Dirichlet";
// Height of the soil column [m]
"solver.spaceBottom" "2.0"
// nested Newton tolerance , range (10^( -3) ; 10^( -14))
"solver. newtonTolerance " "0.00000001"
// Algorithm to solve the nonlinear system :
// - 0 --> Newton ’s method
// - 1 --> nested Newton :
"solver. nestedNewton " "1"
// time step [s], it must be consistent
// with tTimestep defined at line 22
"solver.tTimestep" "300"
// parameters reader data input top boundary condition
" reader_data_topBC .file" "$oms_prj // data/
Trento_TopBC .csv"
" reader_data_topBC .idfield" "ID"
" reader_data_topBC .tStart" "${startDate}"
" reader_data_topBC .tEnd" "${endDate}"
" reader_data_topBC .tTimestep" "${tTimestep}"
" reader_data_topBC .fileNovalue" " -9999"
// parameters reader data input bottom boundary condition
" reader_data_bottomBC .file" "$oms_prj // data/
Trento_BottomBC_0 .csv"
" reader_data_bottomBC .idfield" "ID"
" reader_data_bottomBC .tStart" "${startDate}"
" reader_data_bottomBC .tEnd" "${endDate}"
" reader_data_bottomBC .tTimestep" "${tTimestep}"

7. Tubini et al. Page 7 of 7
" reader_data_bottomBC . fileNovalue" " -9999"
// file path for the initial condition
"read_iC.filePath" "$oms_prj/data/ InitialConditionHydrostatic .
csv"
// folder path for the output files
"solver.dir" "$oms_prj/output"
}
connect{
"read_iC.depth" "solver.depth"
"read_iC.suctionIC" "solver.iC"
" reader_data_topBC .outData" "solver.inTopBC"
" reader_data_bottomBC .outData" "solver.inBottomBC"
" reader_data_topBC .tCurrent" "solver. inCurrentDate "
}
}
}
Data and Project
The following link is for the download of the input data necessaries to execute the com-
ponent (as shown in the .sim file in the previous section ):
https://github.com/GEOframeOMSProjects/OMS_Project_Richards1D/tree/master/
data
The following link is for the download of the OMS project for the component:
https://github.com/GEOframeOMSProjects/OMS_Project_Richards1D
%
References