1r.sim.water(1)              GRASS GIS User's Manual             r.sim.water(1)
2
3
4

NAME

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

KEYWORDS

10       raster, hydrology, soil, flow, overland flow, model
11

SYNOPSIS

13       r.sim.water
14       r.sim.water --help
15       r.sim.water   [-ts]   elevation=name   dx=name   dy=name    [rain=name]
16       [rain_value=float]    [infil=name]    [infil_value=float]    [man=name]
17       [man_value=float]        [flow_control=name]         [observation=name]
18       [depth=name]    [discharge=name]   [error=name]   [walkers_output=name]
19       [logfile=name]    [nwalkers=integer]    [niterations=integer]     [out‐
20       put_step=integer]     [diffusion_coeff=float]     [hmax=float]    [hal‐
21       pha=float]   [hbeta=float]    [random_seed=integer]    [nprocs=integer]
22       [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]
23
24   Flags:
25       -t
26           Time-series output
27
28       -s
29           Generate random seed
30           Automatically  generates  random  seed  for random number generator
31           (use when you don’t want to provide the seed option)
32
33       --overwrite
34           Allow output files to overwrite existing files
35
36       --help
37           Print usage summary
38
39       --verbose
40           Verbose module output
41
42       --quiet
43           Quiet module output
44
45       --ui
46           Force launching GUI dialog
47
48   Parameters:
49       elevation=name [required]
50           Name of input elevation raster map
51
52       dx=name [required]
53           Name of x-derivatives raster map [m/m]
54
55       dy=name [required]
56           Name of y-derivatives raster map [m/m]
57
58       rain=name
59           Name of rainfall excess rate (rain-infilt) raster map [mm/hr]
60
61       rain_value=float
62           Rainfall excess rate unique value [mm/hr]
63           Default: 50
64
65       infil=name
66           Name of runoff infiltration rate raster map [mm/hr]
67
68       infil_value=float
69           Runoff infiltration rate unique value [mm/hr]
70           Default: 0.0
71
72       man=name
73           Name of Manning’s n raster map
74
75       man_value=float
76           Manning’s n unique value
77           Default: 0.1
78
79       flow_control=name
80           Name of flow controls raster map (permeability ratio 0-1)
81
82       observation=name
83           Name of sampling locations vector points map
84           Or data source for direct OGR access
85
86       depth=name
87           Name for output water depth raster map [m]
88
89       discharge=name
90           Name for output water discharge raster map [m3/s]
91
92       error=name
93           Name for output simulation error raster map [m]
94
95       walkers_output=name
96           Base name of the output walkers vector points map
97           Name for output vector map
98
99       logfile=name
100           Name for sampling points output text  file.  For  each  observation
101           vector point the time series of sediment transport is stored.
102
103       nwalkers=integer
104           Number of walkers, default is twice the number of cells
105
106       niterations=integer
107           Time used for iterations [minutes]
108           Default: 10
109
110       output_step=integer
111           Time interval for creating output maps [minutes]
112           Default: 2
113
114       diffusion_coeff=float
115           Water diffusion constant
116           Default: 0.8
117
118       hmax=float
119           Threshold water depth [m]
120           Diffusion increases after this water depth is reached
121           Default: 0.3
122
123       halpha=float
124           Diffusion increase constant
125           Default: 4.0
126
127       hbeta=float
128           Weighting factor for water flow velocity vector
129           Default: 0.5
130
131       random_seed=integer
132           Seed for random number generator
133           The same seed can be used to obtain same results or random seed can
134           be generated by other means.
135
136       nprocs=integer
137           Number of threads which will be used for parallel compute
138           Default: 1
139

DESCRIPTION

