.TH r.sim.water 1grass "" "GRASS 7.8.5" "GRASS GIS User's Manual"
.SH NAME
\fI\fBr.sim.water\fR\fR  \- Overland flow hydrologic simulation using path sampling method (SIMWE).
.SH KEYWORDS
raster, hydrology, soil, flow, overland flow, model
.SH SYNOPSIS
\fBr.sim.water\fR
.br
\fBr.sim.water \-\-help\fR
.br
\fBr.sim.water\fR [\-\fBts\fR] \fBelevation\fR=\fIname\fR \fBdx\fR=\fIname\fR \fBdy\fR=\fIname\fR  [\fBrain\fR=\fIname\fR]   [\fBrain_value\fR=\fIfloat\fR]   [\fBinfil\fR=\fIname\fR]   [\fBinfil_value\fR=\fIfloat\fR]   [\fBman\fR=\fIname\fR]   [\fBman_value\fR=\fIfloat\fR]   [\fBflow_control\fR=\fIname\fR]   [\fBobservation\fR=\fIname\fR]   [\fBdepth\fR=\fIname\fR]   [\fBdischarge\fR=\fIname\fR]   [\fBerror\fR=\fIname\fR]   [\fBwalkers_output\fR=\fIname\fR]   [\fBlogfile\fR=\fIname\fR]   [\fBnwalkers\fR=\fIinteger\fR]   [\fBniterations\fR=\fIinteger\fR]   [\fBoutput_step\fR=\fIinteger\fR]   [\fBdiffusion_coeff\fR=\fIfloat\fR]   [\fBhmax\fR=\fIfloat\fR]   [\fBhalpha\fR=\fIfloat\fR]   [\fBhbeta\fR=\fIfloat\fR]   [\fBrandom_seed\fR=\fIinteger\fR]   [\fBnprocs\fR=\fIinteger\fR]   [\-\-\fBoverwrite\fR]  [\-\-\fBhelp\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR]  [\-\-\fBui\fR]
.SS Flags:
.IP "\fB\-t\fR" 4m
.br
Time\-series output
.IP "\fB\-s\fR" 4m
.br
Generate random seed
.br
Automatically generates random seed for random number generator (use when you don\(cqt want to provide the seed option)
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-help\fR" 4m
.br
Print usage summary
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.IP "\fB\-\-ui\fR" 4m
.br
Force launching GUI dialog
.SS Parameters:
.IP "\fBelevation\fR=\fIname\fR \fB[required]\fR" 4m
.br
Name of input elevation raster map
.IP "\fBdx\fR=\fIname\fR \fB[required]\fR" 4m
.br
Name of x\-derivatives raster map [m/m]
.IP "\fBdy\fR=\fIname\fR \fB[required]\fR" 4m
.br
Name of y\-derivatives raster map [m/m]
.IP "\fBrain\fR=\fIname\fR" 4m
.br
Name of rainfall excess rate (rain\-infilt) raster map [mm/hr]
.IP "\fBrain_value\fR=\fIfloat\fR" 4m
.br
Rainfall excess rate unique value [mm/hr]
.br
Default: \fI50\fR
.IP "\fBinfil\fR=\fIname\fR" 4m
.br
Name of runoff infiltration rate raster map [mm/hr]
.IP "\fBinfil_value\fR=\fIfloat\fR" 4m
.br
Runoff infiltration rate unique value [mm/hr]
.br
Default: \fI0.0\fR
.IP "\fBman\fR=\fIname\fR" 4m
.br
Name of Manning\(cqs n raster map
.IP "\fBman_value\fR=\fIfloat\fR" 4m
.br
Manning\(cqs n unique value
.br
Default: \fI0.1\fR
.IP "\fBflow_control\fR=\fIname\fR" 4m
.br
Name of flow controls raster map (permeability ratio 0\-1)
.IP "\fBobservation\fR=\fIname\fR" 4m
.br
Name of sampling locations vector points map
.br
Or data source for direct OGR access
.IP "\fBdepth\fR=\fIname\fR" 4m
.br
Name for output water depth raster map [m]
.IP "\fBdischarge\fR=\fIname\fR" 4m
.br
Name for output water discharge raster map [m3/s]
.IP "\fBerror\fR=\fIname\fR" 4m
.br
Name for output simulation error raster map [m]
.IP "\fBwalkers_output\fR=\fIname\fR" 4m
.br
Base name of the output walkers vector points map
.br
Name for output vector map
.IP "\fBlogfile\fR=\fIname\fR" 4m
.br
Name for sampling points output text file. For each observation vector point the time series of sediment transport is stored.
.IP "\fBnwalkers\fR=\fIinteger\fR" 4m
.br
Number of walkers, default is twice the number of cells
.IP "\fBniterations\fR=\fIinteger\fR" 4m
.br
Time used for iterations [minutes]
.br
Default: \fI10\fR
.IP "\fBoutput_step\fR=\fIinteger\fR" 4m
.br
Time interval for creating output maps [minutes]
.br
Default: \fI2\fR
.IP "\fBdiffusion_coeff\fR=\fIfloat\fR" 4m
.br
Water diffusion constant
.br
Default: \fI0.8\fR
.IP "\fBhmax\fR=\fIfloat\fR" 4m
.br
Threshold water depth [m]
.br
Diffusion increases after this water depth is reached
.br
Default: \fI0.3\fR
.IP "\fBhalpha\fR=\fIfloat\fR" 4m
.br
Diffusion increase constant
.br
Default: \fI4.0\fR
.IP "\fBhbeta\fR=\fIfloat\fR" 4m
.br
Weighting factor for water flow velocity vector
.br
Default: \fI0.5\fR
.IP "\fBrandom_seed\fR=\fIinteger\fR" 4m
.br
Seed for random number generator
.br
The same seed can be used to obtain same results or random seed can be generated by other means.
.IP "\fBnprocs\fR=\fIinteger\fR" 4m
.br
Number of threads which will be used for parallel compute
.br
Default: \fI1\fR
.SH DESCRIPTION
\fIr.sim.water\fR 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\(cqs 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 (\fBelevation\fR raster map), flow gradient vector given by
first\-order partial derivatives of elevation field (\fBdx\fR and \fBdy\fR
raster maps), rainfall excess rate (\fBrain\fR raster map or \fBrain_value\fR single
value) and a surface roughness coefficient given by Manning\(cqs n
(\fBman\fR raster map or \fBman_value\fR single value). Partial
derivatives raster maps can be computed along with interpolation of a DEM using
the \-d option in \fIv.surf.rst\fR module. If elevation raster
map is already provided, partial derivatives can be computed using
\fIr.slope.aspect\fR 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.
.PP
.br
\fI
Figure: Simulated water flow in a rural area
showing the areas with highest water depth
highlighting streams, pooling, and wet areas
during a rainfall event.
\fR
.PP
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
\fBinfil\fR or a single value \fBinfil_value\fR 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 controlled 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 \fBflow_control\fR that defines the probability of particles to pass
through the structure (the values will be 0\-1).
.PP
Output includes a water depth raster map \fBdepth\fR in [m], and a water discharge
raster map \fBdischarge\fR in [m3/s]. Error of the numerical solution can be analyzed using
the \fBerror\fR raster map (the resulting water depth is an average, and err is its RMSE).
The output vector points map \fBoutput_walkers\fR 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 \fBnwalkers\fR.
Duration of simulation is controlled by the \fBniterations\fR 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 \fB\-t\fR and \fBoutput_step\fR 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.
.PP
Overland flow is routed based on partial derivatives of elevation
field or other landscape features influencing water flow. Simulation
equations include a diffusion term (\fBdiffusion_coeff\fR parameter) which enables
water flow to overcome elevation depressions or obstacles when water depth exceeds
a threshold water depth value (\fBhmax)\fR, given in [m]. When it is reached,
diffusion term increases as given by \fBhalpha\fR and advection term
(direction of flow) is given as \(dqprevailing\(dq direction of flow computed
as average of flow directions from the previous \fBhbeta\fR number of grid cells.
.SH 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\(cqs 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\(cqs 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\(cqs coefficient
(e.g., due to a road, or other anthropogenic changes in elevations or cover).
.PP
\fBGreen\(cqs function stochastic method of solution.\fR
.br
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).
.PP
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.
.SH EXAMPLE
Using the North Carolina full sample dataset:
.br
.nf
\fC
# set computational region
g.region raster=elev_lid792_1m \-p
# compute dx, dy
r.slope.aspect elevation=elev_lid792_1m dx=elev_lid792_dx dy=elev_lid792_dy
# simulate (this may take a minute or two)
r.sim.water elevation=elev_lid792_1m dx=elev_lid792_dx dy=elev_lid792_dy depth=water_depth disch=water_discharge nwalk=10000 rain_value=100 niter=5
\fR
.fi
Now, let\(cqs visualize the result using rendering to a file
(note the further management of computational region and
usage of d.mon module
which are not needed when working in GUI):
.br
.nf
\fC
# increase the computational region by 350 meters
g.region e=e+350
# initiate the rendering
d.mon start=cairo output=r_sim_water_water_depth.png
# render raster, legend, etc.
d.rast map=water_depth_1m
d.legend raster=water_depth_1m title=\(dqWater depth [m]\(dq label_step=0.10 font=sans at=20,80,70,75
d.barscale at=67,10 length=250 segment=5 font=sans
d.northarrow at=90,25
# finish the rendering
d.mon stop=cairo
\fR
.fi
.PP
.br
\fI
Figure: Simulated water depth map in the rural area of
the North Carolina sample dataset.
\fR
.SH ERROR MESSAGES
If the module fails with
.br
.nf
\fC
ERROR: nwalk (7000001) > maxw (7000000)!
\fR
.fi
then a lower \fBnwalkers\fR parameter value has to be selected.
.SH REFERENCES
.RS 4n
.IP \(bu 4n
Mitasova, H., Thaxton, C., Hofierka, J., McLaughlin, R., Moore, A., Mitas L., 2004,
Path sampling method for modeling overland water flow, sediment transport
and short term terrain evolution in Open Source GIS.
In: C.T. Miller, M.W. Farthing, V.G. Gray, G.F. Pinder eds.,
Proceedings of the XVth International Conference on Computational Methods in Water
Resources (CMWR XV), June 13\-17 2004, Chapel Hill, NC, USA, Elsevier, pp. 1479\-1490.
.IP \(bu 4n
Mitasova H, Mitas, L., 2000,
Modeling spatial
processes in multiscale framework: exploring duality between particles and fields,
plenary talk at GIScience2000 conference, Savannah, GA.
.IP \(bu 4n
Mitas, L., and Mitasova, H., 1998, Distributed soil erosion simulation
for effective erosion prevention. Water Resources Research, 34(3), 505\-516.
.IP \(bu 4n
Mitasova, H., Mitas, L., 2001,
Multiscale soil erosion simulations for land use management,
In: Landscape erosion and landscape evolution modeling, Harmon R. and Doe W. eds.,
Kluwer Academic/Plenum Publishers, pp. 321\-347.
.IP \(bu 4n
Hofierka, J, Mitasova, H., Mitas, L., 2002. GRASS and modeling landscape processes
using duality between particles and fields. Proceedings of the Open source GIS \-
GRASS users conference 2002 \- Trento, Italy, 11\-13 September 2002.
PDF
.IP \(bu 4n
Hofierka, J., Knutova, M., 2015,
Simulating aspects of a flash flood using the Monte Carlo method and
GRASS GIS: a case study of the Malá Svinka Basin (Slovakia),
Open Geosciences. Volume 7, Issue 1, ISSN (Online) 2391\-5447, DOI:
10.1515/geo\-2015\-0013,
April 2015
.IP \(bu 4n
Neteler, M. and Mitasova, H., 2008,
Open Source GIS: A GRASS GIS Approach. Third Edition.
The International Series in Engineering and Computer Science: Volume 773. Springer New York Inc, p. 406.
.RE
.SH SEE ALSO
\fI
v.surf.rst,
r.slope.aspect,
r.sim.sediment
\fR
.SH AUTHORS
Helena Mitasova, Lubos Mitas
.br
North Carolina State University
.br
\fIhmitaso@unity.ncsu.edu\fR
.PP
Jaroslav Hofierka
.br
GeoModel, s.r.o. Bratislava, Slovakia
.br
\fIhofierka@geomodel.sk\fR
.PP
Chris Thaxton
.br
North Carolina State University
.br
\fIcsthaxto@unity.ncsu.edu\fR
.SH SOURCE CODE
.PP
Available at: r.sim.water source code (history)
.PP
Main index |
Raster index |
Topics index |
Keywords index |
Graphical index |
Full index
.PP
© 2003\-2020
GRASS Development Team,
GRASS GIS 7.8.5 Reference Manual