Provided by: grass-doc_7.4.0-1_all bug

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   [-ts]   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]     [random_seed=integer]     [nprocs=integer]     [--overwrite]    [--help]
       [--verbose]  [--quiet]  [--ui]

   Flags:
       -t
           Time-series output

       -s
           Generate random seed
           Automatically  generates  random  seed for random number generator (use when you don’t
           want to provide the seed option)

       --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

       random_seed=integer
           Seed for random number generator
           The  same  seed  can be used to obtain same results or random seed can be generated by
           other means.

       nprocs=integer
           Number of threads which will be used for parallel compute
           Default: 1

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 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  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  controlled 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

       Figure: 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.

REFERENCES

           •   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.

           •   Mitasova H, Mitas, L., 2000, Modeling spatial processes in  multiscale  framework:
               exploring  duality  between  particles  and  fields, plenary talk at GIScience2000
               conference, Savannah, GA.

           •   Mitas, L., and  Mitasova,  H.,  1998,  Distributed  soil  erosion  simulation  for
               effective erosion prevention. Water Resources Research, 34(3), 505-516.

           •   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.

           •   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

           •   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

           •   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.

SEE ALSO

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

AUTHORS

       Helena Mitasova, Lubos Mitas
       North Carolina State University
       hmitaso@unity.ncsu.edu

       Jaroslav Hofierka
       GeoModel, s.r.o. Bratislava, Slovakia
       hofierka@geomodel.sk

       Chris Thaxton
       North Carolina State University
       csthaxto@unity.ncsu.edu

       Last changed: $Date: 2016-09-20 11:18:44 +0200 (Tue, 20 Sep 2016) $

SOURCE CODE

       Available at: r.sim.water source code (history)

       Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2018 GRASS Development Team, GRASS GIS 7.4.0 Reference Manual