141       r.sim.water is a landscape scale  simulation  model  of  overland  flow
142       designed  for  spatially  variable  terrain,  soil,  cover and rainfall
143       excess conditions. A 2D shallow water flow is described by the  bivari‐
144       ate  form of Saint Venant equations. The numerical solution is based on
145       the concept of duality between the field and particle representation of
146       the  modeled  quantity.  Green’s  function  Monte Carlo method, used to
147       solve the equation, provides robustness necessary for  spatially  vari‐
148       able conditions and high resolutions (Mitas and Mitasova 1998). The key
149       inputs of the model include elevation (elevation raster map), flow gra‐
150       dient  vector  given  by  first-order  partial derivatives of elevation
151       field (dx and dy raster maps), rainfall excess rate (rain raster map or
152       rain_value  single  value) and a surface roughness coefficient given by
153       Manning’s n (man raster map or man_value single value). Partial deriva‐
154       tives  raster  maps  can  be computed along with interpolation of a DEM
155       using the -d option in v.surf.rst module. If elevation  raster  map  is
156       already   provided,   partial   derivatives   can   be  computed  using
157       r.slope.aspect module. Partial derivatives are used  to  determine  the
158       direction and magnitude of water flow velocity. To include a predefined
159       direction of flow, map algebra can be used to  replace  terrain-derived
160       partial  derivatives  with  pre-defined partial derivatives in selected
161       grid cells such as man-made channels, ditches  or  culverts.  Equations
162       (2)  and  (3) from this report can be used to compute partial derivates
163       of the predefined flow using its direction given by aspect and slope.
164
165        Figure: Simulated water flow in a rural area showing  the  areas  with
166       highest water depth highlighting streams, pooling, and wet areas during
167       a rainfall event.
168
169       The module automatically converts horizontal  distances  from  feet  to
170       metric system using database/projection information. Rainfall excess is
171       defined as rainfall intensity - infiltration rate and  should  be  pro‐
172       vided  in  [mm/hr].   Rainfall  intensities  are usually available from
173       meteorological stations.  Infiltration rate depends on soil  properties
174       and  land  cover.  It varies in space and time.  For saturated soil and
175       steady-state water flow it can be estimated using  saturated  hydraulic
176       conductivity  rates based on field measurements or using reference val‐
177       ues which can be found in literature.  Optionally, user can provide  an
178       overland flow infiltration rate map infil or a single value infil_value
179       in [mm/hr] that control the rate of infiltration for the already  flow‐
180       ing water, effectively reducing the flow depth and discharge.  Overland
181       flow can be further controlled by permeable check dams or similar  type
182       of structures, the user can provide a map of these structures and their
183       permeability ratio in the map flow_control that defines the probability
184       of particles to pass through the structure (the values will be 0-1).
185
186       Output includes a water depth raster map depth in [m], and a water dis‐
187       charge raster map discharge in [m3/s]. Error of the numerical  solution
188       can  be  analyzed using the error raster map (the resulting water depth
189       is an average, and err is its RMSE).  The output vector points map out‐
190       put_walkers  can  be used to analyze and visualize spatial distribution
191       of walkers at different simulation times (note that the resulting water
192       depth is based on the density of these walkers).  The spatial distribu‐
193       tion of numerical error associated with path sampling solution  can  be
194       analysed  using the output error raster file [m]. This error is a func‐
195       tion of the number of particles used  in  the  simulation  and  can  be
196       reduced  by  increasing the number of walkers given by parameter nwalk‐
197       ers.  Duration of simulation is controlled by the  niterations  parame‐
198       ter.  The  default  value  is 10 minutes, reaching the steady-state may
199       require much longer time, depending on the  time  step,  complexity  of
200       terrain,  land  cover and size of the area.  Output walker, water depth
201       and discharge maps can be saved during simulation using the time series
202       flag -t and output_step parameter defining the time step in minutes for
203       writing output files.  Files are saved with a suffix representing  time
204       since  the  start of simulation in minutes (e.g. wdepth.05, wdepth.10).
205       Monitoring of water depth at specific points is supported. A vector map
206       with  observation  points and a path to a logfile must be provided. For
207       each point in the vector map which  is  located  in  the  computational
208       region  the  water  depth  is logged each time step in the logfile. The
209       logfile is organized as a table. A single header identifies  the  cate‐
210       gory  number  of  the  logged  vector points.  In case of invalid water
211       depth data the value -1 is used.
212
213       Overland flow is routed based on partial derivatives of elevation field
214       or  other  landscape  features influencing water flow. Simulation equa‐
215       tions  include  a  diffusion  term  (diffusion_coeff  parameter)  which
216       enables  water flow to overcome elevation depressions or obstacles when
217       water depth exceeds a threshold water depth value (hmax), given in [m].
218       When  it  is  reached,  diffusion term increases as given by halpha and
219       advection term (direction of flow) is given as  "prevailing"  direction
220       of  flow computed as average of flow directions from the previous hbeta
221       number of grid cells.
222

