(version 2.1)

Table of contents

Introduction

iGrOw is a program packed in a html-document that calculates the groundwater flow to an open water drain in a vertical cross section. As output the program produces three views (positioned vertically underneath each other, so the vertical scroll bar has to be used to go from one to the other), illustrated by in the picture below:

Moreover iGrOw uses six graphical menus as interface.

(Back to top)

Install


Extract all the files of iGrOw.zip into one folder. The content of the folder should look like in the following figure:


drawing

(Back to top)

Opening the html

Both files iGrOwManual.html and iGrOw.html can be opened with almost all browsers.
You succeeded opening the first one, otherwise you would not be reading this.

Opening iGrOw.html shows a screen as in the following figure:

drawing

It may be useful to open this manual in a second tab of the browser, as illustrated in the figure above.

Only part of the graphs can be seen in the window, as the vertical scroll bar suggests.

(Back to top)

Resizing the browser window

The size of the graphs presented adjust them self to the size of the browser window.
If one does change the size of the browser window one can force this adjustment by hitting the "reload" button (may differ between browsers) as in the following figure:

drawing

Reloading the "iGrOw.html" however undoes all settings and calculations.

(Back to top)

Handling the menus

The interface of iGrOW is strongly interactive. Several menus make this possible.
As the program opens, all of these menus are open. One can however close these menus, and open the ones of choice, as shown by:
drawing

Moreover, these menus can be dragged to an arbitrary postion.
By double clicking on the top, a menu changes from minimized to full and back again.

(Back to top)

Zooming in the local view

The local view of the systems opens with a preselected width and the total depth. The cross-like symbol on the left top (which can be dragged to any position) allows the user to change this:

drawing

(Back to top)

The geometrical settings

The geomenu

The geomenu collects all the settings of parameters that have a pure geometrical meaning.

In principle the user can choose any unit for these parameters, but in all the examples that follow it is assumed that the values are given in [m].

Opening the "geo"-menu is done by checking the first box of the main menu. Unchecking it removes this menu from the window.
When checked, a new menu (that can also be dragged, minimized and maximized) appears in the window showing the geometrical variables whose values can be changed through this menu, as is shown in the following figure:

drawing

The following figure clarifies the meaning of the 5 first values in this menu.

drawing

These values are:

Changing a value in this geo-menu has an immediate effect on all plots in the window as can be seen in the following picture:

drawing

All these values have preset minimum and maximum values (set in the script "iGrOwmenu.js").
There are also relations between the settings that need to be satisfied. For instance, the drain bottom should never be higher than the domain height. The user is warned if he nevertheless tries to do this.
So if one wants to lower the domain height and the drain bottom in such a way that the new domain height is below the current drain bottom, one should first lower the drain bottom to avoid this type of conflicts.

(Back to top)

The bed form of the drain

The bed form of the drain is a smooth curve determined by three parameters: bottom height, width and angle, as illustrated in the following figure:

drawing

Technically, the smooth curve of the drain bottom is determined by a cubic spline:

z(x)=a0+a1  x+a2  x3+a3  x3z(x) = a_0 + a_1 \; x + a_2\; x^3 + a_3 \; x^3
uniquely defined by:

The following figure shows 3 of such splines.


drawing

The figure above shows that if we choose xb=x1x_b=x_1 too far to the left, the resulting spline
takes values below the drain bottom, which is unwanted. For values at the right, as e.g. xb=x2x_b=x_2 this is no longer the case. iGroW chooses the smallest value xb=xx_b=x_* for which the spline does not give values below the drain bottom.

(Back to top)

Add base layer

The second to last button in the geo-menu "add base layer" changes the system to solve.

drawing

If checked, extra input fields appear in the hydro-vars-menu (see the relevant section).

(Back to top)

The aspect of the plots

The graphs shown have different x-axis and y-axis scales, chosen such as to fill the available space in the window.
In the menu, this is called the "image" aspect. Plotting under this aspect does not preserve orthogonality. By choosing the "physical" aspect an x over y = 1 aspect is used for plotting. The difference between image and the physical aspect is usually much larger for the top graph, shown here in the image below:

drawing

The "physical" aspect plot the true curvatures and angles, orthogonality correctly presented.
That in contrast with the "image" aspect curvatures and angles are not represented according to their true physical values.

