r.damflood

Estimate the area potentially inundated in case of dam break

r.damflood [-d] [method=string] [timestep=float] elev=string lake=string dambreak=string manning=string tstop=integer [u=string] [v=string] [deltat=integer] [opt_t=float [,float,...]] [h=string] [vel=string] [hmax=string] [vmax=string] [imax=string] [wavefront=string] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.damflood elev=string lake=string dambreak=string manning=string tstop=integer

grass.script.run_command("r.damflood", method="dambreak-without_hypotesis", timestep=0.01, elev, lake, dambreak, manning, tstop, u=None, v=None, deltat=None, opt_t=None, h=None, vel=None, hmax=None, vmax=None, imax=None, wavefront=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.damflood", elev="string", lake="string", dambreak="string", manning="string", tstop=integer)

Parameters

Command linePython (grass.script)

method=string
    Computational method for initial velocity estimation
    Allowed values: dambreak-without_hypotesis, uniform drop in of lake, small dam breach
    Default: dambreak-without_hypotesis
timestep=float
    Initial computational time step [s] - CFL condition
    Default: 0.01
elev=string [required]
    Name of elevation raster map (including lake bathymetry and dam)
lake=string [required]
    Name of water depth raster map
dambreak=string [required]
    Name of dam breach width raster map
manning=string [required]
    Name of Manning's roughness coefficient raster map
tstop=integer [required]
    Simulation time duration [s]
u=string
    Initial velocity along the east direction [m/s]
v=string
    Initial velocity along the north direction [m/s]
deltat=integer
    Time-lag for output generation [s]
opt_t=float [,float,...]
    Additional instants for output map generation [s]
h=string
    Prefix for water depth output raster maps
vel=string
    Prefix for water velocity output raster maps
hmax=string
    Name of output maximum water depth raster map; relative intensity [h*v] and time map are also generated
vmax=string
    Name of output maximum water velocity raster map; relative intensity [h*v] and time map are also generated
imax=string
    Name of output maximum intensity [h*v] raster map; relative time map are also generated
wavefront=string
    Name of output wave front time[s] raster map
-d
    Flow direction additional output (aspect visualization)
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

method : str, optional
    Computational method for initial velocity estimation
    Allowed values: dambreak-without_hypotesis, uniform drop in of lake, small dam breach
    Default: dambreak-without_hypotesis
timestep : float, optional
    Initial computational time step [s] - CFL condition
    Default: 0.01
elev : str, required
    Name of elevation raster map (including lake bathymetry and dam)
    Used as: input, raster
lake : str, required
    Name of water depth raster map
    Used as: input, raster
dambreak : str, required
    Name of dam breach width raster map
    Used as: input, raster
manning : str, required
    Name of Manning's roughness coefficient raster map
    Used as: input, raster
tstop : int, required
    Simulation time duration [s]
u : str, optional
    Initial velocity along the east direction [m/s]
    Used as: input, raster
v : str, optional
    Initial velocity along the north direction [m/s]
    Used as: input, raster
deltat : int, optional
    Time-lag for output generation [s]
opt_t : float | list[float] | str, optional
    Additional instants for output map generation [s]
h : str, optional
    Prefix for water depth output raster maps
    Used as: output, raster
vel : str, optional
    Prefix for water velocity output raster maps
    Used as: output, raster
hmax : str, optional
    Name of output maximum water depth raster map; relative intensity [h*v] and time map are also generated
    Used as: output, raster
vmax : str, optional
    Name of output maximum water velocity raster map; relative intensity [h*v] and time map are also generated
    Used as: output, raster
imax : str, optional
    Name of output maximum intensity [h*v] raster map; relative time map are also generated
    Used as: output, raster
wavefront : str, optional
    Name of output wave front time[s] raster map
    Used as: output, raster
flags : str, optional
    Allowed values: d
    d
        Flow direction additional output (aspect visualization)
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

r.damflood - The definition of flooding areas is of considerable importance for both the risk analysis and the emergency management. This command, in particular, is an embedded GRASS GIS hydrodynamic 2D model that allows to obtain flooding area due to a failure of a dam, given the geometry of the reservoir and of the downstream area, the initial conditions and the dam breach geometry.
The numerical model solves the conservative form of the shallow water equations (SWE) using a finite volume method (FVM); the intercell flux is computed by the "upwind method and the water-level gradient is evaluated by weighted average of both upwind and downwind gradient. Additional details of the specific numerical scheme adopted in the model are presented in references [1].
The command allows to generate raster time series, of water depth and flow velocity, with time resolution defined by user. Each time series is identified by a number of raster maps named with a common prefix as specified by the user and the time instant which it refers expressed in seconds from the dam failure, joined by the underscore character (e.g.; myvel_125, myvel_250, myvel_375, etc.).
Because this new module has been implemented with the aim to provide an instrument for risk assessment fully within a GIS environment, it should be able to provide intensity maps directly applicable in those analyses.In floods, intensity generally corresponds to the maximum flow depth, but in the particular case of flash floods, where velocities are normally high, it is recommended to use as intensity indicator the maximum between the water depth and the product of water velocity and water depth. For this reason, with this module, in addition to the water depth and velocity maps, the user can choose a variety of output raster maps: maximum water depth, maximum water velocity, and maximum intensity raster maps.
In case on high numerical stability problem, the user is warned, and the simulation is stopped.

Use

Requested input:
The required input are:
- a DTM including the lake bathimetry and the dam elevation over the ground [elev],
- a map with the initial condition easily obtained with r.lake command [lake],
- a dam breach width raster map [dambreak] which can be obtained using r.dam grass add-on script,
- a Manning's roughness coefficient raster map, easily obtained from a reclassification of a land use map (r.reclass) [manning],
- the simulation time length expressed in seconds [tstop].

Output map and additional output options:
First the user can set a specific time lag [deltat] expressed in seconds, that is used for the output map (depth and velocity) generation. and also an additional series of instants [opt_t],expressed in seconds from the beginning of the simulation), used to generate further water flow depth and velocity maps at desired precise times.
The user can choose between one of the following time series raster maps as output: - flow depth [h],
- flow velocity [vel],
- a raster map with maximum water depth [hmax], relative flooding intensity [i_hmax], that is the product of water depth and velocity, and the relative time of occurence[t_hmax],
- a raster map with maximum water velocity [vmax], relative flooding intensity [i_vmax], and the relative time of occurence[t_vmax],
- a raster map with maximum flooding intensity [imax] and the relative time of occurence[t_imax].
- a raster map with the time of arriving of the Wave-Front [wavefront]