NOTES

224       A 2D shallow water flow is described by the  bivariate  form  of  Saint
225       Venant  equations  (e.g., Julien et al., 1995). The continuity of water
226       flow relation is coupled with the momentum  conservation  equation  and
227       for a shallow water overland flow, the hydraulic radius is approximated
228       by the normal flow depth. The system of equations is closed  using  the
229       Manning’s  relation.  Model assumes that the flow is close to the kine‐
230       matic wave approximation, but  we  include  a  diffusion-like  term  to
231       incorporate the impact of diffusive wave effects. Such an incorporation
232       of diffusion in the water flow simulation is not new and a similar term
233       has  been  obtained in derivations of diffusion-advection equations for
234       overland flow, e.g., by Lettenmeier and Wood, (1992). In our reformula‐
235       tion,  we simplify the diffusion coefficient to a constant and we use a
236       modified diffusion term.  The diffusion constant which we have used  is
237       rather  small  (approximately  one  order of magnitude smaller than the
238       reciprocal Manning’s coefficient) and therefore the resulting  flow  is
239       close to the kinematic regime. However, the diffusion term improves the
240       kinematic solution, by overcoming small shallow pits common in  digital
241       elevation models (DEM) and by smoothing out the flow over slope discon‐
242       tinuities or abrupt changes in Manning’s coefficient (e.g.,  due  to  a
243       road, or other anthropogenic changes in elevations or cover).
244
245       Green’s function stochastic method of solution.
246       The  Saint  Venant  equations  are solved by a stochastic method called
247       Monte Carlo (very similar to Monte Carlo methods in computational fluid
248       dynamics  or  to  quantum Monte Carlo approaches for solving the Schro‐
249       dinger equation (Schmidt and Ceperley,  1992,  Hammond  et  al.,  1994;
250       Mitas,  1996)). It is assumed that these equations are a representation
251       of  stochastic  processes   with   diffusion   and   drift   components
252       (Fokker-Planck equations).
253
254       The  Monte  Carlo  technique  has  several  unique advantages which are
255       becoming even more important due to new developments in computer  tech‐
256       nology.   Perhaps one of the most significant Monte Carlo properties is
257       robustness which enables us to solve the equations for  complex  cases,
258       such  as  discontinuities in the coefficients of differential operators
259       (in our case, abrupt slope or cover changes, etc).  Also,  rough  solu‐
260       tions  can  be  estimated  rather quickly, which allows us to carry out
261       preliminary quantitative studies  or  to  rapidly  extract  qualitative
262       trends by parameter scans. In addition, the stochastic methods are tai‐
263       lored to the new generation of computers as  they  provide  scalability
264       from  a  single workstation to large parallel machines due to the inde‐
265       pendence of sampling points. Therefore, the methods are useful both for
266       everyday  exploratory work using a desktop computer and for large, cut‐
267       ting-edge applications using high performance computing.
268

EXAMPLE