The local view is excluded from this aspect change, as it has its own re-scaling methods (see section).

(Back to top)

The physical settings

The hydro-vars-menu

The hydro vars menu (appears if second box in main menu is checked, again: can be dragged to any place in the window, minimized and maximized by double-clicking) allows the user to set value for physical variables. The precise role of these variables is explained in the equations section. The two drain resistance parameters (c_drain and c_seepage) will be explained in the next section.

The parameters in this menu also involve time. In principle the user can choose any time unit, but in all examples that follow this time unit is [day].

Changing the drain level gives immediate changes in the graphs. Changes of the other values will only become visible through their effects on the solution. Note that the recharge input value will be divided by 1000 when used in the calculations (so that with the choice of [m] for length en [day] for time, the unit of this field is [mm/day]).

The following figure shows this menu:
drawing

The horizontal conductivity is given by kxxk_{xx}, the vertical by kzzk_{zz} (and kx,zk_{x,z} should be non-zero if a tensor is to be used, see section).
With the standard choice of units, these parameters are in [m/day].

When one the option add lower boundary layer was chosen in the geo-menu, two new fields are added to this menu to be used to calculate the fluxes over this lower boundary, as in the following figure:

drawing

(Back to top)

The outflow resistance

The resistance of the groundwater flow to the drain is determined by two parameters: c_drain and c_seepage.

Resistances have the dimensions of time, so with the standard choice of unit these should be given in [day].

This resistance is depth dependent c(z)c(z)

It is clear that one should have c_seepage \leq c_drain, equality occuring when the resistance is constant over depth.

The following figure illustrates this depth relation:


drawing

(Back to top)

The flow equations


drawing

The problem to solve is to calculate for each point (x,z)(x,z) below the groundwater surface the groundwater head H(x,z)H(x,z).
In the figure above the variation of HH is indicated by colors.

Calculating the position of the groundwater surface is part of the problem to be solved.
The groundwater surface consists of the points (x,z)(x,z) for which the following equation holds:
H(x,z)=zH(x,z) = z

The flux is calculated by:

Q=[QxQz]=[kxxkxzkxzk_zz][H/xH/z]\vec{Q}= \begin{bmatrix} Q_x \\ Q_z \end{bmatrix} = - \begin{bmatrix} k_{xx} & k_{xz} \\ k_{xz} & k\_{zz} \end{bmatrix} \begin{bmatrix} \partial H/\partial x\\ \partial H/\partial z \end{bmatrix}

The mass balance equation is in each point (x,z)(x,z) given by:

Qxx(x,z)+Qzz(x,z)=q(x,z)\frac{\partial Q_x}{\partial x}(x,z) + \frac{\partial Q_z}{\partial z}(x,z)={q}(x,z)

