Bancheri

LINKERS

JGrass-NewAge: ProbabilitiesBackwardcomponentMarialaura Bancheri

Correspondence:

marialaura.bancheri@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

Abstract

These pages teach how to run the ProbabilitiesBackward component inside the OMS3 console. Some preliminary knowledge and installation of OMS is mandatory (see@Also useful). This component deals with the computation of the backward probabilitydensity functions (pdfs) of the residence time, travel time and evapotranspiration timeconditional on the actual time, according to (). Solving the simple ODE, once definedthe mixing assumption, it is possible to obtain the residence time, the travel times andevapotranspiration times pdfs and the mean travel and evapotranspiration times. Theresults of the component are given in tridimensional matrices, in which two dimensionsare the injection and current times, and the third is the value of the variable. To obtainthe time series of the mean travel and evapotranspiration times, a second component (injection time integrator) is required, which computes the time integral of the outputmatrices.

@Version:0.1

@License:GPL v. 3

@Inputs:• Rainfall (mm);• Water storage (mm);• Evapotranspiration (mm);• Discharge (m3/m2);• Station ID (-);• Start date (String);• Start Date Water Budget (String);• End date (String);• Model solver (String);• SAS type (String);• Params (vector);

@Outputs:• Residence times backward pdfs [T−1];• Travel times backward pdfs [T−1];• Evapotranspiration times backward pdfs [T−1];• Mean travel times [T];• Mean evapotranspiration times [T];

@Doc Author: Marialaura Bancheri

@References:• See References section below

Keywords: OMS; JGrass-NewAGE Component Description; Travel times

Bancheri Page 2 of 10

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_TT/tree/master/BackwardPdfs/

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 JGrass-NewAGE 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

marialaura.bancheri@unitn.it

Authors of documentation

Marialaura Bancheri (marialaura.bancheri@unitn.it)

This documentation is released under Creative Commons 4.0 Attribution International

Bancheri Page 3 of 10

Component DescriptionResidence time, travel time and life expectancy of water and associated constituents

flowing through the control volume are three related quantities whose meaning is well

defined by the following equation:

T = (t− τ)︸ ︷︷ ︸Tr

+ (ι− t)︸ ︷︷ ︸Le

(1)

where T [T] ([T] means time units) is the travel time, t [T] is the actual time measured by

a clock, τ [T] is the injection time (i.e., the time in which a certain amount of water enters

the control volume) and ι [T] is the exit time (i.e., the time in which a certain amount

of water exits the control volume). Based upon these definitions, Tr := t− τ [T] is the so

called residence time, or the age of water entered at time τ , and Le := ι− t [T] is the life

expectancy of the same water molecules which are inside of the control volume. Due to

the heterogeneity of the media and the chaos of some dynamical processes, usually T , Tr

and Le are considered as random variables, and therefore they are studied by means of

their probability distributions

In particular, the pdfs of residence time conditional on the actual time t, p(Tr|t), can

be defined as:

p(Tr|t) ≡ p(t− τ |t) :=s(t, τ)

S(t)[T−1] (2)

where s(t, τ) [L3 T−1) is a sub-volume of the water storage, S(t), and refers to water

injected into the system at time τ .

The pdfs of travel time for water exiting the control volume as discharge, pQ(t − τ |t),can be defined as:

pQ(t− τ |t) =q(t, τ)

Q(t)[T−1], (3)

where q(t, τ) [L3 T−2] is the part of the discharge Q(t) exiting the control volume at time

t but composed by water molecules entered at instant τ .

Eventually, the pdf of travel time for water exiting the control volume as water vapor,

pET(t− τ |t), can be defined as:

pET(t− τ |t) =

aeT (t, τ)

AET (t)[T−1], (4)

After the above definitions, the water budget equation for a generic control volume, can

be written as:

d

dtS(t)p(Tr|t) = J(t)δ(t− τ)−Q(t)pQ(t− τ |t)−AEt(t)pET

(t− τ |t) (5)

when a single “new water” injection of mass is considered, and the bulk quantities S(t),

Q(t), AET (t) are known. The travel time probabilities on the right side of (5) are not

known, To this scope (1) introduced the StorAge Selection (SAS) functions, ω(t, τ) [-],

for each of the outputs, so that:

pQ(t− τ |t) := ωQ(t, τ)p(Tr|t) (6)

Bancheri Page 4 of 10

and:

pET(t− τ |t) := ωET

(t, τ)p(Tr|t) (7)

Therefore equation (5), after the proper substitutions, becomes:

d

dtS(t)p(Tr|t) = J(t)δ(t− τ)−Q(t)ωQ(t, τ)p(Tr|t)−AEt(t)ωET

(t, τ)p(Tr|t) (8)

which represents a linear ordinary differential equation that can be solved exactly.

Once solved the eq. 8, it is possible to compute the mean age of water for any of the

two outlets, which is defines as:

〈Tr(t)〉i =

∫ t

0

(t− τ)pi(t− τ |t)dτ (9)

for i ∈ {Q,ET }, an it is, obviously, a function of the sampling time.

Detailed Inputs description