270       Using the North Carolina full sample dataset:
271       # set computational region
272       g.region raster=elev_lid792_1m -p
273       # compute dx, dy
274       r.slope.aspect elevation=elev_lid792_1m dx=elev_lid792_dx dy=elev_lid792_dy
275       # simulate (this may take a minute or two)
276       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
277       Now, let’s visualize the result using rendering to  a  file  (note  the
278       further  management  of  computational region and usage of d.mon module
279       which are not needed when working in GUI):
280       # increase the computational region by 350 meters
281       g.region e=e+350
282       # initiate the rendering
283       d.mon start=cairo output=r_sim_water_water_depth.png
284       # render raster, legend, etc.
285       d.rast map=water_depth_1m
286       d.legend raster=water_depth_1m title="Water depth [m]" label_step=0.10 font=sans at=20,80,70,75
287       d.barscale at=67,10 length=250 segment=5 font=sans
288       d.northarrow at=90,25
289       # finish the rendering
290       d.mon stop=cairo
291
292        Figure: Simulated water depth map in the rural area of the North  Car‐
293       olina sample dataset.
294

ERROR MESSAGES

296       If the module fails with
297       ERROR: nwalk (7000001) > maxw (7000000)!
298       then a lower nwalkers parameter value has to be selected.
299

REFERENCES

301           ·   Mitasova, H., Thaxton, C., Hofierka, J., McLaughlin, R., Moore,
302               A., Mitas L., 2004, Path sampling method for modeling  overland
303               water flow, sediment transport and short term terrain evolution
304               in Open Source GIS.  In: C.T. Miller, M.W. Farthing, V.G. Gray,
305               G.F. Pinder eds., Proceedings of the XVth International Confer‐
306               ence on Computational Methods in  Water  Resources  (CMWR  XV),
307               June 13-17 2004, Chapel Hill, NC, USA, Elsevier, pp. 1479-1490.
308
309           ·   Mitasova H, Mitas, L., 2000, Modeling spatial processes in mul‐
310               tiscale framework:  exploring  duality  between  particles  and
311               fields, plenary talk at GIScience2000 conference, Savannah, GA.
312
313           ·   Mitas,  L.,  and  Mitasova,  H., 1998, Distributed soil erosion
314               simulation for effective erosion  prevention.  Water  Resources
315               Research, 34(3), 505-516.
316
317           ·   Mitasova,  H., Mitas, L., 2001, Multiscale soil erosion simula‐
318               tions for land use management, In: Landscape erosion and  land‐
319               scape  evolution  modeling,  Harmon  R. and Doe W. eds., Kluwer
320               Academic/Plenum Publishers, pp. 321-347.
321
322           ·   Hofierka, J, Mitasova, H., Mitas, L., 2002. GRASS and  modeling
323               landscape processes using duality between particles and fields.
324               Proceedings of the Open source GIS  -  GRASS  users  conference
325               2002 - Trento, Italy, 11-13 September 2002.  PDF
326
327           ·   Hofierka,  J., Knutova, M., 2015, Simulating aspects of a flash
328               flood using the Monte Carlo method and GRASS GIS: a case  study
329               of  the Malá Svinka Basin (Slovakia), Open Geosciences. Volume
330               7,    Issue    1,     ISSN     (Online)     2391-5447,     DOI:
331               10.1515/geo-2015-0013, April 2015
332
333           ·   Neteler,  M.  and  Mitasova, H., 2008, Open Source GIS: A GRASS
334               GIS Approach. Third Edition.  The International Series in Engi‐
335               neering  and  Computer  Science:  Volume 773. Springer New York
336               Inc, p. 406.
337

SEE ALSO

339        v.surf.rst, r.slope.aspect, r.sim.sediment
340

AUTHORS

342       Helena Mitasova, Lubos Mitas
343       North Carolina State University
344       hmitaso@unity.ncsu.edu
345
346       Jaroslav Hofierka
347       GeoModel, s.r.o. Bratislava, Slovakia
348       hofierka@geomodel.sk
349
350       Chris Thaxton
351       North Carolina State University
352       csthaxto@unity.ncsu.edu
353

SOURCE CODE

355       Available at: r.sim.water source code (history)
356
357       Main index | Raster index | Topics index | Keywords index  |  Graphical
358       index | Full index
359
360       © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
361
362
363
364GRASS 7.8.5                                                     r.sim.water(1)
Impressum