The external flux has different expressions on different parts of the domain:

  1. in a point AA in the interior of the domain the external flux is not present:
    q(A)=0q(A) = 0

  2. in a point BB on the groundwater surface, the external flux is given by the recharge intensity rr:
    q(B)=rq(B) = r

  3. the left and right boundaries are considered as water divides, so no water enters or leaves the system there so that for a point CC:
    q(C)=0q(C) = 0

  4. At a point DD on the lower boundary, two choices are possible:

  1. at points as EE where the system is contact with the water in the drain (with constant head HdrainH_{drain} and resistance cdrainc_{drain}
    the flux is given by:
    q(E)=HdrainH(E)c(zE)q(E) = \frac{H_{drain}-H(E)}{c(z_E)}

    for c(zE)c(z_E) see the section on outflow resistance

  2. at points as FF where the system is contact with the atmosphere the flux is given by:
    q(F)=zFH(F)cseepageq(F) = \frac{z_F-H(F)}{c_{seepage}}

(Back to top)

The numerical settings

The numeric menu

As the equations can not be solved analytically, a numerical solution will be calculated. The first step in this procedure is make a discretization of space. A finite number of nodes will be placed in the domain, and only in these nodes an approximation to the HH's will be calculated. As the solution will show dramatically different variations throughout the solution domain, with very horizontal flow on the right and with strongly curved flow near the bottom of the drain. A critical point is thus the rightmost point of the drain. A uniform discretization would require an extremely large number of nodes. Therefor a non-uniform discretization is implemented.
The following figure shows the parameters determining such a discretization as can be set through the numerical vars menu:

drawing

The discretization nodes will be generated on a regular grid of straight vertical lines and curved horizontal ones.
Initially this grid will fill the total below-ground space.
The grid is adaptive: it will adjust itself to the solution such that the grid only fills that part of the domain beneath the groundwater surface. This will be done in such a way that they stay on their original vertical line, to the top will be on the groundwater surface and the nodes on each vertical will keep their relative distances.

As the nodes are positioned on a grid, a discretization is specified by giving horizontal and vertical information:

  1. "#hor under drain": the number of vertical lines of nodes underneath the drain level

  2. "#hor right of drain": the number of vertical lines of nodes on the right hand side of the drain level

  3. "densification hor": the larger this number, the more the vertical lines cluster around the right most point of the drain (and thus the less uniform the discretization is), see also the last figure of this section.

  4. "densification ver": the larger this number, the more the nodes cluster at the top (and thus the less uniform the discretization is), see also last figure of this section.

(Back to top)

discretization nodes and cells

Once a discretization is made with the chosen parameters by clicking the "make discretization" button, two new fields appear in the menu allowing the user to inspect the nodes and the cells, as shown in the following two figures:

drawing drawing

The example of these figures also show that the non-uniformity is such that both views are needed to inspect a typical discretization.

The following figure shows the result of a different choice of densification:

drawing

A bad choice of discretization may result in a poor approximation of the drain bed as illustrated by the following image:


drawing


The bed from is depicted in the graph with a high resolution (using the formulas in this section), but the solution will only see the discretization nodes, and by that will not capture the slope at the right.

(Back to top)

Calculation of the numerical solution

Once a discretization made, a numerical solution can be calculated. As the differential equations (see above) are essentially balance equations, the solving procedure tries iteratively to find head values in the nodes (HiH_i) such that the numerical mass balances for each node the numerical mass balance error is minimized.


drawing

The fluxes for the numerical balances are calculated in the numerical cells. The figure above shows such a typical cell (n1n2n3n4n_1-n_2-n_3-n_4) in which approximations of the fluxes are to be calculated, based on the heads (H1,H2,H3,H4H_1,H_2,H_3,H_4) at the four corners. This is done by creating the intersection point of the diagonals nmn_m and assigning to it the mean value ((H1+H2+H3+H3)/4(H_1+H_2+H_3+H_3)/4) to it.
In each of the four resulting triangles the heads can be interpolated linearly, head gradients and from this fluxes can be calculated. Combining these values for fluxes Qninj    i,j=1,4Q_{n_i\rightarrow n_j}\;\; i,j=1,\dots 4 can be calculated.

Once the fluxes are calculated, balances for each node can be made by considering the four cells of which this node is a corner, as in the figure below:


drawing

The balance for the central node CC can now be written as:
QNC+QNEC+QEC+QSEC+QSC+QSWC+QWC+QNWC=0Q_{N \rightarrow C} + Q_{NE \rightarrow C} + Q_{E \rightarrow C} + Q_{SE \rightarrow C} + Q_{S \rightarrow C} + Q_{SW \rightarrow C} + Q_{W \rightarrow C} + Q_{NW \rightarrow C} = 0
If the node is on the border of the domain, external fluxes can be added.

The node inspector of the solution analysis allows the user to inspect the numerical values of these fluxes.

A typical step in the iterative solution consists of:

A result of this last adjustment is seen in the following figure:

drawing

(Back to top)

Analyzing the solution

Solving and solution menu

If a discretization is made, one can calculate a numerical solution. To do this, open the solution-menu and hit the solve button:

drawing

Once a solution is calculated, new options appear in the solution-menu, as shown in the figure below:
drawing

(Back to top)

Water table

Checking the "show H table" box shows the water table, that is the surface for which H(x,z)=zH(x,z)=z in the groundwater and the water level in the drain, as shown in the figure below:

drawing

(Back to top)

H fills

Checking this box fills the flow domain with colors representing the values of the HH's.
A color bar with an axis (which can be dragged to any place in the window) gives the relation between values and colors.

drawing

Both the top (global) view and the second (local) view are filled. The same colors are used but the relation between colors and values are chosen in such a way that only the values visible in the local view are used. A new color bar adjusted to this new relation is added, as shown in the figure below:

drawing

(Back to top)

Contours

If the "fill cells with H" option in the menu is checked, an extra option "add contours" appears in the menu.
When checked contour lines corresponding to the values of the color bar are added to the plot as shown in the figure below:

drawing

(Back to top)

Flow direction

If the "draw flow direction" option in the solution menu is checked, arrows are drawn in the whole domain, both for global and local view, indicating the direction of flow. In this the flux size is neglected resulting in arrows all of the same length. If flux size is the point of interest, one should use the "draw fluxes" options (see section).

The following picture shows such an analysis:
drawing

As can be seen from absence of a thick line at the bottom, the example shows a case with a base layer. For x>60x>60 there is a net flow towards this base layer, for x<60x<60 there is a net flow from the base layer into the system.

The flow directions plotted are the directions of the numerical approximation of the true flow directions. As in all approximations, errors do occur. In the figure below, errors of the flow directions on the vertical below the talud of the drain are clearly visible:


drawing



Numerical errors get smaller by choosing a finer grid of nodes (see setion) and the convergence criterium (see section).

(Back to top)

Fluxes

Checking the "draw fluxes" option draw fluxes both in the top global and middle local view.
The user has to select a factor to map the flux vectors (who have a different physical dimension: length/time as the pure length dimensions of the axes) onto the plot. The length of the arrows is proportional to the flux. All arrow head have the same head size. When the "dont draw small arrows" box is checked (default), arrows whose length is invisible below the head are not drawn. When unchecked, fluxes are drawn in the total domain, even if they are invisible beneath the arrowhead.
Note that the same arrows are drawn in the top global and middle local view.

drawing

If one is only interested in the direction of the flux, and not its size, one should use the "draw flow directions" options as discucced in section.

Numerical errors as discussed on flow directions (see section) do also occur here,
and generally become more visible when large arrow factors are choosen.

(Back to top)

Node inspector

The option "add node inspector" allows the user to inspect the information assembled in a node.
When checked, a yellow circle with a black line around it appears in both views. It can be dragged to any place in the domain. By dragging the pointer circle in one view, the circle in the other view will follow. Of course, by dragging the pointer in the global view to the far right can make the pointer in the middle local view invisible.
When released after dragging, the pointer will automatically move to the nearest node.
A small report of all information connected to that node appears, as can be seen in the following figure:
drawing

That report can be dragged to any place in the window.
It contains the following information:

(Back to top)

Cell analysis

If the "add analysis" box is checked, a section on the left of the domain is analyzed as if it was a cell of a numerical model (as e.g. MODFLOW).The width of this cell can be chosen by the new menu item that appears. The right border of this cell is plotted as a yellow line.
The results of the analysis are shown in a small report (that can be dragged to any place in the window) as in the following figure:

drawing

This report contains the following information:

cfleak=HCellMeanHDrainLevelQTotdrain    WWidthCellc_{\textrm{fleak}} = \frac{H_\textrm{CellMean}-H_\textrm{DrainLevel}}{Q_\textrm{Totdrain}}\;\; W_\textrm{WidthCell}

This value is chosen such that if one calculates the flux to the drain with a constant head HCellMeanH_\textrm{CellMean}
and this resistance cfleakc_\mathrm{fleak} this would result in the modelled flux to the drain:
QTotdrain=HCellMeanHDrainLevelcfleak    WWidthCellQ_\textrm{Totdrain} = \frac{H_\textrm{CellMean}-H_\textrm{DrainLevel}}{c_{\textrm{fleak}}}\;\; W_\textrm{WidthCell}

Note that the value of c_fleak is only representative for the current parameter values.
If the relation between QdrainQ_\mathrm{drain} and HmeanHdrainH_\mathrm{mean}-H_\mathrm{drain} is very non-linear as in the figure above, the linear relation determined by only the current parameter values (red line) can be a poor approximation.
drawing

When the lower boundary is open the report is extended as in the following figure:

drawing

The extra value in this report is:

(Back to top)

Using the table

Active storage

The lowest part of the window shows a table-view in terms of numbers of the model under consideration. Both input numbers and result numbers are stored in this table. Any change in these numbers of the current model is immediately stored in the topline of the table, called the "active storage" as shown in the following figure:

drawing

The table is (usually) much wider than the browser window. One should use the horizontal scroll bar to view all the variables. Name of the variables are as introduced above, input variables have the same name as in the menus. Variables that do not receive a value in the current model (e.g. because there is no base layer or no cell analysis is done) get the value "NaN" (not a number).

(Back to top)

Wetted perimeter

There are two fields in the table that have not been introduced yet: the wetted perimeter.

The wetter perimeter is defined as the length of the drain perimeter over which there is interaction with the groundwater. This is different for a draining and infiltrating situation;

The following figure illustrates the draining situation:

drawing

The following figure illustrates an infiltrating situation:

drawing

This ground water wet perimeter is stored in the table under the name Gr Wet Per.
Fro comparison, also the open water or hydraulic wet perimeter --defined as the contact perimeter of the water in the drain-- is stored under the name Ow Wet Per_.

(Back to top)

Archiving in the tabel

Often one wants to compare to (or more) model runs.
For this the table can be used. By clicking on the active row, the user has the option to archive the active row. If the user accepts this, the now active row is copied in another part of the table called "archive". Changing the model parameters and rerun the model results in another active row. The results of this active row can then be compared to the archived one.

The following figure illustrates this:
drawing

In this example the first model used values kxx=kzz=2k_{xx}=k_{zz} =2. The results of this model were archived. Changing the values kxx=kzz=5k_{xx}=k_{zz} =5, rerunning the model an comparing the active row to the archived row shows that the maximum ground water level went down form 9.789 to 9.619.

(Back to top)

Activating archived row

Changing model parameters, running the model, archiving the results end in general in a table with several rows. One can of course compare the output numbers of the different results as stored in the table. But it may also be the case that one wants to review the plots corresponding to an archived row.
This can be done by clicking on an archived row. The user has then the option to accept that this archived row becomes active, including all the graphical plots.

The following figure illustrates this:

drawing

(Back to top)

Download table to CSV

After collecting a lot of runs in the table archive, one may wish to continue the analysis outside iGrOw.html, for instance in a spreadsheet. For this, one can hit the button "Download table to csv".
A csv file containing all the rows and columns of the table will then be saved on your computer.
Most browsers will save this (for security reasons) only in the local Downloads folder. Some browsers allow to change the name of that file, some give a default name.

The figure below shows such a download on a Chromium browser. The default name is then "data.csv" and it appears in lower part of the browser. This file can be downloaded and analyzed in any spreadsheet.

drawing

(Back to top)

Running cases/uploading from CSV

The manual discussed until now how models could be made interactively (through menus) and stored in tables. To run many cases, the interactive approach may be too cumbersome.

For that reasons, iGrOw allows also to define all these cases in a csv file and upload it in _iGrOw.
iGrOW will run all these cases and store them in a table.

For this procedure, one should first make a csv file with all input variables as column names and where the rows correspond to the cases.

Remember: column names are identical to those used in the menus:
"domain width (L/2)", "domain height", "drain width (B/2)", "drain bottom", "talud angle", "drain level", "recharge *1000" , "kxx", "kzz" ,"kxz", "c drain", "c seepage", "c base", "H base","# hor under drain", "#hor right of drain", "# ver", "densification hor", "densification ver", "Cell width"

To help the user in this, a spreadsheet template for a spreadsheet file by which such a csv file can be make and an example are provided in the distribution.

The following figure shows the "_iGrOwInputTemplate.xlsx":

drawing

The following figure shows the "_iGrOwInputExample.xlsx" made by this template:

drawing

the same file, but now scrolled to columns more to the right:

drawing

In this laste figure the use of "NaN" signal options one does not want to use:

Such a spreadsheet can be save as a csv file and uploaded into iGrOw as in the following illustration:

drawing

(Back to top)

Non-menu settings

The sections above discussed values of variables that can be interactively set through the menu options.

The “iGrOw.html” uses some other values that can be changed if wanted. The are collected in a javascript file (which can be opened and edited by any editor) called “iGrOwdefaultsettings.js” that can be found the “script folder”. The following image shows this file as provided in the zip-version:

The first three objects provide the default values by which “iGrOw.html” opens. The fourth collects numbers that are used in the solution procedure:

Any of these numbers can be changed. If an altered file is saved in the script folder, it will be used the next time the “iGrOw.html” is opened in a browser.

(Back to top)