Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

r.damflood: Update manual and migrate Italian to English #683

Open
wants to merge 26 commits into
base: grass8
Choose a base branch
from
Open
Changes from 1 commit
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
9ac2a06
Add english comments
echoix Jan 3, 2022
7eade51
Spelling fixes in r.damflood
echoix Jan 3, 2022
d80bfd3
r.damflood manual page revision
echoix Jan 3, 2022
c0e7574
r.damflood: Translation to English attempt in SWE
echoix Jan 4, 2022
b74a1b9
Merge branch 'OSGeo:grass8' into r.damflood-patch-1
echoix Jan 16, 2022
bde6fbf
Merge branch 'OSGeo:grass8' into r.damflood-patch-1
echoix Jan 16, 2022
7809e78
r.damflood: Improve manual and broken link
echoix Jan 22, 2022
283cc20
r.damflood: Translate comments to English
echoix Jan 22, 2022
af848a3
Merge branch 'r.damflood-patch-1' of https://github.com/echoix/grass-…
echoix Jan 22, 2022
dfefcbb
r.damflood: Continue translating SWE
echoix Jan 22, 2022
3ad438b
r.damflood: SWE keep original tab indentation
echoix Jan 22, 2022
11fea4c
r.damflood: End r.damflood.html with newline.
echoix Jan 22, 2022
f4e304d
Update src/raster/r.damflood/SWE.c
echoix Jan 26, 2022
575f2fc
r.damflood: Apply suggestions
echoix Jan 29, 2022
796b43c
Merge branch 'grass8' into r.damflood-patch-1
echoix Dec 30, 2023
e3ca1ef
Merge branch 'grass8' into r.damflood-patch-1
echoix Dec 30, 2023
60d3351
Merge branch 'grass8' into r.damflood-patch-1
echoix Dec 30, 2023
5bd8815
Merge branch 'grass8' into r.damflood-patch-1
echoix Dec 30, 2023
f0ebe9a
Merge branch 'grass8' into r.damflood-patch-1
echoix Dec 30, 2023
b596a54
Merge branch 'grass8' into r.damflood-patch-1
echoix Dec 30, 2023
a5fd00f
Add comments to function parameters in SWE.h
echoix Dec 30, 2023
c79c37b
Fix formatting in main.c
echoix Dec 30, 2023
d13187d
Fix formatting of comments in SWE.c
echoix Dec 30, 2023
76149f0
r.damflood: Fix typos and formatting of manual
echoix Dec 30, 2023
db2c0d8
Apply suggestions from code review
echoix Dec 31, 2023
24c42d6
Update main.c
echoix Dec 31, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
r.damflood manual page revision
  • Loading branch information
echoix committed Jan 4, 2022
commit d80bfd3c85337b9a426244abc6a283f4a12d390d
241 changes: 149 additions & 92 deletions src/raster/r.damflood/r.damflood.html
Original file line number Diff line number Diff line change
@@ -1,124 +1,156 @@
<h2>DESCRIPTION</h2>


<em><b>r.damflood</b></em> - 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.
<em><b>r.damflood</b></em> - The definition of flooding areas is of considerable
importance for both the risk analysis and the emergency management.
This module, in particular, is an embedded GRASS GIS hydrodynamic 2D model
that allows to obtain flooding areas 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.
<br>

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
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].<br>

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.).<br>

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

In case on high numerical stability problem, the user is warned, and the simulation is stopped.<br>
<br><br>
The module allows to generate raster time series, of water depth and
flow velocity, with time resolution defined by the 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.).<br>

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 an 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.<br>

In case of numerical stability problems, the user is warned, and the
simulation is stopped.<br>
Comment on lines +36 to +37
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had a hard time deciding if this was the correct interpretation, given that code is speaking of "Courant-Friedrich-Lewy stability condition" and seems specific to the numerical algorithm. I tried to learn more on this, but I'm still not quite sure. This sentence refers to (now) lines 889-895 of main.c, comments at (now) lines 84-94 of SWE.c, code and comments of lines 550-536 and 724-742 of SWE.c.

<br>


<em><b><!--font size = "5"-->Use</b></em><!--/font-->
<br>
<p>
<em><b>Requested input:</b></em> <br>
The required input are: <br>
- a DTM including the lake bathimetry and the dam elevation over the ground [elev], <br>
- a map with the initial condition easily obtained with <a href="https://grass.osgeo.org/grass-stable/manuals/r.lake.html">r.lake</a> command [lake], <br>
- a dam breach width raster map [dambreak] which can be obtained using <a href="r.dam.html">r.dam</a> grass add-on script, <br>
- a Manning's roughness coefficient raster map, easily obtained from a reclassification of a land use map
(<a href="https://grass.osgeo.org/grass-stable/manuals/r.reclass.html">r.reclass</a>) [manning],<br>
- the simulation time length expressed in <em>seconds</em> [tstop].<br><br>




<!-- ********************************************************************************************************************************* -->
<em><b>Output map and additional output options:</b></em> <br>
First the user can set a specific time lag [deltat] expressed in <em>seconds</em>, that is used for the output map (depth and velocity) generation.
and also an additional series of instants [opt_t],expressed in <em>seconds</em> from the beginning of the simulation), used to generate further water flow depth and velocity maps
at desired precise times.<br>

