r.avaflow - The simulation model for avalanche and debris flows, Version 1.8 (20171019 - 19 October 2017)
Raster, Granular avalanche, Debris flow
r.avaflow [-ekmv] prefix=string [cores=integer] [cellsize=float] [model=integer] [limiter=integer] [funcctrl=int,...] [aoicoords=float,...] [elevation=name] [hrelease=name] [rhreleases=float[,float]] [vhrelease=float,float] [hreleases=name] [hreleasef=name] [hentrmax=name] [rhrentrmaxs=float[,float]] [vhrentrmax=float,float] [hentrmaxs=name] [hentrmaxf=name] [centr=name] [delta=name] [ambdrag=name] [flufri=name] [roughness=name] [impactarea=name] [hdeposit=name] [hydrograph=string[,string,...]] [hydrocoords=float,float[,float,...]] [flowparam=float,...] [baseparam=float[,float,...]] [sampling=integer] [cfl=float,float] [tint=float] [tstop=float] [imparam=float,...] [profile=float,...] [ctrlpoints=float,float[,float,...]] [phexagg=float] [orthophoto=string] [--verbose] [--quiet]
r.avaflow (Mergili et al., 2017) represents an application to run physically-based models for simulating the motion of granular avalanches or debris flows over arbitrary topography, and to visualize the results. It empoys the NOC numerical scheme (Wang et al., 2004) along with the Voellmy-Salm Model with entrainment and random kinetic energy (Christen et al., 2010) or with the Pudasaini Two-phase Flow Model (Pudasaini, 2012) with entrainment, which may be run alternatively. The starting mass may be given as raster map of the release height and/or as one or more hydrographs. r.avaflow includes the possibility to explore multi-core computing environments to run multiple simulations at once as a basis for parameter sensitivity analysis and optimization.
Note that, as release heights are usually given in the direction parallel to gravity, these heights can be converted into depths (perpendicular to the local topography) needed for the simulation at the start, whilst the resulting depths are reconverted into heights for output.
r.avaflow was developed and tested on Ubuntu 12.04 LTS and 16.04LTS as well as on Red Hat 6.6 (Scientific Linux), but is expected to work in other LINUX environments, too. It relies on GRASS GIS 7, installation of r.avaflow requires the grass-dev package. Visualization and validation of the model results (flag v) makes use of the R Project for Statistical Computing (recommended version: 3.0.2 or higher). The following packages of R are required in order to fully explore the functionalities offered by r.avaflow: maptools, stats, sp, rgeos, rgdal, ROCR and raster. The code builds on Python 2.7 (the Python Imaging Library PIL is required) and C. The script grass7.install.sh provided with r.avaflow can be used to automatically install all the software needed on fresh installations of Ubuntu 12.04LTS, 14.04LTS, or 16.04LTS. The script has to be called from the terminal as superuser (requiring administrator rights): sudo sh grass7.install.sh.
As soon as all software requirements are fulfilled, the installation of r.avaflow is straightforward and just requires a few more steps. Please note that you need administrator rights (access to sudo) and that some manual modifications of the installation script might be required.
Model execution (flag e)
This flag activates the execution of the simulation model for granular avalanches and debris flows.
Keep result GRASS raster maps (flag k)
Particularly with a very large number of model runs (flag m and parameter cores), a huge amount of GRASS raster maps is produced which are often not needed, but require a considerable amount of disk space. Without the flag k all result GRASS raster maps stored in the active mapset are deleted, with the flag they are kept.
Multiple model runs (flag m)
Multiple model runs are executed to produce impact indicator index maps and to generate the input for the sensitivity analysis and parameter optimization tool AIMEC (Fischer, 2013).
Visualization of model results (flag v)
Series and animations of maps and profile plots are generated for the flow heights, flow velocities, flow kinetic energies and flow pressures modelled for the different time steps.
Note that both m and v are set to active in case none of the two flags is given by the user. Please consult the section Output for a detailed description of the output of r.avaflow.
Mandatory prefix for the output files and folders. Any type of string can be used, but it is recommended to choose a combination of approx. 3-5 characters to shortly describe the simulation.
When performing multiple model runs (flag -m), the number of processors to be used is mandatory. E.g., cores=8 induces the use of 8 processors.
Pixel size in metres to be used for the model (optional with flag m). If the pixel size is not given, it is taken from the input elevation raster map (parameter elevation).
Type of model to be executed, mandatory with flag e). r.avaflow includes the following possibilities:
model=1 starts the Voellmy-Salm model, model=2 starts the Pudasaini two-phase flow model.
Four types of numerical limiters can be used, indicated by an integer number:
Six comma-separated integer controls for activating or deactivating complementary functions (optional). The controls have to be provided in the following sequence:
Series of four coordinates (N, S, W, E) delineating the bounding rectangle to applied for the analysis. If this parameter is not given, the bounding rectangle will be determined from the elevation raster map (parameter elevation).
Name of the input elevation raster map. Note that, in the release area, the map has to represent the bottom of the flow mass. This parameter is mandatory with flag e), the unit is metres. Those pixels of the elevation raster map where data are available are considered the area of interest (which can optionally be further constrained through the rectangle defined by the parameter aoicoords.
The following five parameters determine the distribution of the release height of the flow. If none of the parameters is given, the release height of the flow should be given by the parameters hydrograph and hydrocoords.
Name of the input raster map representing the distribution of the release height. The unit is metres.
Without flag -m, dimensionless number in the range 0-1 indicating the ratio of solid release height out of the total release height given by the parameter hrelease. With flag -m, two or three comma-separated dimensionless numbers in the range 0-1 indicating the lower and the upper threshold for randomization or controlled variation (see parameter sampling). This parameter is ignored for model=1 or when hrelease is not given along with model=2.
Two or three comma-separated dimensionless numbers indicating the lower and upper thresholds for the randomization or controlled variation (see parameter sampling) of the release height between different model runs. The resulting number is multiplied with the values of release height given by the parameter hrelease. vhrelease is only considered with flag -m. If the parameter is not given, the release height is kept constant throughout all model runs.
Name of the input raster map representing the distribution of the solid release height. The unit is metres. This parameter is ignored for model=1 or when hrelease an rhreleases are given along with model=2.
Name of the input raster map representing the distribution of the fluid release height. The unit is metres. This parameter is ignored for model=1 or when hrelease and rhreleases are given along with model=2.
The following five parameters determine the distribution of the maximum height of entrainment. If none of the parameters is given, the height of entrainment is not limited.
Name of the input raster map representing the distribution of the maximum height of entrainment. The unit is metres.
Without flag -m, dimensionless number in the range 0-1 indicating the ratio of maximum solid height of entrainment out of the maximum total height of entrainment given by the parameter hentrmax. With flag -m, two or three comma-separated dimensionless numbers in the range 0-1 indicating the lower and the upper threshold for randomization or controlled variation (see parameter sampling). This parameter is ignored for model=1 or when hentrmax is not given along with model=2.
Two or three comma-separated dimensionless numbers indicating the lower and upper thresholds for the randomization or controlled variation (see parameter sampling) of the maximum height of entrainment between different model runs. The resulting number is multiplied with the values of the maximum height of entrainment given by the parameter hentrmax. vhentrmax is only considered with flag -m. If the parameter is not given, the maximum height of entrainment is kept constant throughout all model runs.
Name of the input raster map representing the distribution of the maximum solid height of entrainment. The unit is metres. This parameter is ignored for model=1 or when hentrmax an rhentrmaxs are given along with model=2.
Name of the input raster map representing the distribution of the maximum fluid height of entrainment. The unit is metres. This parameter is ignored for model=1 or when hentrmax and rhentrmaxs are given along with model=2.
Optional input raster map defining the spatial patterns of the entrainment coefficient, provided as logarithm (base 10). If this parameter is not given, and for all pixels with value -9999, the global value of the entrainment coefficient is taken from the flow parameters (see parameter flowparam).
Optional input raster map defining the spatial patterns of the basal friction angle in degrees. If this parameter is not given, and for all pixels with value -9999, the global value of the basal friction angle is taken from the flow parameters (see parameter flowparam).
Optional input raster map defining the spatial patterns of the ambient drag coefficient. If this parameter is not given, and for all pixels with value -9999, the global value of the ambient drag coefficient is taken from the flow parameters (see parameter flowparam).
Optional input raster map defining the spatial patterns of the fluid friction coefficient. If this parameter is not given, and for all pixels with value -9999, the global value of the fluid friction coefficient is taken from the flow parameters (see parameter flowparam).
Optional input raster map defining the spatial patterns of the roughness threshold. If the total flow depth is below that threshold, a decelerating effect of fine-scale (within individual raster cells) surface roughness is assumed. If this parameter is not given, and for all pixels with value -9999, the global value of the roughness threshold is taken from the flow parameters (see parameter flowparam).
Name of the input raster map defining the observed impact area of the flow. Areas with observed impact should be indicated by positive values, areas with no observed impact by 0, no data areas by negative values.
Name of the input raster map of the height of the observed deposit of the flow. The unit is metres. Areas with no data should be indicated by negative values.
Path to input hydrograph text file. This text file has to consist of five columns:
An unlimited number of hydrographs may be defined additionally to or instead of the helease height parameters(hrelease, rhreleases, vhrelease, hreleases and/or hreleasef).
Centre coordinates, profile length and aspect of each input hydrograph, starting with the x coordinate of the first hydrograph, followed by the y coordinate of the first hydrograph, the profile length of the first hydrograph, the aspect of the first hydrograph (flow direction in radian starting from east-west in anti-clockwise direction; -9999 to align the hydrograph perpendicular to the steepest slope), the x coordinate of the second hydrograph and so on. All entries are separated by commas. If more pairs of coordinates than input hydrographs (parameter hydrograph) are given, the remaining pairs of coordinates define the locations of output hydrographs. If less pairs of coordinates than hydrographs are given, the model run(s) will crash.
Comma-separated values of geotechnical and fluid parameters governing the behaviour of the flow. With model=1, the parameters have to be specified in the following order:
With model=2, the parameters have to be specified in the following order:
If the parameter delta (raster map of basal friction angle) is provided, the values of the raster map are applied to all pixels where delta is not -9999, and the values given by flowparam are applied to all other pixels.
With the flag m, two or three values have to be given for each parameter, the first one representing the minimum and the second one the maximum threshold for randomization or controlled variation (parameter sampling). The third parameter denotes the number of tested values in case of controlled variation (sampling=0) whilst it denotes the initial value in case of one-at-a-time sampling (sampling smaller than 0). It is skipped in the case of random sampling (sampling larger than 0). The first value given represents the lower threshold of the first parameter, followed by the upper threshold of the first parameter, the third value for the first parameter (if necessary), the lower threshold of the second parameter and so on. All entries are separated by commas. If only one value of a given parameter shall be applied throughout all model runs, identical values have to be specified for the lower and upper threshold, but both have to be given in order to maintain the consistency of the list of values.
Empirical entrainment coefficient (1/kg). With approach 0 (no entrainment) the parameter is ignored, otherwise either baseparam or centr is mandatory. If both are given, the values of the raster map (parameter centr) are applied to all pixels where centr is not -9999, and the values given by baseparam are applied to all other pixels.
With the flag m, the same rules as described for the parameter flowparam have to be followed.
This parameter is only applicable along with the flag m. It defines the type of sampling of the parameters vhrelease, rhreleases, vhentrmax, rhentrmaxs and flowparam: integer value larger than 0 = random sampling (the default; the value given denotes the number of model runs i.e., the sample size), 0 = controlled sampling, integer value smaller than 0 = one-at-a-time sampling (the value given, if multiplied by -1, denotes the number of model runs i.e., the sample size, for each parameter). With controlled or one-at-a-time sampling, the number of model runs is applied to generate a uniform distribution between the minimum and the maximum of each parameter which is varied. This means that the actual number of model runs is the product of the sample sizes associated to all the varied parameters.
Two comma-separated floating point numbers governing time step length (optional):
Note that higher values of the CFL criterion and the maximum time step length help to decrease the computational time, but lead to an increased risk of numerical failure. The default values serve well for most simulations, so that this parameter should only be provided in case of numerical issues.
Time interval in seconds for writing output.
Time in seconds after which to stop the simulation.
Lower thresholds of flow height in metres, flow kinetic energy in Joule, and flow pressure in Pascal for map display, and flow height in metres for computation. These four values have to be provided in the specified order, separated by commas.
Main flow path, given by the coordinates of an unlimited number of points along the flow path, separated by commas in the following sequence: x of first point, y of first point, x of second point and so on (all in metres). Note that the sequence of points has to strictly follow the course of the path, starting at the top and ending at the bottom, without juming forth and back.
An unlimited number of control points for which te main model output parameters are written to a text file. The control points are defined by comma-separated coordinates: x of first point, y of first point, x of second point and so on (all in metres).
Factor for exaggeration of flow height in profile plots (flag v). A value of 1 (the default) means no exaggeration. Exaggeration of flow height may be useful in case of a large ratio between flow length and flow height. However, the interpretation of profiles with exaggerated flow height requires specific care.
Optional path to an orthophoto of the investigation area, only useful along with flag v. If provided, this orthophoto will be used as background for the map display, otherwise a hillshade automatically generated from the elevation raster map will be used as background.
The names of all output raster maps, folders and files start with the prefix defined by the parameter prefix. r.avaflow produces a set of output GRASS raster maps stored in the active mapset as well as a set of asc, gif, png and txt files stored in subfolders of the folder [prefix]_results:
The subfolders [prefix]_hydrographs, [prefix]_maps and [prefix]_profiles, including their content, are produced only if the flag v (visualization of model results) is specified. In addition, the subfolder [prefix]_hydrograph depends on the specification of the parameters hydrograph and hydrocoords. The folder [prefix]_aimec is only produced with the flag m whilst the folder [prefix]_profiles is only produced without the flag m.
If the flag v was not specified when executing the model, the visualization can be performed afterwards by running the command
r.avaflow -v prefix=[prefix].
This step is only possible if the output raster maps still exist in the active GRASS mapset and the directory [prefix]_results has remained unchanged since the original computation. However, advanced users may manually modify the content of the text file [prefix]_documentation.txt.
Active GRASS mapset
r.avaflow produces the following output raster maps which are, however, stored permanently only with the flag k:
For model=1, [prefix]_rflow[timestep] represents the random kinetic energy for the time step [timestep]. For model=2, the solid and fluid components of each parameter are output as separate raster maps identified by the letters s for solid and f for fluid inserted before [timestep]. Maxima of flow heights, flow kinetic energies and flow pressures over the entire simulation are output with the suffix _max. The final values of the flow heights and entrained/deposited heights are output with the suffix _fin. [prefix]_elev_mod denotes the elevation in metres at the end of the simulated event (initial elevation corrected for entrainment and deposition.
With the flag m, mainly three output maps are produced, illustrating the impact indicator indices for maximum flow height ([prefix]_iii_hflow.png), for maximum flow kinetic energy ([prefix]_iii_tflow.png) and for maximum flow pressure ([prefix]_iii_pflow.png). The impact indicator index represents the number of simulation runs where the maximum value of the considered parameter computed for a pixel is equal or larger than the corresponding impact threshold (parameter imparam) divided by the total number of successful simulation runs.
In addition to the output maps, some preprocessed input maps are produced (with the flag m they may amount to a large number, depending on the number of model runs). Most output and preprocessed input maps are also stored as ascii rasters in the folder [prefix]_ascii.
With the flag m, this folder contains the automatically generated input folders and files for the validation, parameter sensitivity analysis and optimization tool AIMEC. In order to enable applying this tool to the results produced by r.avaflow, the content and structure of this folder should not be manipulated manually.
Most of the output and preprocessed input raster maps stored in the active GRASS mapset are also exported as ascii rasters in order to be accessible with other software packages. The naming scheme follows the one used for the GRASS raster maps.
The following text files summarize the main parameters of the simulation or are needed for the construction of the maps and plots in the folders [prefix]_hydrographs, [prefix]_maps and [prefix]_profiles:
Maps of the maximum values (suffix _max) of flow height, flow kinetic energy and flow pressure over the entire simulation and a map of the final height of entrainment and deposition (suffix _fin) are drawn at the top level of the folder along with animated gifs illustrating the evolution of the flow parameters during the simulation. The suffix c in the file names of the gifs refers to compressed versions. With the flag m, only three maps are drawn, illustrating the impact indicator indices for maximum flow height ([prefix]_iii_hflow.png), for maximum flow kinetic energy ([prefix]_iii_tflow.png) and for maximum flow pressure ([prefix]_iii_pflow.png).
Two additional text files, aucroc.txt and aucrocn.txt, are produced along with the ROC Plots. These files are stored directly in the working directory and display the prefix of the computation along with the corresponding value of AUCROC: in aucroc.txt, the value refers to the entire area of interest, while in aucrocn.txt the true negative area is normalized. These two files are not overwritten during the next execution of r.avaflow. Instead, a new line is added each time r.avaflow is run with the flag v. This facilitates the analysis of the AUCROC values in case of multiple executions of r.avaflow.
This version of r.avaflow represents an experimental implementation of the Voellmy-Salm Model and, more importantly, the Pudasaini Two-phase Flow Model - which can be chosen alternatively - for arbitrary mountain topography. It was tested for a number of study areas and is expected to work also for others. However, (i) thorough testing with real-world events and laboratory experiments, (ii) checking of the code for errors and (iii) general improvement of the application are still ongoing. In particular, the following issues are known:
Christen, M., Kowalski, J., Bartelt, P., 2010. RAMMS: Numerical simulation of dense snow avalanches in three-dimensional terrain. Cold Regions Science and Technology 63(1), 1-14.
Fischer, J-T., 2013. A novel approach to evaluate and compare computational snow avalanche simulation. Natural Hazards and Earth System Sciences 13(6), 1655-1667.
Mergili, M., Fischer, J.-T., Krenn, J., Pudasaini, S.P.,2017. r.avaflow v1, an advanced open source computational framework for the propagation and interaction of two-phase mass flows. Geoscientific Model Development 10, 553-569.
Pudasaini, S.P., 2012. A general two-phase debris flow model." Journal of Geophysical Research: Earth Surface 117, F3.
Wang, Y., Hutter, K., Pudasaini, S.P., 2004. The Savage-Hutter theory: A system of partial differential equations for avalanche flows of snow, debris, and mud. ZAMM-Journal of Applied Mathematics and Mechanics/Zeitschrift für Angewandte Mathematik und Mechanik 84(8), 507-527.
Martin Mergili, University of Natural Resources and Life Sciences (BOKU), Vienna, Austria and University of Vienna, Austria
Shiva P. Pudasaini, University of Bonn, Germany
Funding: German Research Foundation DFG and Austrian Research Fund FWF
Project web site: avaflow.org
The support of Massimiliano Alvioli, Matthias Benedikt, Wolfgang Fellin, Jan-Thomas Fischer, Andreas Huber, Ivan Marchesini, Markus Metz, Alexander Ostermann and Matthias Rauter is acknowledged.
Last changed: 19 October 2017.
Main index - raster index - Full index
© 2008-2017 The authors, © 2010-2017 The BOKU University, Vienna, © 2015-2017 The University of Vienna, © 2014-2017 The University of Bonn, © 1999-2017 The GRASS Development Team and © 1993-2017 The R Development Core Team