This is the command r.sim.watergrass that can be run in the OnWorks free hosting provider using one of our multiple free online workstations such as Ubuntu Online, Fedora Online, Windows online emulator or MAC OS online emulator

**PROGRAM:**

**NAME**

**r.sim.water**- Overland flow hydrologic simulation using path sampling method (SIMWE).

**KEYWORDS**

raster, hydrology, soil, flow, overland flow, model

**SYNOPSIS**

**r.sim.water**

**r.sim.water**

**--help**

**r.sim.water**[-

**t**]

**elevation**=

__name__

**dx**=

__name__

**dy**=

__name__[

**rain**=

__name__] [

**rain_value**=

__float__]

[

**infil**=

__name__] [

**infil_value**=

__float__] [

**man**=

__name__] [

**man_value**=

__float__] [

**flow_control**=

__name__]

[

**observation**=

__name__] [

**depth**=

__name__] [

**discharge**=

__name__] [

**error**=

__name__]

[

**walkers_output**=

__name__] [

**logfile**=

__name__] [

**nwalkers**=

__integer__] [

**niterations**=

__integer__]

[

**output_step**=

__integer__] [

**diffusion_coeff**=

__float__] [

**hmax**=

__float__] [

**halpha**=

__float__]

[

**hbeta**=

__float__] [--

**overwrite**] [--

**help**] [--

**verbose**] [--

**quiet**] [--

**ui**]

**Flags:**

**-t**

Time-series output

**--overwrite**

Allow output files to overwrite existing files

**--help**

Print usage summary

**--verbose**

Verbose module output

**--quiet**

Quiet module output

**--ui**

Force launching GUI dialog

**Parameters:**

**elevation**=

__name__

**[required]**

Name of input elevation raster map

**dx**=

__name__

**[required]**

Name of x-derivatives raster map [m/m]

**dy**=

__name__

**[required]**

Name of y-derivatives raster map [m/m]

**rain**=

__name__

Name of rainfall excess rate (rain-infilt) raster map [mm/hr]

**rain_value**=

__float__

Rainfall excess rate unique value [mm/hr]

Default:

__50__

**infil**=

__name__

Name of runoff infiltration rate raster map [mm/hr]

**infil_value**=

__float__

Runoff infiltration rate unique value [mm/hr]

Default:

__0.0__

**man**=

__name__

Name of Manning’s n raster map

**man_value**=

__float__

Manning’s n unique value

Default:

__0.1__

**flow_control**=

__name__

Name of flow controls raster map (permeability ratio 0-1)

**observation**=

__name__

Name of sampling locations vector points map

Or data source for direct OGR access

**depth**=

__name__

Name for output water depth raster map [m]

**discharge**=

__name__

Name for output water discharge raster map [m3/s]

**error**=

__name__

Name for output simulation error raster map [m]

**walkers_output**=

__name__

Base name of the output walkers vector points map

Name for output vector map

**logfile**=

__name__

Name for sampling points output text file. For each observation vector point the time

series of sediment transport is stored.

**nwalkers**=

__integer__

Number of walkers, default is twice the number of cells

**niterations**=

__integer__

Time used for iterations [minutes]

Default:

__10__

**output_step**=

__integer__

Time interval for creating output maps [minutes]

Default:

__2__

**diffusion_coeff**=

__float__

Water diffusion constant

Default:

__0.8__

**hmax**=

__float__

Threshold water depth [m]

Diffusion increases after this water depth is reached

Default:

__0.3__

**halpha**=

__float__

Diffusion increase constant

Default:

__4.0__

**hbeta**=

__float__

Weighting factor for water flow velocity vector

Default:

__0.5__

**DESCRIPTION**

__r.sim.water__is a landscape scale simulation model of overland flow designed for spatially

variable terrain, soil, cover and rainfall excess conditions. A 2D shallow water flow is

described by the bivariate form of Saint Venant equations. The numerical solution is based

on the concept of duality between the field and particle representation of the modeled

quantity. Green’s function Monte Carlo method, used to solve the equation, provides

robustness necessary for spatially variable conditions and high resolutions (Mitas and

Mitasova 1998). The key inputs of the model include elevation (

__elevation__raster map), flow

gradient vector given by first-order partial derivatives of elevation field (

__dx__and

__dy__

raster maps), rainfall excess rate (

__rain__raster map or

__rain_value__single value) and a

surface roughness coefficient given by Manning’s n (

__man__raster map or

__man_value__single

value). Partial derivatives raster maps can be computed along with interpolation of a DEM

using the -d option in v.surf.rst module. If elevation raster map is already provided,

partial derivatives can be computed using r.slope.aspect module. Partial derivatives are

used to determine the direction and magnitude of water flow velocity. To include a

predefined direction of flow, map algebra can be used to replace terrain-derived partial

derivatives with pre-defined partial derivatives in selected grid cells such as man-made

channels, ditches or culverts. Equations (2) and (3) from this report can be used to

compute partial derivates of the predefined flow using its direction given by aspect and

slope.

The module automatically converts horizontal distances from feet to metric system using

database/projection information. Rainfall excess is defined as rainfall intensity -

infiltration rate and should be provided in [mm/hr]. Rainfall intensities are usually

available from meteorological stations. Infiltration rate depends on soil properties and

land cover. It varies in space and time. For saturated soil and steady-state water flow

it can be estimated using saturated hydraulic conductivity rates based on field

measurements or using reference values which can be found in literature. Optionally, user

can provide an overland flow infiltration rate map

__infil__or a single value