The user can choose between one of the following time series raster maps as output:
- flow depth [h],<br>
- flow velocity [vel],<br>

<!--Finally the user can be choose as additional output: <br> -->
- 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],<br>
- a raster map with maximum water velocity [vmax], relative flooding intensity [i_vmax], and the relative time of occurence[t_vmax],<br>
- a raster map with maximum flooding intensity [imax] and the relative time of occurence[t_imax].<br>
- a raster map with the time of arriving of the Wave-Front [wavefront]<br><br>
where and the raster maps are coded as "prefix" + "_" + "elapsed seconds": e.g. <em>mydepth_125</em>.<br><br>
<h3>USAGE</h3>
<h4>Required inputs</h4>
The required inputs are:
<ul>
<li>a DTM including the lake bathymetry and the dam elevation over
the ground [<b>elev</b>],</li>
<li>a map with the initial condition easily obtained with
<a href="https://grass.osgeo.org/grass-stable/manuals/r.lake.html">r.lake</a>
command [<b>lake</b>],</li>
<li>a dam breach width raster map [<b>dambreak</b>] which can be
obtained using <a href="r.dam.html">r.dam</a> grass add-on script,</li>
<li>a Manning's roughness coefficient raster map, easily obtained from a
reclassification of a land use map
(<a href="https://grass.osgeo.org/grass-stable/manuals/r.reclass.html">r.reclass</a>)
[<b>manning</b>],</li>
<li>the simulation time length expressed in <em>seconds</em>
[<b>tstop</b>].</li>
</ul>


<h4>Output map and additional output options</h4>
First the user can set a specific time lag [<b>deltat</b>] expressed in
<em>seconds</em>, that is used for the output map (depth and velocity)
generation.
It is also possible to generate the output maps, like water flow depth and
velocity maps, at some precise times. These additional series of instants
are set with the <b>opt_t</b> parameter, expressed in <em>seconds</em>
from the beginning of the simulation.

The user can choose between one of the following time series raster maps as
output:
<ul>
<li>flow depth [<b>h</b>],</li>
<li>flow velocity [<b>vel</b>],</li>
<!--Finally, the user can choose as additional output: <br> -->
<li>a raster map with maximum water depth [<b>hmax</b>],
relative flooding intensity [<b>i_hmax</b>],
that is the product of water depth and velocity,
and the relative time of occurrence [<b>t_hmax</b>],</li>
<li>a raster map with maximum water velocity [<b>vmax</b>],
relative flooding intensity [<b>i_vmax</b>],
and the relative time of occurrence [<b>t_vmax</b>],</li>
<li>a raster map with maximum flooding intensity [<b>imax</b>]
and the relative time of occurrence[<b>t_imax</b>],</li>
<li>a raster map with the time of arriving of the Wave-Front
[<b>wavefront</b>]</li>
</ul>
where and the raster maps are coded as "prefix" + "_" + "elapsed seconds":
e.g. <em>mydepth_125</em>.<br>
<br>

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

The unit of measurements of output raster maps are expressed using the
<em>International System</em> (<em>S.I.</em>).


<!-- ********************************************************************************************************************************* -->
<em><b>Options:</b></em> <br>
Using a specific flag, the user can obtain another raster map with flow directions that can be visualized using a specific display command
(<a href="https://grass.osgeo.org/grass-stable/manuals/d.rast.arrow.html">d.rast.arrow</a>) of the GRASS GIS software. <br>
<h4>Options</h4>
Using a specific flag, the user can obtain another raster map with flow
directions that can be visualized using a specific display command
(<a href="https://grass.osgeo.org/grass-stable/manuals/d.rast.arrow.html">d.rast.arrow</a>)
of the GRASS GIS software.<br>
<br>

Actually two different dam failure type are considered by the command: <em>(i)</em> full breach, <em>(ii)</em> partial breach.
Two different dam failure types are currently considered by the module:
<em>(i)</em> full breach, <em>(ii)</em> partial breach.
<br>
<img src="./dam_failure.png" height="350" alt="" >

<img src="./dam_failure.png" height="350" alt="Full breach. Partial breach.">
<br>

In case of total istantaeous dam break (configuration <em>i</em>), the initial velocity is computed directly applying the SWE at the first time step;
while in case of partial dam breach (configuration <em>ii</em>) the user can choose between don't use any hypothesis, like in the previous configuration,
In case of total instantaneous dam break (configuration <em>i</em>), the initial
velocity is computed directly applying the SWE at the first time step;
while in case of partial dam breach (configuration <em>ii</em>) 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: <br>

<em> V </em> = <em> 0.4 </em> <span class="radic"><sup><var> </var></sup>&#8730;<span style="text-decoration:overline" class="radicand"><var>(2 <em>g h)</em></var></span> <br>
<em> V </em> = <em> 0.4 </em> <span class="radic"><sup><var> </var>
</sup>&#8730;<span style="text-decoration:overline"class="radicand">
<var>(2 <em>g h)</em></var></span><br>