where and the raster maps are coded as "prefix" + "_" + "elapsed seconds": e.g. mydepth_125.

Obviously at least one output map prefix must be specified.
The unit of measurements of output raster maps are expresssed using the International System (S.I.).

Options:
Using a specific flag, the user can obtain another raster map with flow directions that can be visualized using a specific display command (d.rast.arrow) of the GRASS GIS software.

Actually two different dam failure type are considered by the command: (i) full breach, (ii) partial breach.

In case of total istantaeous dam break (configuration i), the initial velocity is computed directly applying the SWE at the first time step; while in case of partial dam breach (configuration ii) the user can choose between don't use any hypothesis, like in the previous configuration, or evaluate the initial velocity using the overflow spillway equation:
V = 0.4 * sqrt(2 g h)
where V is the water flow velocity expressed in m/s, g is the gravitational acceleration expressed in m/s² and h is the water depth in correspondence of the dam breach expresssed in meters (m).
Optionally the user may modify the initial timestep used for the numerical solution of the SWE (default value = 0.01 s), nevertheless the timestep [], and choose a specific failure tipe corresponding to different computational method for the initial velocity estimation.

AUTHORS

Roberto Marzocchi (e-mail) and Massimiliano Cannata (e-mail). The GRASS tool was developed by Institute of earth science (IST), University of applied science of Italian Switzerland (SUPSI), Lugano - Division of geomatics web-page
Actually the debug is assured by:
- Gter srl (Genoa, Italy)
- IST -SUPSI (Lugano, Switzerland)
The numerical model, originally developed by the National Center for Computational Hydroscience and Engineering of the University of Mississippi, has been reformulated and modified by the authors introducing important new features to consider the numerical stability and the type of dam failure, and currently is written in ANSI C programming language within GRASS.

REFERENCES

[1] Cannata M. & Marzocchi R. (2012). Two-dimensional dam break flooding simulation: a GIS embedded approach. - Natural Hazards 61(3):1143-1159
[2] Pdf presentation of the work at the "X Meeting degli Utenti Italiani di GRASS - GFOSS" (It) web-page
[3] Pdf presentation of the work at the FOSS4G 2009 (En) - web-page
[4] Pdf presentation of the work at the Geoitalia 2011 conference (En)- document

Last changed: $27 februar 2013 09:40:00 CET $

SOURCE CODE

Available at: r.damflood source code (history)
Latest change: Friday Feb 21 23:33:10 2025 in commit 7c35290