The input file is a .csv file containing a header and one or more time series of input data,

depending on the number of stations involved. Each column of the file is associated to a

different station.

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 IDs of the stations (e.g. station number 8:

value 8, ID, ,8);

• 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 the previous information shown in the figure 1.

Figure 1 Heading of the .csv input file

Rainfall

The rainfall is given in time series of (mm) for the investigated station .

Water sorage

The water storage is given as a time series f (mm) for the investigated station.

Bancheri Page 5 of 10

Evapotranpiration

The evapotranpiration is given in time series of (mm) for the investigated station.

Discharge

The discharge is given in time series for the investigated station in (m3/m2).

Station ID

Station ID is the ID of the investigate station.

Start date

Start date is a string containing the first day of the simulation.

Start Date Water Budget

Start Date Water Budget is a string containing the first day of the simulation of the water

budget time series, if it is different from the start date of the actual simulation.

End date

End date is a string containing the last day of the simulation

Model solver

Model Solver is a string defining the integrator for the ODE in eq. 8: ”dp853” is Dormand-

Prince 8(5,3) integrator or ”Eulero” is the Euler integrator;

SAS type

SAS type is a string defining the SAS function chosen. Just the BetaDistribution has been

implemented.

Params

Params is a vector containing the parameter of the SAS distribution.

Detailed Outputs descriptionThe output are given in tridimensional matrices, t× ti × variable value, which must be

integrated in the injection time dimension to obtain the time series of the mean travel

times and the mean evapotranspiration times. Fig. 2 shows an example of a pdfs matrix.

The injection times are in the first column, whose length is l. In this case l = 5. The

actual time is t = ti− i, with i varying in the interval [0, l−1], in this case [0, 4]. Each row

contains a number of values equals to t. So for example for the first row i = 0 and there

are 5 elements, the second 4 and so on. If, at a given injection time ti, the input rainfall

is zero, the rows has one zero value. This structures take into account two important

aspect: the first is that when t < ti, the variables are zero; the second is the speed of the

computation, which, in this case, is the minimum possible.

Bancheri Page 6 of 10

Figure 2 : Example of output pdfs matrix: for each time step, the length of the row decrease of onevalue, till the end of the time series

Residence times backward pdfs

figure 3 shows an example of a residence time pdf obtained considering the well mixing

assumption (ωQ = ωET = 1). Its value are zero when there is no rainfall and its integral

in time is equal to one, as a proper pdf.

0 50 100 150

0.0

0.1

0.2

0.3

0.4

Residence time pdf for a single injection time

Time [h]

Res

iden

ce ti

me

pdf [

1/T]

Figure 3 : Evolution in time of the residence time pdf for a given injection time

Travel times backward pdfs

In the case of well mixing assumptions, residence time, travel time and evapotranspiration

time pdfs are the same.

Evapotranspiration times backward pdfs

In the case of well mixing assumptions, residence time, travel time and evapotranspiration

time pdfs are the same.

Mean travel times

Figure 4 shows an example of a time series of mean travel times, after being integrated by

the component InjectionTimeIntegrator (see ). The mean travel times evolution depend

on the input fluxes, in this case the rainfall and, of course, on the compartment considered

(bigger for deeper layers and smaller for upper layers).

Bancheri Page 7 of 10

0 2000 4000 6000 80000

200400600800

Mean travel times in case of well mixing assumption

Time [h]

Mea

n TT

[h]

Figure 4 : Example of output pdfs matrix: for each time step, the length of the row decrease of onevalue, till the end of the time series

Mean evapotranspiration times

Also in this case, being in the well mixing assumption, mean travel times and mean

evapotranspiration times are equal.

ExamplesThe following .sim files are customized for the use of the probabilities backward component

and for the injection time integrator. The .sim files can be downloaded from here:

https://github.com/GEOframeOMSProjects/OMS_Project_TT/tree/master/BackwardPdfs/

simulation

https://github.com/GEOframeOMSProjects/OMS_Project_TT/tree/master/Integrator/

simulation

Probabilities Backward .sim file