where <em>V</em> is the water flow velocity expressed in m/s,
<em>g</em> is the gravitational acceleration expressed in m/s<sup>2</sup>
and <em>h</em> is the water depth in correspondence of the dam breach expresssed in meters (m). <br>
and <em>h</em> is the water depth in correspondence of the dam breach
expressed in meters (m). <br>



Optionally the user may modify the initial timestep used for the numerical solution of the SWE (<em>default value = 0.01 s</em>), nevertheless the timestep [],
and choose a specific failure tipe corresponding to different computational method for the initial velocity estimation.
Optionally the user may modify the initial timestep used for the numerical
solution of the SWE (<em>default value = 0.01 s</em>), nevertheless the
timestep [<b>timestep</b>],
and choose a specific failure type corresponding to different computational
method for the initial velocity estimation.
<br><br>


<br>

<br>
<br>
<em><b><!--font size = "5"-->Notes</b></em><!--/font-->

<br>
<br>
<h2>NOTES</h2>
<em>(GRASS ANSI C command)</em>


<h2>AUTHORS</h2>
Roberto Marzocchi (<a href="mailto:roberto.marzocchi@gter.it">e-mail</a>) and Massimiliano Cannata (<a href="mailto:massimiliano.cannata@supsi.ch">e-mail</a>).
The GRASS tool was developed by Institute of earth science (IST),
University of applied science of Italian Switzerland (SUPSI), Lugano - Division of geomatics <a href="http://istgeo.ist.supsi.ch/site/" target="_blank">web-page</a><br>
Actually the debug is assured by:<br>
- <a href="http://www.gter.it/?q=en" target="_blank"> Gter srl</a> (Genoa, Italy) <br>
- <a href="http://www.ist.supsi.ch/" target="_blank">IST -SUPSI</a> (Lugano, Switzerland)<br>



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

<h2>REFERENCES</h2>
[1] Cannata M. & Marzocchi R. (2012). Two-dimensional dam break flooding simulation: a GIS embedded approach. - Natural Hazards 61(3):1143-1159 <br>
[2] <a href="http://gfoss2009.crs4.it/en/system/files/marzocchi_cannata_licensed.pdf"
target="_blank">Pdf</a> presentation of the work at the
"X Meeting degli Utenti Italiani di GRASS - GFOSS" (It)
<a href="http://gfoss2009.crs4.it/en/node/61" target="_blank">web-page</a><br>
[3] Pdf presentation of the work at the FOSS4G 2009 (En) -
<a href="http://2009.foss4g.org/researchpapers/#researchpaper_10"
target="_blank">web-page</a><br>
[4] Pdf presentation of the work at the Geoitalia 2011 conference (En) -
<a href="https://dl.dropbox.com/u/3019930/marzocchi_cannata_geoitalia2011.pdf"
target="_blank">document</a><br>


<h2>SEE ALSO</h2>
Expand All @@ -131,10 +163,35 @@ <h2>SEE ALSO</h2>
Details of the numerical model are presented in references. <br>
Details of use and developing of <a r.damflood></a> are available <a href="http://istgeo.ist.supsi.ch/site/projects/dambreak" target="_blank">here</a>.<br>

<h2>REFERENCES</h2>
[1] Cannata M. & Marzocchi R. (2012). Two-dimensional dam break flooding simulation: a GIS embedded approach. - Natural Hazards 61(3):1143-1159 <br>
[2] <a href="http://gfoss2009.crs4.it/en/system/files/marzocchi_cannata_licensed.pdf" target="_blank">Pdf</a> presentation of the work at the "X Meeting degli Utenti Italiani di GRASS - GFOSS" (It) <a href="http://gfoss2009.crs4.it/en/node/61" target="_blank"> web-page </a> <br>
[3] Pdf presentation of the work at the FOSS4G 2009 (En) - <a href="http://2009.foss4g.org/researchpapers/#researchpaper_10" target="_blank"> web-page </a> <br>
[4] Pdf presentation of the work at the Geoitalia 2011 conference (En)- <a href="https://dl.dropbox.com/u/3019930/marzocchi_cannata_geoitalia2011.pdf" target="_blank"> document </a><br>

<h2>AUTHORS</h2>
Roberto Marzocchi (<a href="mailto:roberto.marzocchi@gter.it">e-mail</a>)
and Massimiliano Cannata (<a
href="mailto:massimiliano.cannata@supsi.ch">e-mail</a>).
The GRASS tool was developed by Institute of earth science (IST),
University of applied science of Italian Switzerland (SUPSI), Lugano -
Division of geomatics <a href="http://istgeo.ist.supsi.ch/site/"
target="_blank">web-page</a><br>
Actually the debug is assured by:<br>
<ul>
<li>
<a href="http://www.gter.it/?q=en" target="_blank">Gter srl</a>
(Genoa, Italy)<br>
</li>
<li>
<a href="http://www.ist.supsi.ch/" target="_blank">IST -SUPSI</a>
(Lugano, Switzerland)<br>
</li>
</ul>


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

<!--
<p><i> Last changed: $27 februar 2013 09:40:00 CET $</i>
-->