1r.sim.water(1) GRASS GIS User's Manual r.sim.water(1)
2
6 r.sim.water - Overland flow hydrologic simulation using path sampling
7 method (SIMWE).
8
10 raster, hydrology, soil, flow, overland flow, model, parallel
11
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 Flags:
25 -t
26 Time-series output
27 -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 --overwrite
34 Allow output files to overwrite existing files
35 --help
37 Print usage summary
38 --verbose
40 Verbose module output
41 --quiet
43 Quiet module output
44 --ui
46 Force launching GUI dialog
47 Parameters:
49 elevation=name [required]
50 Name of input elevation raster map
51 dx=name [required]
53 Name of x-derivatives raster map [m/m]
54 dy=name [required]
56 Name of y-derivatives raster map [m/m]
57 rain=name
59 Name of rainfall excess rate (rain-infilt) raster map [mm/hr]
60 rain_value=float
62 Rainfall excess rate unique value [mm/hr]
63 Default: 50
64 infil=name
66 Name of runoff infiltration rate raster map [mm/hr]
67 infil_value=float
69 Runoff infiltration rate unique value [mm/hr]
70 Default: 0.0
71 man=name
73 Name of Manning’s n raster map
74 man_value=float
76 Manning’s n unique value
77 Default: 0.1
78 flow_control=name
80 Name of flow controls raster map (permeability ratio 0-1)
81 observation=name
83 Name of sampling locations vector points map
84 Or data source for direct OGR access
85 depth=name
87 Name for output water depth raster map [m]
88 discharge=name
90 Name for output water discharge raster map [m3/s]
91 error=name
93 Name for output simulation error raster map [m]
94 walkers_output=name
96 Base name of the output walkers vector points map
97 Name for output vector map
98 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 nwalkers=integer
104 Number of walkers, default is twice the number of cells
105 niterations=integer
107 Time used for iterations [minutes]
108 Default: 10
109 output_step=integer
111 Time interval for creating output maps [minutes]
112 Default: 2
113 diffusion_coeff=float
115 Water diffusion constant
116 Default: 0.8
117 hmax=float
119 Threshold water depth [m]
120 Diffusion increases after this water depth is reached
121 Default: 0.3
122 halpha=float
124 Diffusion increase constant
125 Default: 4.0
126 hbeta=float
128 Weighting factor for water flow velocity vector
129 Default: 0.5
130 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 nprocs=integer
137 Number of threads which will be used for parallel compute
138 Default: 1
139
141 r.sim.water is a landscape scale simulation model of overland flow de‐
142 signed for spatially variable terrain, soil, cover and rainfall excess
143 conditions. A 2D shallow water flow is described by the bivariate form
144 of Saint Venant equations. The numerical solution is based on the con‐
145 cept of duality between the field and particle representation of the
146 modeled quantity. Green’s function Monte Carlo method, used to solve
147 the equation, provides robustness necessary for spatially variable con‐
148 ditions and high resolutions (Mitas and Mitasova 1998). The key inputs
149 of the model include elevation (elevation raster map), flow gradient
150 vector given by first-order partial derivatives of elevation field (dx
151 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 us‐
155 ing the -d option in v.surf.rst module. If elevation raster map is al‐
156 ready provided, partial derivatives can be computed using r.slope.as‐
157 pect module. Partial derivatives are used to determine the direction
158 and magnitude of water flow velocity. To include a predefined direction
159 of flow, map algebra can be used to replace terrain-derived partial de‐
160 rivatives with pre-defined partial derivatives in selected grid cells
161 such as man-made channels, ditches or culverts. Equations (2) and (3)
162 from this report can be used to compute partial derivates of the prede‐
163 fined flow using its direction given by aspect and slope.
164 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 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 me‐
173 teorological 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 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 re‐
196 duced by increasing the number of walkers given by parameter nwalkers.
197 Duration of simulation is controlled by the niterations parameter. The
198 default value is 10 minutes, reaching the steady-state may require much
199 longer time, depending on the time step, complexity of terrain, land
200 cover and size of the area. Output walker, water depth and discharge
201 maps can be saved during simulation using the time series flag -t and
202 output_step parameter defining the time step in minutes for writing
203 output files. Files are saved with a suffix representing time since
204 the start of simulation in minutes (e.g. wdepth.05, wdepth.10). Moni‐
205 toring 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 re‐
208 gion the water depth is logged each time step in the logfile. The log‐
209 file is organized as a table. A single header identifies the category
210 number of the logged vector points. In case of invalid water depth
211 data the value -1 is used.
212 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 en‐
216 ables 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 ad‐
219 vection term (direction of flow) is given as "prevailing" direction of
220 flow computed as average of flow directions from the previous hbeta
221 number of grid cells.
222
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 in‐
231 corporate 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 re‐
238 ciprocal 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 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 Schrodin‐
249 ger equation (Schmidt and Ceperley, 1992, Hammond et al., 1994; Mitas,
250 1996)). It is assumed that these equations are a representation of sto‐
251 chastic processes with diffusion and drift components (Fokker-Planck
252 equations).
253 The Monte Carlo technique has several unique advantages which are be‐
255 coming even more important due to new developments in computer technol‐
256 ogy. Perhaps one of the most significant Monte Carlo properties is ro‐
257 bustness 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
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 Figure: Simulated water depth map in the rural area of the North Car‐
293 olina sample dataset.
294
296 If the module fails with
297 ERROR: nwalk (7000001) > maxw (7000000)!
298 then a lower nwalkers parameter value has to be selected.
299
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 • 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 • Mitas, L., and Mitasova, H., 1998, Distributed soil erosion
314 simulation for effective erosion prevention. Water Resources
315 Research, 34(3), 505-516.
316 • 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 • 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 • 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 • 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
339 v.surf.rst, r.slope.aspect, r.sim.sediment
340
342 Helena Mitasova, Lubos Mitas
343 North Carolina State University
344 hmitaso@unity.ncsu.edu
345 Jaroslav Hofierka
347 GeoModel, s.r.o. Bratislava, Slovakia
348 hofierka@geomodel.sk
349 Chris Thaxton
351 North Carolina State University
352 csthaxto@unity.ncsu.edu
353
355 Available at: r.sim.water source code (history)
356 Accessed: Saturday Jan 21 21:15:12 2023
358 Main index | Raster index | Topics index | Keywords index | Graphical
360 index | Full index
361 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
363GRASS 8.2.1 r.sim.water(1)