__infil_value__in

[mm/hr] that control the rate of infiltration for the already flowing water, effectively

reducing the flow depth and discharge. Overland flow can be further controled by

permeable check dams or similar type of structures, the user can provide a map of these

structures and their permeability ratio in the map

__flow_control__that defines the

probability of particles to pass through the structure (the values will be 0-1).

Output includes a water depth raster map

__depth__in [m], and a water discharge raster map

__discharge__in [m3/s]. Error of the numerical solution can be analyzed using the

__error__

raster map (the resulting water depth is an average, and err is its RMSE). The output

vector points map

__output_walkers__can be used to analyze and visualize spatial distribution

of walkers at different simulation times (note that the resulting water depth is based on

the density of these walkers). The spatial distribution of numerical error associated

with path sampling solution can be analysed using the output error raster file [m]. This

error is a function of the number of particles used in the simulation and can be reduced

by increasing the number of walkers given by parameter

__nwalkers__. Duration of simulation

is controled by the

__niterations__parameter. The default value is 10 minutes, reaching the

steady-state may require much longer time, depending on the time step, complexity of

terrain, land cover and size of the area. Output walker, water depth and discharge maps

can be saved during simulation using the time series flag

__-t__and

__output_step__parameter

defining the time step in minutes for writing output files. Files are saved with a suffix

representing time since the start of simulation in minutes (e.g. wdepth.05, wdepth.10).

Monitoring of water depth at specific points is supported. A vector map with observation

points and a path to a logfile must be provided. For each point in the vector map which is

located in the computational region the water depth is logged each time step in the

logfile. The logfile is organized as a table. A single header identifies the category

number of the logged vector points. In case of invalid water depth data the value -1 is

used.

Overland flow is routed based on partial derivatives of elevation field or other landscape

features influencing water flow. Simulation equations include a diffusion term

(

__diffusion_coeff__parameter) which enables water flow to overcome elevation depressions or

obstacles when water depth exceeds a threshold water depth value (

__hmax)__, given in [m].

When it is reached, diffusion term increases as given by

__halpha__and advection term

(direction of flow) is given as "prevailing" direction of flow computed as average of flow

directions from the previous

__hbeta__number of grid cells.

**NOTES**

A 2D shallow water flow is described by the bivariate form of Saint Venant equations

(e.g., Julien et al., 1995). The continuity of water flow relation is coupled with the

momentum conservation equation and for a shallow water overland flow, the hydraulic radius

is approximated by the normal flow depth. The system of equations is closed using the

Manning’s relation. Model assumes that the flow is close to the kinematic wave

approximation, but we include a diffusion-like term to incorporate the impact of diffusive

wave effects. Such an incorporation of diffusion in the water flow simulation is not new

and a similar term has been obtained in derivations of diffusion-advection equations for

overland flow, e.g., by Lettenmeier and Wood, (1992). In our reformulation, we simplify

the diffusion coefficient to a constant and we use a modified diffusion term. The

diffusion constant which we have used is rather small (approximately one order of

magnitude smaller than the reciprocal Manning’s coefficient) and therefore the resulting

flow is close to the kinematic regime. However, the diffusion term improves the kinematic

solution, by overcoming small shallow pits common in digital elevation models (DEM) and by

smoothing out the flow over slope discontinuities or abrupt changes in Manning’s

coefficient (e.g., due to a road, or other anthropogenic changes in elevations or cover).

**Green’s**

**function**

**stochastic**

**method**

**of**

**solution.**

The Saint Venant equations are solved by a stochastic method called Monte Carlo (very

similar to Monte Carlo methods in computational fluid dynamics or to quantum Monte Carlo

approaches for solving the Schrodinger equation (Schmidt and Ceperley, 1992, Hammond et

al., 1994; Mitas, 1996)). It is assumed that these equations are a representation of

stochastic processes with diffusion and drift components (Fokker-Planck equations).

The Monte Carlo technique has several unique advantages which are becoming even more

important due to new developments in computer technology. Perhaps one of the most

significant Monte Carlo properties is robustness which enables us to solve the equations

for complex cases, such as discontinuities in the coefficients of differential operators

(in our case, abrupt slope or cover changes, etc). Also, rough solutions can be estimated

rather quickly, which allows us to carry out preliminary quantitative studies or to

rapidly extract qualitative trends by parameter scans. In addition, the stochastic methods

are tailored to the new generation of computers as they provide scalability from a single

workstation to large parallel machines due to the independence of sampling points.

Therefore, the methods are useful both for everyday exploratory work using a desktop

computer and for large, cutting-edge applications using high performance computing.

**EXAMPLE**

Spearfish region:

g.region raster=elevation.10m -p

r.slope.aspect elevation=elevation.10m dx=elev_dx dy=elev_dy

# synthetic maps

r.mapcalc "rain = if(elevation.10m, 5.0, null())"

r.mapcalc "manning = if(elevation.10m, 0.05, null())"

r.mapcalc "infilt = if(elevation.10m, 0.0, null())"

# simulate

r.sim.water elevation=elevation.10m dx=elev_dx dy=elev_dy \

rain=rain man=manning infil=infilt \

nwalkers=5000000 depth=depth

__Water__

__depth__

__map__

__in__

__the__

__Spearfish__

__(SD)__

__area__

**ERROR** **MESSAGES**

If the module fails with

ERROR: nwalk (7000001) > maxw (7000000)!

then a lower

__nwalkers__parameter value has to be selected.

Use r.sim.watergrass online using onworks.net services