import static oms3.SimBuilder.instance as OMS3def home = oms_prjdef startDate= "1994 -01 -01 00:00"def endDate= "1995 -01 -01 00:00"OMS3.sim {

resource "$oms_prj/lib"

model(while:"reader_data_J.doProcess") {components {

"reader_data_J" "org.jgrasstools.gears.io.timedependent.OmsTimeSeriesIteratorReader"

"pdfs" "travelTimesBack.ProbabilitiesBackward""writer_p" "org.jgrasstools.gears.io.timedependent.

OmsTimeSeriesIteratorWriter""writer_pQ" "org.jgrasstools.gears.io.timedependent.

OmsTimeSeriesIteratorWriter""writer_pET" "org.jgrasstools.gears.io.timedependent.

OmsTimeSeriesIteratorWriter""writer_Qback" "org.jgrasstools.gears.io.timedependent

.OmsTimeSeriesIteratorWriter""writer_ETback" "org.jgrasstools.gears.io.timedependent

.OmsTimeSeriesIteratorWriter""writer_Qtt" "org.jgrasstools.gears.io.timedependent.

OmsTimeSeriesIteratorWriter""writer_ETtt" "org.jgrasstools.gears.io.timedependent.

OmsTimeSeriesIteratorWriter"}

parameter{

Bancheri Page 8 of 10

"reader_data_J.file" "${home}/data/rainfall.csv""reader_data_J.idfield" "ID""reader_data_J.tStart" "${startDate}""reader_data_J.tEnd" "${endDate}""reader_data_J.tTimestep" 60"reader_data_J.fileNovalue" " -9999"

"pdfs.ID" 209"pdfs.tStartDate" "${startDate}""pdfs.tStartDateWaterBudget" "${startDate}""pdfs.tEndDate" "${endDate}"

"pdfs.inPathToStorage" "${home}/data/Storage.csv""pdfs.inPathToDischarge" "${home}/data/Q.csv""pdfs.inPathToET" "${home}/data/ET.csv""pdfs.m_solver" "dp853""pdfs.SAStype" "BetaDistribution""pdfs.params" "{1,1}"

"writer_p.file" "${home}/ output/p.csv""writer_p.tStart" "${startDate}""writer_p.tTimestep" 60"writer_p.fileNovalue" " -9999"

"writer_pQ.file" "${home}/ output/pQ.csv""writer_pQ.tStart" "${startDate}""writer_pQ.tTimestep" 60"writer_pQ.fileNovalue" " -9999"

"writer_pET.file" "${home}/ output/pET.csv""writer_pET.tStart" "${startDate}""writer_pET.tTimestep" 60"writer_pET.fileNovalue" " -9999"

"writer_Qback.file" "${home}/ output/Qback.csv""writer_Qback.tStart" "${startDate}"

"writer_Qback.tTimestep" 60"writer_Qback.fileNovalue" " -9999"

"writer_ETback.file" "${home}/ output/ETback.csv""writer_ETback.tStart" "${startDate}""writer_ETback.tTimestep" 60"writer_ETback.fileNovalue" " -9999"

"writer_Qtt.file" "${home}/ output/Qtt.csv""writer_Qtt.tStart" "${startDate}""writer_Qtt.tTimestep" 60"writer_Qtt.fileNovalue" " -9999"

"writer_ETtt.file" "${home}/ output/ETtt.csv""writer_ETtt.tStart" "${startDate}""writer_ETtt.tTimestep" 60"writer_ETtt.fileNovalue" " -9999"

}connect {

"reader_data_J.outData" "pdfs.inPrecipvalues"

"pdfs.outHMPback" "writer_p.inData""pdfs.outHMPQback" "writer_pQ.inData""pdfs.outHMPETback" "writer_pET.inData"

"pdfs.outHMQback" "writer_Qback.inData""pdfs.outHMETback" "writer_ETback.inData"

"pdfs.outHMQtt" "writer_Qtt.inData""pdfs.outHMETtt" "writer_ETtt.inData"

}

Bancheri Page 9 of 10

}}

Injection time integrator .sim file

import static oms3.SimBuilder.instance as OMS3def home = oms_prjdef startDate= "1994 -01 -01 00:00"def endDate= "1995 -01 -01 00:00"OMS3.sim {

resource "$oms_prj/lib"

model(while:"reader_data_Qtt.doProcess") {components {

"reader_data_Qtt" "org.jgrasstools.gears.io.timedependent.OmsTimeSeriesIteratorReader"

"integrator" "integrator.InjectionTimeIntegration"

"writer_Qint" "org.jgrasstools.gears.io.timedependent.OmsTimeSeriesIteratorWriter"

}

parameter{

"reader_data_Qtt.file" "${home}/data/Qtt.csv""reader_data_Qtt.idfield" "ID""reader_data_Qtt.tStart" "${startDate}""reader_data_Qtt.tEnd" "${endDate}""reader_data_Qtt.tTimestep" 60"reader_data_Qtt.fileNovalue" " -9999"

"integrator.ID" 209"integrator.tStartDate" "${startDate}""integrator.tEndDate" "${endDate}"

"writer_Qint.file" "${home}/ output/Qtt_int.csv""writer_Qint.tStart" "${startDate}""writer_Qint.tTimestep" 60"writer_Qint.fileNovalue" " -9999"

}connect {

"reader_data_Qtt.outData" "integrator.inQoutvalues"

"integrator.outHMQ" "writer_Qint.inData"

}

}}

Data and ProjectThe following link is for the download of the input data necessaries to execute both the

previous components (as shown in the .sim files in the previous section ) :

https://github.com/GEOframeOMSProjects/OMS_Project_TT/tree/master/BackwardPdfs/

data

https://github.com/GEOframeOMSProjects/OMS_Project_TT/tree/master/Integrator/

data

Bancheri Page 10 of 10

The following link is for the download of the OMS project for the TT component:

https://github.com/GEOframeOMSProjects/OMS_Project_TT

%

References1. Botter, G., Bertuzzo, E., Rinaldo, A.: Catchment residence and travel time distributions: The master equation.

Geophysical Research Letters 38(11) (2011)