r.avaflow
The mass flow simulation tool
r.avaflow 2.4 User manual
by Martin Mergili
r.avaflow 2.4 represents a GIS-supported open source software tool for the simulation of complex, cascading mass flows over arbitrary topography. It empoys the NOC-TVD numerical scheme (Wang et al., 2004) along with a Voellmy-type model, with an enhanced version of the Pudasaini multi-phase flow model (Pudasaini and Mergili, 2019), or with a simple mass point model for the approximation of sliding processes. Complementary functions include entrainment, deposition, stopping, and phase transformations. The starting mass may be defined through raster maps and/or hydrographs. r.avaflow 2.4 includes the possibility to explore multi-core computing environments to run multiple simulations at once as a basis for parameter sensitivity analysis and optimization.
Tutorial videos
r.avaflow 2.4 is most easy to learn from videos.
The following videos are intended to facilitate the first steps with r.avaflow. They were created based on r.avaflow 2.2, but are equally useful for r.avaflow 2.4, even though some input options might have changed. However, note that the installation of r.avaflow now uses the GRASS module g.extension, so that no installation script is required any more.
- Lesson 1 | General aspects
- Lesson 2 | Software installation and preparation of data
- Lesson 3 | First simulations with r.avaflow
The Frank Slide data used in the video tutorials were provided as a courtesy by Oldrich Hungr and should only be used for training purposes. Please consult Hungr (2008) for more information on the data and their previous use.
Recent changes
r.avaflow 2.4 includes some substantial changes, compared to r.avaflow 2.0-2.3.
The most fundamental changes in r.avaflow 2.4, compared to r.avaflow 2.3, are indicated below. This list is most useful for those users which have already been working with r.avaflow 2.3.
- r.avaflow 2.4 only operates with Python 3 and GRASS 7.8. The use with Python 2.7 and older versions of GRASS GIS has been deprecated.
- The installation of r.avaflow 2.4 uses the built-in GRASS module g.extension. No installation script is provided any more.
- Mass point model for sliding: a completely new feature has been introduced, allowing to approximate the motion of slide-type movements with no or limited internal deformation. At each time step, the material at each raster cell is moved through a one-parameter or two-parameter friction model, based on the slope and aspect of the entire sliding mass or a user-defined neighbourhood zone. There is flexibility in transformation from sliding to flowing, and in spatially differentiating between zones of sliding and flowing. This feature is managed and parameterized through the newly introduced options tslide and slidepar. It is mainly intended for the very initial stage of landslide processes, before disintegration of the mass.
- Entrainment, deposition, and stopping: the models covering the interaction of the flow with the basal surface have been fundamentally revised and extended, allowing for a much more realistic representation of entrainment and deposition, but also stopping. Obsolete approaches have been removed. See options tstop, basal, and cvshear for more details.
- Flow parameters: some changes and rearrangements were made. The option ambient was replaced by the newly introduced option basal, which serves for the parameterization of the updated entrainment, deposition, and stopping models. The fluid friction number (which is related, but not similar to the Manning number) is now included in the option friction whereas the ambient drag coefficient, which has turned out to be hard to handle in practical applications, has been moved to the option special with a default value of 0.0.
- The function for the dynamic adaptation of the friction parameters has been modified in order to allow for a more convenient parameterization. If the function is activated (options controls), the friction parameters given through the option friction are valid for flows with zero kinetic energy (i.e. at rest). The exponential decrease of the friction is governed by a coefficient which is multiplied with the kinetic energy at a given raster cell. Further, the scaling of the friction parameters with the fraction of the respective case has been integrated. However, for most applications, it is strongly recommended to deactivate this function by setting the scaling exponent to zero.
- Progressive collapse: the possibility to consider progressive release though the options trelease and trelstop has been extended from the first phase to the entire mass. Still, this function should only be used for one single release mass, and cannot be combined with the extrusion-type progressive release.
- Curvature: the effects of topographic curvature can be more rigorously applied than in the previous versions. They can be switched on and off through the second value in the controls option: 0 = deactivated, 1 = only applied to decelerationg terms (comparable to the implementation in version 2.3), 2 = applied to all terms (slows down the simulation and may cause numerical issues). The default is 1. Note that deactivating curvature effects can make the simulated flow substantially more mobile.
- Diffusion control: this feature has been deprecated. Even though it has some effect in reducing computational times, unplausible behaviour has been observed in some specific flow situations.
- Option hydrocoords: the aspects of the hydrograph profiles have to be provided in degrees instead of radians.
- The maximum flow velocity displayed in the map plots, which sometimes used to show unrealistically high values, is now computed in a different way, better approximating the real conditions.
- Additional output raster maps of frontal and maximum flow velocities and phase fractions are automatically generated, depending on the model used.
- The accessibility of the map plots displaying the output of the mixture or one-phase model has been improved by adapting the colour schemes.
The major changes in r.avaflow 2.3, compared to r.avaflow 2.2, are indicated below. This list is most useful for those users which have already been working with r.avaflow 2.2.
- Numerical issues with the Voellmy-type mixture model, which were observed in the previous versions, have been fixed. Decelerating forces are now treated separately from the accelerating forces (as it had been implemented earlier for the Pudasaini and Mergili, 2019 multi-phase model), in order to avoid changes of the flow direction due to deceleration effects, having caused the numerical instabilities.
- Progressive collapse: the possibility to consider progressive release though the options trelease and trelstop has been extended. It is now possible to simulate the progressive collapse of a release mass, starting from its summit, instead of the progressive extrusion of the release mass from its basis. Progressive collapse is activated by providing trelstop with negative sign. Note that this function is still experimental and, when used with the multi-phase model, is only applied to the the first phase. It should only be used for one single release mass, and cannot be combined with the extrusion-type progressive release.
- Ambient drag: the default value of the ambient drag coefficient has been changed to 0.0. Experience and feedback from users have shown that setting the ambient drag coefficient (mainly used for air resistance) in a reliable way is a considerable challenge. Therefore, it is now recommended not to consider air resistance in a direct way, but rather to include its effect in the friction parameters (basal friction and turbulent friction in the Voellmy-type model, basal friction in the Pudasaini and Mergili, 2019 model).
- Internal friction and basal friction: if the internal friction is lower than the basal friction, it is set equal to the basal friction. This means that, in simulations with varying basal friction, the internal friction can be globally set to the basal friction by choosing a very low value.
- Fluid friction: Manning's n is now used as the fluid friction coefficient, the default value is 0.05. As Mannings n is widely used, it is supposed to greatly facilitate the choice of appropriate values. This change was mostly implemented by Sigríður S. Gylfadóttir from the Iceland Meteorological Office.
- Stopping: an additional stopping criterion has been introduced. When setting the fifth value in the controls parameters to 7, the flow stops when there is no raster cell at which the dynamic flow pressure is larger than the threshold value for flow pressure given in the thresholds parameter.
- Flow pressure: only the dynamic component of the pressure is considered, whereas the static component has been removed.
- Time of reach: the time of reach is now automatically provided as an additional output GRASS raster, ASCII raster, and map plot, indicated by the string treach. It shows the time in seconds after which the flow first reaches each raster cell, using the mimimum flow height for display (thresholds parameters) as the criterion. Time of reach is also shown in the control points output files. With multiple simulations (flag m), the ratio between the time of reach and the observed time of reach is included in the evaluation. Observed times of reach can be provided through the newly introduced option reftime, where comma-separated values indicate the observed travel times to each control point in seconds.
- Not providing the flag a has a more "aggressive" impact than in the previous versions. The output in terms of GRASS raster maps, ASCII rasters, and map plots is reduced to an absolute minimum (flow heights, change of basal topography if relevant, time of reach) in order to save time and memory. Note that no profile graphs can be produced without this flag. However, note that the flag a is now automatically enabled for multiple simulations (flag m).
- Some further bugs were fixed, such as another issue with progressive release.
The major changes in r.avaflow 2.2, compared to r.avaflow 2.1, are summarized as follows. This list is most useful for those users which have already been working with r.avaflow 2.1.
- An important bugfix has been included, concerning the treatment of hydrographs with Python 3.
- In the input hydrographs, the discharge in cubic metres per seconds now has to be provided instead of the flow height, whereas flow velocity has to be provided in the same way as before. Discharge and flow velocity are always applied to the centre of the hydrograph profile. The profile length is only used for the output hydrographs, but has to be provided also for the input hydrographs.
- After the flexibility in the combination of phases had been strictly constrained in r.avaflow 2.1, r.avaflow 2.4 again allows for the combination of two solid phases and one fluid phase (phases=s,s,f). However, this is the only exception from the rule that the sequence always has to be solid - fine solid - fluid when considering more than one phase. Simulations with two solid phases and one fluid phase should still be considered experimental. They can be useful when considering avalanches of rock and ice, since the consideration of granular flows of ice blocks as fine solid is not necessarily appropriate.
The list below summarizes the most important changes introduced in r.avaflow 2.1, compared to r.avaflow 2.0. It is most useful for those users which have already been working with r.avaflow 2.0.
- r.avaflow 2.4 can be run with Python 2.7 or Python 3. Installation with Python 2.7 is only recommended if the setup with all required software packages is already available. The script grass7.install.sh is exclusively targeted at the setup for the application of r.avaflow with Python 3 and GRASS GIS 7.8 or higher.
- The combination of phases is more restricted than in r.avaflow 2.0, in order to ensure a more rigorous application of the Pudasaini and Mergili, 2019 model and its extensions. Previously optimized model parameters might have to be revised. From an operational point of view, there is no two-phase model directly available any more, and the first phase in the multi-phase model is always solid, the second phase is always fine solid, and the third phase is always fluid. The multi-phase model is selected by entering phases=m. Input of material through the release, entrainment, and hydrograph parameters governs which phases are effectively considered and which are not. Providing input, for example, for the phases 1 and 3, but not for phase 2, effectively results in a two-phase model of solid and fluid material. It is noted that the fine solid phase can be represented by a wide variety of materials, ranging from rather solid ice to rather fluid slurry. Defining hrelease together with rhrelease1 results in an effectively two-phase simulation of solid and fluid (i.e. the phases 1 and 3), where rhrelease1 represents the fraction of solid release material. One-phase models can be used in the same way as in the version 2.0, with the difference that the Voellmy-type mixture model is selected through phases=x.
- Balancing of forces has been improved, so that numerical oscillations on water surfaces are strongly reduced, though not completely eliminated. Still, the new functionality has to be activated through the surface control in the controls parameter. Also, the boundary conditions have been revised, so that water surfaces can now extend all the way to the margin of the area of interest, without draining towards outside. These improvments make r.avaflow potentially suitable for the simulation of tsunamis. As a consequence, an additional set of map plots displaying the evolution and maximum of the heights of impact waves or tsunamis can be generated optionally, by providing the flag t.
- There are two new stopping criteria available: with stopping=4, the flow stops when its kinetic energy reaches a certain fraction of its maximum kinetic energy during the simulation. This fraction is defined through an additional value in the ambient parameter. 0.05 (the default) would mean that the flow stops as soon as its kinetic energy drops below 5 per cent of its maximum kinetic energy. With stopping=5, the same principle applies, but considering flow momentum instead of kinetic energy. Note that the additional value in the ambient parameter has to be provided in any case - but it is only used if one of the new stopping criteria are applied.
- Also, the flexibility with regard to entrainment has been increased: with entrainment=2, the entrainment coefficient is multiplied with the flow momentum instead of the flow kinetic energy at a given raster cell.
- Non-hydrostatic effects are now optionally considered, including enhanced gravity and dispersion. This function is activated by setting the surface control to a value of 2 in the controls parameter. Please note that this function is still in its experimental stage and undergoes further testing.
- A new, still experimental function for time scaling can be used for the simulation of very viscous, slow moving one-phase flows. Setting the new slomo parameter to a value larger than 1 means that the time is not measured in seconds, but in seconds multiplied with the value provided. slomo=86400 would scale the time from seconds to days, resulting in output velocities of metres per day. However, such changes of units are not indicated in the output data.
- The friction parameters can be dynamically adapted to the flow kinetic energy, in order to account for fluidization and lubrication effects. This function is activated by setting the last (additional) value of the controls parameter to 1. The necessary constraints are provided through the new option dynfric. Also this function is still in its experimental stage.
- Providing the flag a in addition to v results in the generation of map plots for flow kinetic energy and flow pressure. In older versions of r.avaflow, these plots were created automatically with the flag v. However, they are not always needed, so that it appears appropriate to make them optional outputs.
Further, note that some bugs were identified and fixed, in comparison to r.avaflow 2.0. It is therefore not recommended to use r.avaflow 2.0 any more. If you encouter possible bugs in this version, or have ideas for improvement of the software, please do not hesitate to contact martin.mergili@boku.ac.at. Note that r.avaflow is not a commercial software, nor is its development subject of an ongoing funded project. However, it is always attempted to provide adequate support as timely as possible.
Requirements
r.avaflow 2.4 runs on LINUX operating systems. It relies on GRASS 7 and R.
r.avaflow 2.4 was developed and tested on Ubuntu 20.04 LTS, but is expected to work in other LINUX environments, too. It relies on GRASS GIS 7.8 and Python 3. Installation of r.avaflow 2.4 requires the grass-dev package. Visualization and evaluation of the model results (flag v) makes use of the R Project for Statistical Computing (recommended version: 3.6.3 or higher) and the Python library pillow. The following packages of R are required in order to fully explore the functionalities offered by r.avaflow 2.4: maptools, stats, sp, rgeos, rgdal, ROCR, and raster. The code builds on Python and C. The script grass7.install.sh provided with r.avaflow 2.4 can be used to automatically install all the software needed on fresh installations of Ubuntu 20.04LTS, and probably also on installations of other LINUX environments. However, please note that LINUX environments and the related software are dynamically evolving, so that the script might be outdated quickly, requiring manual modifications in case of failure. Manual interventions might also be necessary if older installations of some of the required software do exist on the system. The script has to be called from the terminal as superuser (requiring administrator rights): sudo sh grass7.install.sh
Installation
r.avaflow 2.4 can be easily installed through the command g.extension.
As soon as all software requirements are fulfilled, the installation of r.avaflow 2.4 is straightforward, using the built-in GRASS module g.extension. Assuming that the folder with the r.avaflow source code is stored in the directory /home/user1/, installation just requires the execution of the following command:
g.extension extension=r.avaflow url=/home/user1/r.avaflow/
Please note that, if you have installed earlier versions of r.avaflow using the script r.avaflow.install.sh, you have to manually remove the old files installed e.g. in the folders /usr/lib/grass78/scripts and /usr/lib/grass78/bin in order to make sure that the r.avaflow command really calls the newly installed version.
Operation
r.avaflow 2.4 is most efficiently operated through shell scripts.
r.avaflow 2.4 is most efficiently operated through shell scripting. Even though beginners often feel uncomfortable first in working with the terminal and with shell scripts, most of them quickly understand that this is a highly comfortable and efficient way to launch simulations and to analyze the results in a systematic way.
First, you have to launch GRASS with the desired Location and Mapset. Please consult the official GRASS GIS website to learn how to do so. You will not use the GUI of GRASS, but work in the terminal. The command line prompt should start with the GRASS version and, in brackets, the location. This means that you are really in GRASS. You can now start r.avaflow 2.4 by typing the arguments directly into the command line:
r.avaflow -e -v prefix=test phases=s elevation=af_elev hrelease1=af_hrelease
In this case, r.avaflow 2.4 would run a simulation with the one-phase model and evaluate and visualize the results, using the elevation map af_elev and the solid release height map af_hrelease as input. The results are collected in a folder named test_results, which will be stored in the current directory. Both maps would have to be available as GRASS rasters in the current mapset.
You can learn much more about the input of r.avaflow in the section below. However, also with this minimum input it can be demonstrated that this way of operation is rather efficient: if you wish to run the simulation again, you can just recover the string by typing the upward key.
But we still go one step further. We can also write the command we have just typed into the terminal in an executable text file, and instead execute this file. Whereas this does not look very straightforward on a first glance, it dramatically increases our flexibility: we can now write several commands into the same script - for example, running r.avaflow for several times with different input. We can go for a beer, to sleep, or even on holiday, and see the results when we have returned, without any intervention required in between.
It is recommended to create a folder for each project we are working on. So, let us create the folder projects/test in our home directory. Within this folder, let us create a text file with the name test.avaflow.start.sh. The suffix sh stands for shell script, which is the most common type of executable file in LINUX environments. We now copy the text we have executed from the command line into this script, and save our changes. Then, back in the terminal, we have to change to the directory where the script is stored, and execute the script by typing sh and its name:
cd projects/test/
sh test.avaflow.start.sh
You will find the folder with the results of the simulation in the directory projects/test. Using shell scripts, you cannot only run several simulations at a time. They also help you to:
- Import tiff or ascii rasters into GRASS (command r.in.gdal)
- Create generic landcapes (command r.mapcalc)
- Preprocess raster maps (command r.mapcalc)
- Compute statistics of deposited volumes (command r.volume)
Examples of such start scipts can be found in the training data.
Input
r.avaflow 2.4 can be run with a minimum of input, but also with a combination of various parameters.
A large choice of options is available for the definition of the initial conditions and the parameterization of r.avaflow. Not all options are needed for all types of simulations - in fact, simple simulations can be performed with very little input. You can filter the set of options by clicking on one of the keywords below. Klicking on further keywords constrains the number of options. The entire set can be recovered by clicking on All. P1 stands for phase 1 (or the mixture), P2 and P3 stand for the phases 2 and 3.
All
Key parameters
Release
Entrainment
Hydrographs
Flow parameters
Operational parameters
Single run
Multiple runs
Mixture model
One-phase model
Multi-phase model
These are the input parameters with which beginners should start using r.avaflow 2.4. Even though default values are defined for some of the parameters, changes in the parameter values may drastically change the simulation results. They are sufficient to run the one-phase model without entrainment, phase transformations, and hydrograph input or output.
Raster maps defining the release height are one of the most important input of r.avaflow 2.4. They define the initial distribution of the flow material in space and time. Alternatively or in addition to the release heights, the initial flow mass can also be defined by input hydrographs.
Raster maps of the maximum height of entrainment help to constrain entrainment. This is useful in cases where a layer of sediment, ice, or any other erodible material overlays non-erodible material such as bedrock.
Hydrographs enable the continuous input of flow material along a given profile (input hydrographs) as well as the analysis of the simulation results at defined points or profiles (output hydrographs). Arbitrary numbers of input and output hydrographs can be defined.
These options define various types of flow parameters, describing the physical characteristics of the flow materials and the surroundings such as the basal surface. Some of the flow parameters can be provided as single values or raster maps, whereas others can be given as single values only.
If the option delta1 is provided, the values of the raster map are applied to all raster cells where delta1 is not -9999, and the values given by friction are applied to all other raster cells. In an analogous way, the same is true for the options phi1, phi2, delta2, phi3, delta3, tufri, flufri, ny1, ny2, ny3, centr, cvshear, ctrans12, ctrans13, ctrans23, and ambdrag.
All parameters for P2 and P3 have to be skipped for the one-phase and mixture models. For example, the option friction could look as follows for the one-phase model:
friction=35,20
For multiple simulations (flag m), all flow parameters - except for those provided with the option slidepar - given as single values can be varied between the various model runs. 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 (option sampling). The third parameter denotes the number of tested values in case of controlled variation (sampling=0) whereas 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 of 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.
These options serve for the input of operational data and parameters governing the spatial and temporal resolution, type of model and numerical limiter, complementary functions used, and visualization of the results
This set of options is relevant for simulations with single model runs. Not all options are needed for all simulations.
This set of options is relevant for simulations with multiple model runs exploring ranges or spaces of parameters. Not all options are needed for all simulations with multiple model runs.
Note that all flow parameters given as single values can be varied between the various model runs. 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 (option sampling). The third parameter denotes the number of tested values in case of controlled variation (sampling=0) whereas 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.
This set of options is relevant for the Voellmy-type mixture model. However, not all options are needed for all simulations.
This set of options is relevant for the one-phase model. However, not all options are needed for all one-phase simulations.
This set of options is relevant for the multi-phase model. However, not all options are needed for all multi-phase simulations.
-a
Map plots of pressure and kinetic energy
This flag - in combination with the flag v - results in the generation of output rasters and map plots of flow pressure and kinetic energy, in addition to the map plots of flow height, change of the basal topography (if relevant), and time of reach. No profile graphs can be produced without this flag. The flag a is automatically activated for multiple simulations (flag m). Without the flag m, it is deactivated by default in order to save time and memory.
-e
Model execution
-e
This flag enables the execution of the simulation model. It is activated by default.
-k
Keep result GRASS raster maps
Particularly with a very large number of model runs (flag m or time steps time), a huge number 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. This flag is deactivated by default.
-m
Multiple model runs
Multiple model runs are executed to produce impact indicator index maps, to evaluate parameter performance and sensitivity, and to generate the input for the sensitivity analysis and parameter optimization tool AIMEC (Fischer, 2013). This flag is deactivated by default.
-t
Map plots of impact wave or tsunami height
This flag - in combination with the flag v - results in the generation of map plots of wave heights in reservoirs. Reserved for the multi-phase model, those plots display solely P3 (fluid), showing the difference between the fluid flow height for each time step and the fluid release height. This function only yields a useful result for simulations involving impact waves or tsunamis. It is deactivated by default.
-v
Evaluation and visualization
-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. If reference data are provided (options impactarea or hdeposit, selected results are evaluated against the reference data provided. This flag is activated by default.
prefix
Prefix for output files and folders
prefix=afl
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.
cores
Number of cores to be used
cores=8
When performing multiple model runs (flag -m), the number of processors can be provided. E.g., cores=8 triggers the use of a maximum of 8 processors (depending on availability), which is the default.
cellsize
Cell size for simulation
Cell size in metres to be used for the model (optional with flag m). If the cell size is not given, it is taken from the input elevation raster map (option elevation).
limiter
Numerical limiter
limiter=1
Four types of numerical limiters can be used, indicated by an integer number:
- 1 = Minmod limiter
- 2 = Superbee limiter
- 3 = Woodward limiter
- 4 = Van Leer limiter
phases
Phases to be considered
phases=m
A maximum of three phases can be defined through shortcuts of one or two characters, separated by commas.
- x = Mixture (Voellmy-type model)
- s = Solid (plastic behaviour, frictional, non-viscous)
- fs = Fine solid (plasticity-dominated viscoplastic behaviour, frictional and viscous)
- f = Fluid (viscosity-dominated viscoplastic, non-frictional, viscous)
- m = Multi-phase (P1: solid, P2: fine solid, P3: fluid)
- s,s,f = Multi-phase (P1: solid, P2: solid, P3: fluid)
The default is the multi-phase model with solid, fine solid, and fluid material (phases=m). Note that the multi-phase model can be reduced from three to two phases by providing input only for two phases (see release, entrainment, and hydrograph parameters). Thereby, solid material always has to be assigned to P1, fine solid material to P2, and fluid material to P3. In any case, the density of P1 has to be higher that the density of P2, and the density of P2 has to be higher than the density of P3.
phasetext
Phase labels for map plots
phasetext=P1,P2,P3
Optionally, comma-separated strings can be provided, describing the materials associated to each phase. The number of comma-separated strings has to correspond to the number of phases defined through the option phases. An example of a multi-phase model would be (phasetext=Rock,Ice,Water). By default, the string Solid is used for solid material, the string Fine is used for fine solid material, and the string Fluid is used for fluid material. This parameter has no influence on the simulation itself. Instead, it serves for a more descriptive labelling of the map plots.
aoicoords
Set of coordinates delineating area of interest
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 (option elevation).
controls
Control parameters
controls=0,1,0,0,0,0
Default
- 0 = No conversion of flow heights to flow depths;
- 1 = conversion of flow heights to flow depths (multiplication with the cosine of the slope), and reverse.
0
Topographic curvature influences the dynamics of mass flows. In r.avaflow, curvature effects can optionally be included in the simulations through the topography-normal component of gravity.
- 0 = Curvature is neglected - this leads to a higher mobility of the simulated flow, compared to the other options;
- 1 = curvature is considered in the decelerating source terms.
- 2 = curvature is considered in all relevant terms. This is the most rigourous application, but it slows down simulations and may cause numerical issues.
1
This function is important for the interaction between landslides and reservoirs, i.e. the formation and propagation of impact waves. Explicit balancing of the forces at the shoreline of horizontal water surfaces is important to reduce numerical oscillations (surface control), but can have negative effects on simulations in other circumstances.
- 0 = No balancing of forces (recommended for all simulations without landslide-reservoir interactions);
- 1 = balancing of forces is applied.
0
If activated, the flow is allowed to entrain material from its basal surface (see options basal, centr, and cshear).
- 0 = No entrainment;
- 1 = entrainment coefficient multiplied with flow momentum;
- 2 = simplified Pudasaini and Krautblatter (2021) entrainment and deposition model;
- 3 = combination of 1 (for entrainment) and 2 (for deposition);
- 4 = acceleration-deceleration entrainment and deposition model. It is assumed that accelerating flows can entrain material, whereas decelerating flows deposit material. The entrainment coefficient defined through the options basal or centr is multiplied with the change of flow velocity at each time step to comute the rate of entrainment or deposition.
0
If activated, a criterion is defined which decides at each time step whether the flow continues or stops and deposits.
- 0 = No stopping;
- 1 = the flow stops if the flow kinetic energy is equal or lower than the threshold value given in the option basal;
- 2 = the flow stops if the flow momentum is equal or lower than the threshold value given in the option basal;
- 3 = the flow stops when there is no raster cell at which the dynamic flow pressure is larger than the threshold value for flow pressure given in the option basal.
The option tstop can be used to define a raster map allowing to constrain the time of stopping in a spatially differentiated way.
0
Optionally, the flow parameters internal friction angle, bed friction angle, and fluid friction coefficient can be scaled with the flow kinetic energy, following an exponential relationship, and with the fraction of the respective phase. This type of scaling is based on the assumption that flows with higher kinetic energy rather tend to develop fluidization or lubrication effects than flows with lower kinetic energy, and that the friction associated to a given phase is reduced if the phase only represents a minor fraction of the entire flowing mass.
- 0 = No dynamic adaptation of friction parameters;
- 1 = dynamic adaptation of friction parameters (ignored for the mixture model).
See option dynfric for more details.
0
elevation
Name of elevation raster map
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, its unit is metres. Those raster cells 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 option aoicoords.
hrelease1
Name of release height of P1 raster map
Name of the input raster map representing the distribution of the release height of P1. The unit is metres. This parameter is ignored if the mixture ore one-phase model is activated through the option phases.
hrelease2
Name of release height of P2 raster map
Name of the input raster map representing the distribution of the release height of P2. The unit is metres. This parameter is ignored if the mixture ore one-phase model is activated through the option phases.
hrelease3
Name of release height of P3 raster map
Name of the input raster map representing the distribution of the release height of P3. The unit is metres. This parameter is ignored if the mixture ore one-phase model is activated through the option phases.
hrelease
Name of release height raster map
Name of the input raster map representing the distribution of the total release height. The unit is metres. This parameter is used for the mixture and one-phase models (option phases). It can also be employed for the multi-phase model together with the option rhelease1.
rhrelease1
Ratio of P1 release height
Without flag -m, dimensionless number in the range 0-1 indicating the fraction of the release height of P1 out of the total release height given by the option hrelease. The remaining fraction is assigned to P3, whereas the release height of P2 is set to zero. 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 option sampling). This parameter is ignored for the mixture and one-phase models (option phases) or when hrelease is not given.
vhrelease
Variation of release height
Two or three comma-separated dimensionless numbers indicating the lower and upper thresholds for the randomization or controlled variation (see option sampling) of the release height between different model runs. The resulting number is multiplied with the values of the release height given by the option hrelease. vhrelease is only considered with flag -m. If the parameter is not given, the release height is kept constant throughout all model runs.
trelease
Name of release start time raster map
Name of input raster map representing the time when the mass at each cell is released, given in seconds after the start of the simulation. This parameter is optional. If it is not given, the mass is released immediately.
trelstop
Name of release stop time raster map
Name of input raster map representing the time when the release stops, given in seconds after the start of the simulation. This parameter only comes into action when also trelease is provided, giving the start of the release. If trelstop is provided, a continuous release is considered and hrelease, hrelease1, hrelease2, and/or hrelease3 have to be given in vertical metres per second. This process can be described as a continuous extrusion of material, such as it is the case for lava during an effusive volcanic eruption. It also possible to simulate the progressive collapse of a release mass, starting from its summit, instead of the progressive extrusion of the release mass from its basis. Progressive collapse is activated by providing trelstop with negative sign. Note that this function is still experimental and, when used with the multi-phase model, is only applied to the the first phase. It should only be used for one single release mass, and cannot be combined with the extrusion-type progressive release.
tslide
Name of time of initial sliding raster map
Name of the input raster map indicating for each cell the time in seconds until which the mass point model for sliding, parameterized through the option slidepar, should be applied. Cell values of -777 provided with the multi-phase model (model=m or model=s,s,f) automatically result in the sliding model to be applied to purely solid and fine solid material, and the flow model to be applied to pure fluid or solid-fluid mixtures. Other negative values, zero, or not using this option at all mean that the sliding model is not applied.
If initial sliding is used for the entire area of interest, it is recommended to set the second number in the option cfl to something around 0.1-0.5 seconds, in order to avoid unnecessarily short time steps.
tstop
Name of stopping time raster map
Name of the input raster map indicating for each cell the time in seconds from which on stopping is enabled. This means that the stopping criterion set through the option basal is disabled before that point in time. If this map is not provided, stopping is enabled from five seconds onwards.
Negative raster cell values have a particular meaning: negative values are interpreted as absolute values in seconds, but the minus sign triggers the behaviour that the flow material at a given raster cell stops as soon as the stopping time is reached, irrespective of the fulfilment of the criterion provided in the option basal. With the multi-phase model (model=m or model=s,s,f), however, the fluid P3 material escapes with an equal amount (in terms of volume) of solid P1 material and the P2 material. This function helps to simulate the development of distal debris flows and related processes from depositing solid-dominated flows such as rock avalanches.
vinx
Name of release velocity in x direction raster map
Name of the input raster map representing the distribution of the release velocity in x direction in the mixture and one-phase models. The unit is m/s. This parameter is optional and not needed for most applications. If it is not provided, its value is set to zero for all cells.
viny
Name of release velocity in y direction raster map
Name of the input raster map representing the distribution of the release velocity in y direction in the mixture and one-phase models. The unit is m/s. This parameter is optional and not needed for most applications. If it is not provided, its value is set to zero for all cells.
vinx1
Name of release velocity of P1 in x direction raster map
Name of the input raster map representing the distribution of the release velocity of P1 in x direction. The unit is m/s. This parameter is optional and not needed for most applications. If it is not provided, its value is set to zero for all cells.
viny1
Name of release velocity of P1 in y direction raster map
Name of the input raster map representing the distribution of the release velocity of P1 in y direction. The unit is m/s. This parameter is optional and not needed for most applications. If it is not provided, its value is set to zero for all cells.
vinx2
Name of release velocity of P2 in x direction raster map
Name of the input raster map representing the distribution of the release velocity of P2 in x direction. The unit is m/s. This parameter is optional and not needed for most applications. If it is not provided, its value is set to zero for all cells. It is further ignored if the one-phase or mixture model is activated through the option phases.
viny2
Name of release velocity of P2 in y direction raster map
Name of the input raster map representing the distribution of the release velocity of P2 in y direction. The unit is m/s. This parameter is optional and not needed for most applications. If it is not provided, its value is set to zero for all cells. It is further ignored if the one-phase or mixture model is activated through the option phases.
vinx3
Name of release velocity of P3 in x direction raster map
Name of the input raster map representing the distribution of the release velocity of P3 in x direction. The unit is m/s. This parameter is optional and not needed for most applications. If it is not provided, its value is set to zero for all cells. It is further ignored if the one-phase or mixture model is activated through the option phases.
viny3
Name of release velocity of P3 in y direction raster map
Name of the input raster map representing the distribution of the release velocity of P3 in y direction. The unit is m/s. This parameter is optional and not needed for most applications. If it is not provided, its value is set to zero for all cells. It is further ignored if the one-phase or mixture model is activated through the option phases.
hentrmax1
Name of maximum height of P1 raster map
Name of the input raster map representing the distribution of the maximum height of entrainment of P1. The unit is metres. This parameter is ignored if the mixture or one-phase model is activated through the option phases.
hentrmax2
Name of maximum height of P2 entrainment raster map
Name of the input raster map representing the distribution of the maximum height of entrainment of P2. The unit is metres. This parameter is ignored if the mixture or one-phase model is activated through the option phases.
hentrmax3
Name of maximum height of P3 entrainment raster map
Name of the input raster map representing the distribution of the maximum height of entrainment of P3. The unit is metres. This parameter is ignored for the mixture or one-phase models (option phases).
hentrmax
Name of maximum height of entrainment raster map
Name of the input raster map representing the distribution of the maximum height of entrainment. The unit is metres. This parameter is used with the mixture and one-phase models (option phases). It can also be employed for the multi-phase model together with the option rhentrmax1.
rhentrmax1
Ratio of maximum height of P1 entrainment
Without flag -m, dimensionless number in the range 0-1 indicating the ratio of maximum height of P1 entrainment out of the maximum total height of entrainment given by the option hentrmax. The remaining fraction is assigned to P3, whereas the entrainable height of P2 is set to zero. 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 option sampling). This parameter is ignored for the mixture or one-phase models (option phases), or when hentrmax is not given.
vhentrmax
Variation of maximum height of entrainment
Two or three comma-separated dimensionless numbers indicating the lower and upper thresholds for the randomization or controlled variation (see option 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 option 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.
density
Densities of the phases
density=2700,1800,1000
Default
2700 for solid
2000 for mixture
1800
1000
friction
Friction parameters associated to each phase
friction=35,20,0,0,0,0,0.05
Default
35
20
3
0
0
0
0
0.05
viscosity
Viscosities of the phases
viscosity=-9999,-9999,-3.0,-9999,-3.0,0.0
Default
-9999
-9999
-3
-9999
-3
0
basal
Parameters governing the interaction of the flow with the basal surface
basal=-7.0,0.05,0.333,0.0
Default
-7.0
0.05
0.0
0.333
3: [0,]
0.0
transformation
Transformation parameters, allowing for example the melting of ice
transformation=0.0,0.0,0.0
Default
0.0
0.0
0.0
dynfric
Dynamic adaptation of friction parameters
dynfric=0.0,-6.0,0.0
Default
0.0
-6.0
0
slideparam
Parameters for mass point model for initial sliding
slidepar=0.0,0.0,0.0
Default
0.0
0.0
0.0
special
Parameters further refining the simulation, recommended to be modified only by advanced users
special=0.0,10,0.12,1,1,1,3,1,0.1,
1,1,1,1,1,0,0,0,1,1,1,10,0,1,1,1
phi1
Name of P1 internal friction angle raster map
Optional input raster map defining the spatial patterns of the internal friction angle of P1 in degrees. If this parameter is not given, and for all raster cells with value -9999, the global value of the internal friction angle is taken from the friction parameters (see option friction). If the internal friction is lower than the basal friction, it is set equal to the basal friction.
phi1
Name of P1 internal friction angle raster map
Optional input raster map defining the spatial patterns of the internal friction angle of P1 in degrees. If this parameter is not given, and for all raster cells with value -9999, the global value of the internal friction angle is taken from the friction parameters (see option friction). If the internal friction is lower than the basal friction, it is set equal to the basal friction.
tufri
Name of turbulent friction raster map
Optional input raster map defining the spatial patterns of the turbulent friction in s2/m. If this parameter is not given, and for all raster cells with value -9999, the global value of the turbulent friction is taken from the friction parameters (see option friction). This parameter is only relevant for the mixture model (model=x.
delta1
Name of P1 basal friction angle raster map
Optional input raster map defining the spatial patterns of the basal friction angle of P1 in degrees. If this parameter is not given, and for all raster cells with value -9999, the global value of the basal friction angle is taken from the friction parameters (see option friction).
delta2
Name of P2 basal friction angle raster map
Optional input raster map defining the spatial patterns of the basal friction angle of P2 in degrees. If this parameter is not given, and for all raster cells with value -9999, the global value of the basal friction angle is taken from the friction parameters (see option friction).
flufri
Name of fluid friction number raster map
Optional input raster map defining the spatial patterns of the fluid friction number, which is related, but not identical to Manning's n, as the fluid friction number is used with the flow height instead of the hydraulic radius. This parameter is useful to consider the effects of roughness of the basal surface. If it is not given, and for all raster cells with value -9999, the global value of the fluid friction number is taken from the friction parameters (see option friction).
ny1
Name of P1 kinematic viscosity raster map
Optional input raster map defining the spatial patterns of the kinematic viscosity of P1, provided as logarithm (base 10). If this parameter is not given, and for all raster cells with value -9999, the global value of the kinematic viscosity is taken from the viscosity parameters (see option viscosity).
ny2
Name of P2 kinematic viscosity raster map
Optional input raster map defining the spatial patterns of the kinematic viscosity of P2, provided as logarithm (base 10). If this parameter is not given, and for all raster cells with value -9999, the global value of the kinematic viscosity is taken from the viscosity parameters (see option viscosity).
ny3
Name of P3 kinematic viscosity raster map
Optional input raster map defining the spatial patterns of the kinematic viscosity of P3, provided as logarithm (base 10). If this parameter is not given, and for all raster cells with value -9999, the global value of the kinematic viscosity is taken from the viscosity parameters (see option viscosity).
centr
Name of entrainment coefficient raster map
Optional input raster map defining the spatial patterns of the empirical entrainment coefficient, provided as logarithm (base 10). If this parameter is not given, and for all raster cells with value -9999, the global value of the entrainment coefficient is taken from the option basal.
cvshear
Name of shear velocity coefficient raster map
Optional input raster map defining the spatial patterns of the shear velocity coefficient, needed with the entrainment models 2 and 3 (see option controls). If this parameter is not given, and for all raster cells with value -9999, the global value of the shear velocity coefficient is taken from the option basal.
deltab
Name of basal friction difference raster map
Optional input raster map defining the difference between the basal friction angles of the basal surface and the flow (weighted average of all phases considered in the simulation). Positive values generally result in deposition, whereas negative values generally result in entrainment of material. This parameter is needed with the entrainment models 2 and 3 (see option controls). If it is not given, and for all raster cells with value -9999, the global value of the basal friction difference is taken from the option basal.
ctrans12
Name of P1-P2 transformation coefficient raster map
Optional input raster map defining the spatial patterns of the empirical transformation coefficient between P1 and P2. The absolute value of the logarithm with base 10 of the coefficient has to be applied, except for 0 which means no transformation. The value has to be preceded by a minus sign for transformation from P2 to P1. If this parameter is not given, and for all raster cells with value -9999, the global value of the coefficient is taken from the transformation parameters (see option transformation).
ctrans13
Name of P1-P3 transformation coefficient raster map
Optional input raster map defining the spatial patterns of the empirical transformation coefficient between P1 and P3. The absolute value of the logarithm with base 10 of the coefficient has to be applied, except for 0 which means no transformation. The value has to be preceded by a minus sign for transformation from P3 to P1. If this parameter is not given, and for all raster cells with value -9999, the global value of the coefficient is taken from the transformation parameters (see option transformation).
ctrans23
Name of P2-P3 transformation coefficient raster map
Optional input raster map defining the spatial patterns of the empirical transformation coefficient between P2 and P3. The absolute value of the logarithm with base 10 of the coefficient has to be applied, except for 0 which means no transformation. The value has to be preceded by a minus sign for transformation from P3 to P2. If this parameter is not given, and for all raster cells with value -9999, the global value of the coefficient is taken from the transformation parameters (see option transformation).
ambdrag
Name of ambient drag coefficient raster map
Optional input raster map defining the spatial patterns of the ambient drag coefficient. If this parameter is not given, and for all raster cells with value -9999, the global value of the ambient drag coefficient is taken from the special parameters (see option special).
impactarea
Name of observed impact area raster map
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.
hdeposit
Name of observed height of deposit raster map
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.
hydrograph
Path(es) to input hydrograph text file(s)
Path to input hydrograph text file. This text file has to consist of seven columns:
- Time passed in seconds
- P1 discharge in cubic metres per second
- P1 flow velocity in metres per second
- P2 discharge in cubic metres per second (0 for one-phase or mixture model)
- P2 flow velocity in metres per second (0 for one-phase or mixture model)
- P3 discharge in cubic metres per second (0 for one-phase or mixture model)
- P3 flow velocity in metres per second (0 for one-phase or mixture model)
An unlimited number of hydrographs may be defined additionally to or instead of the helease height parameters (hrelease, rhreleases, vhrelease, hrelease1, hrelease2, and/or hrelease3).
hydrocoords
Coordinates, lengths, and directions of hydrograph profile(s)
Each hydrograph profile is characterized by a sequence of four numbers:
- x coordinate of the first hydrograph (m);
- y coordinate of the first hydrograph (m);
- profile length of the first hydrograph (m);
- aspect of the first hydrograph,expressed as the flow direction in degrees, starting from east-west in anti-clockwise direction. -9999 can be entered to align the hydrograph perpendicular to the steepest slope.
This sequence is repeated for the second hydrograph and so on. All entries are separated by commas. If more pairs of coordinates than input hydrographs (option 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.
thresholds
Threshold parameters.
thresholds=0.1,10000,10000,0.001
sampling
Sampling strategy for multiple model runs
sampling=100
This parameter is only applicable along with the flag m. It defines the type of sampling of the options vhrelease, rhreleases, vhentrmax, rhentrmaxs, density, friction, viscosity, ambient, transformation, and special: 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 varied parameter. This means that the actual number of model runs is the product of the sample sizes associated to all the varied parameters.
time
Time interval for output and end time
time=10,300
Two comma-separated floating point numbers. The first number indicates the real-time interval in seconds at which output information is displayed and written to files. The second numer indicates the real time in seconds after which the simulations stops.
slomo
Factor for time scaling (slow motion)
slomo=1
Time scaling can be used for the simulation of very viscous, slow moving one-phase flows of fine solid or fluid material. Setting slomo to a value larger than 1 means that the time is not measured in seconds, but in seconds multiplied with the value provided. slomo=86400 would scale the time from seconds to days, resulting in output velocities of metres per day. However, please note that such changes of units are not indicated in the output data. The time scaling function is still experimental and needs more testing.
cfl
Control of time step length
cfl=0.4,0.001
Two comma-separated floating point numbers governing time step length (optional):
- CFL criterion: a number which has to be lower than or equal to 0.5. The default value is 0.25.
- Time step length in seconds used if the CFL criterion is not applicable (e.g. start of the simulation). The default is 0.001 seconds. If initial sliding is used for the entire area of interest (see option tslide), it is recommended to set this parameter to something around 0.1-0.5 seconds, in order to avoid unnecessarily short time steps.
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.
profile
Coordinates of profile vertices
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.
ctrlpoints
Coordinates of control points
An unlimited number of control points for which the 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).
reftime
Reference time of reach for each control point
Optional parameter containing comma-separated values indicating the observed travel times (times of reach) to each control point in seconds. The number of values has to correspond to the number of control points. This parameter is only used with the flag m and the option ctrlpoints. The ratio between the simulated time of reach and the observed time of reach is included in the evaluation.
phexagg
Factor for exaggeration of flow height
phexagg=1.0
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.
orthophoto
Background orthophoto for map plots
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.
Results
r.avaflow 2.4 automatically creates maps, diagrams and animations, and offers interfaces for export.
The names of all output raster maps, folders and files start with the prefix defined by the option prefix. r.avaflow 2.4 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:
- Input files for model evaluation, parameter sensitivity analysis and parameter optimization with the software AIMEC are stored in the subfolder [prefix]_aimec.
- Exported ascii raster maps for use with other software packages are stored in the subfolder [prefix]_ascii.
- Text files are stored in the subfolder [prefix]_files.
- Output hydrographs, maps and derived animations, profile plots and derived animations and ROC Plots are stored in the subfolder [prefix]_plots.
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 options hydrograph and hydrocoords. The folder [prefix]_aimec is only produced with the flag m, whereas 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. Note that, in this case, also the flags a and t may be provided at this point:
r.avaflow -a -v -t prefix=[prefix]
This step is only possible if the output raster maps still exist in the active GRASS mapset (i.e. if the flag k was activated when running the simulation), 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.
GRASS raster maps
Result raster maps stored in the active GRASS Mapset.
Active GRASS Mapset
r.avaflow 2.4 produces the following output raster maps which are, however, stored permanently only with the flag k:
- [prefix]_hflow[timestep]: flow height for the time step [timestep] in metres, one map is produced for each time step;
- [prefix]_vflowx[timestep]: flow velocity in x direction for the time step [timestep] in m/s, one map is produced for each time step (only with flag a);
- [prefix]_vflowy[timestep]: flow velocity in y direction for the time step [timestep] in m/s, one map is produced for each time step (only with flag a);
- [prefix]_vflow[timestep]: flow velocity for the time step [timestep] in m/s, one map is produced for each time step (only with flag a);
- [prefix]_tflow[timestep]: flow kinetic energy for the time step [timestep] in J, one map is produced for each time step (only with flag a);
- [prefix]_pflow[timestep]: flow pressure for the time step [timestep] in Pa, one map is produced for each time step (only with flag a);
- [prefix]_basechange[timestep]: entrained or deposited height (change of basal surface) at the time step [timestep] in m, one map is produced for each time step - deposition is indicated by positive values, entrainment by negative values.
- [prefix]_tsun[timestep]: impact wave or tsunami height of P3 for the time step [timestep] in m. One map is produced for each time step, but only for the multi-phase model with flag t.
- [prefix]_vfront: frontal flow velocity in m/s (weigthed average of all phases).
- [prefix]_r1front: volumetric fraction of P1 at the flow front.
- [prefix]_r3front: volumetric fraction of P3 at the flow front.
- [prefix]_r1max: volumetric fraction of P1 at the time of maximum momentum throughout the entire simulation.
- [prefix]_r3max: volumetric fraction of P3 at the time of maximum momentum throughout the entire simulation.
- [prefix]_vhmax: flow velocity in m/s (weigthed average of all phases) at the time of maximum momentum throughout the entire simulation.
- [prefix]_treach: time of reach. It shows the time in seconds after which the flow first reaches each raster cell, using the mimimum flow height for display (thresholds parameters) as the criterion. Time of reach is also shown in the control points output files.
The number of the phase each map refers to is inserted before [timestep]. Maps without that number refer to the entire flow. Maxima of flow heights, flow kinetic energies, and flow pressures over the entire simulation are provided with the suffix _max. The final values of the flow heights and entrained/deposited heights are provided 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, representing 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 raster cell is equal or larger than the corresponding impact threshold (option 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 maps and preprocessed input maps are also stored as ascii rasters in the folder [prefix]_ascii.
AIMEC input
Files needed for post-processing with the tool AIMEC.
[prefix]_aimec
With the flag m, this folder contains the automatically generated input folders and files for the evaluation, parameter sensitivity analysis and optimization tool AIMEC. In order to enable applying this tool to the results produced by r.avaflow 2.4, the content and structure of this folder should not be manipulated manually.
Ascii rasters
Ascii rasters of result files which can be exported for use in other software packages.
[prefix]_ascii
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.
Text files
Text files describing the simulation and its results.
[prefix]_files
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:
- [prefix]_averages.txt: portion of area of interest with an observed deposit and average of impact indicator index (with flag m only).
- [prefix]_ctrlpoints.txt: IDs, coordinates and selected result raster values (hmax = maximum flow height and the flow heights of all time steps, and hentrmax = maximum height of entrainment and the heights of entrainment of all time steps without flag m; iii = impact indicator index according to flow height with flag m) of all control points specified by the option ctrlpoints.
- [prefix]_directions[phase].txt: Velocities in x and y direction. This file is needed for the construction of arrows indicating flow direction and velocity in the maps stored in the folder [prefix]_maps (not applicable with flag m).
- [prefix]_documentation.txt: summary of the flags and parameters specified when starting the simulation as well as some further parameters needed for constructing the maps and plots in the folders [prefix]_hydrographs, [prefix]_maps and [prefix]_profiles when running r.avaflow 2.4 with the flag v only.
- [prefix]_hydinfo[hydrograph].txt, where [hydrograph] stands for the number of the hydrograph: output hydrograph data for each time step (not applicable with flag m). T = time passed; H = flow height; V = flow velocity; E = height of entrainment/deposition; Q = discharge. Numbers at the end of the headers indicate the phase the column refers to.
- [prefix]_hydprofiles.txt: x and y coordinates of the centre (xC, yC) and terminal points (x1, y1, x2, y2) of all hydrographs. Hydrograph IDs starting with I indicate input hydrograps, hydrograph IDs starting with O indicate output hydrographs. This file is not produced with flag m. The hydrograph profiles along with the IDs are shown in the maps stored in the folder [prefix]_maps.
- [prefix]_nout1.txt: two-line file, in the first line displaying the number of time steps, in the second line the model success (1=success; 2=failure, usually for numerical reasons). With the flag m, one file is produced for each model run, the number of the model run is added to the file name as suffix.
- [prefix]_param.txt: Raw input parameter file created by r.avaflow.py (only without flag m).
- [prefix]_params.txt: This file is produced along with the flag m only. It summarizes the input parameters for all model runs.
- [prefix]_profile.txt: Profile data illustrating elevation, flow height, depth of entrainment and deposition, flow velocity, flow kinetic energy and flow pressure at all time steps along the pre-defined profile (option profile). This file is needed for the construction of the profiles stored in the folder [prefix]_profiles (not applicable with flag m).
- [prefix]_summary.txt: summary file of the simulation, each line documenting the main parameters of each time step. With the flag m, one summary file is produced for each model run, the number of the model run is added as suffix. The content of the summary file(s) is largely identical to the screen output during routing of the flow. With model=1 the meanings of the column headers are: nout: number of time step; nsum: number of internal time step of the routing algorithm (these time steps are very short in order to ensure numerical stability); cfl: indicator for numerical stability (value should be smaller than 0.5); tdim: duration of one internal time step (1/100 s); tsum: time passed since start of the flow (s); dmax: maximum flow depth at time step (m); vmax: maximum flow velocity at time step (m/s); volume: flow volume at time step (cubic metres in the summary file; 1000s of cubic metres on the screen output); ekin: kinetic energy summed up over the entire flow (J in the summary file; MJ on the screen output). Numbers at the end of the headers indicate the phase the column refers to.
- [prefix]_time.txt: computational time (excluding visualization) in seconds.
- [prefix]_evaluation.txt: This file includes some model outcomes, in particular the evaluation scores derived from the comparison of the model results with the observed impact area (option impactarea) or the observed height of deposit (option hdeposit). Thereby, the modelled impact area is defined by the area where the maximum flow height is equal or larger than the threshold defined by the option imparam. The modelled deposit is defined by the area where the flow height at the end of the simulation is equal or larger than the threshold defined by the option imparam.
Plots and animations
Graphic representation of the main simulation results.
[prefix]_plots
- Hydrograph plots are produced for all input and output hydrographs (flow height and discharge) defined by the option hydrocoords, using the data stored in the files [prefix]_hydinfo[hydrograph].txt and [prefix]_hydprofiles.txt. The hydrograph profiles along with the IDs are shown in the maps stored in the folder [prefix]_maps. This file is not produced with flag m.
- Without the flag m, colour layouts of the simulated flow height ([prefix]_hflow[timestep].png), flow kinetic energy ([prefix]_tflow[timestep].png, only with flag a), flow pressure ([prefix]_pflow[timestep].png, only with flag a), height of entrainment/deposition, if applicable ([prefix]_basechange[timestep].png), and impact wave or tsunami height ([prefix]_tsun[timestep].png, , only with flag t) are drawn for each time step [timestep]. They are stored in the sub-folder [prefix]_maps_timesteps. The release area and/or release hydrographs (option hydrocoords) are displayed as well as the flow path (option profile), the observed impact area (option impactarea), the observed deposit (option hdeposit) and the locations and IDs of the control points (option ctrlpoints), if specified. If the option orthophoto is not provided, a hillshade derived from the elevation raster map is shown as background. Otherwise, the orthophoto is shown as background.
- Colour layouts of the maximum values (suffix _max) of flow height, flow kinetic energy and flow pressure (both only with flag a), and impact wave or tsunami height (only with flag t) over the entire simulation, and a map of the final height of entrainment and deposition, if applicable (suffix _fin), as well as a map of the time of reach 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 four 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) as well as the deposition indicator index for maximum flow height ([prefix]_dii_hflow.png).
- Without the flag m, series of vertical profiles following the flow path (option flowpath) are constructed, illustrating the flow height (put on top of the terrain) along with bar plots representing flow velocity ([prefix]_vflow[timestep].png), flow kinetic energy ([prefix]_tflow[timestep].png) and flow pressure ([prefix]_pflow[timestep].png). They are stored in the sub-folder [prefix]_profiles_timesteps. Animated gifs visualizing the complete sequences of profiles are stored at the top level of the folder. The suffix c in the file names of the gifs refers to compressed versions.
- In the case of multiple model runs (flag m and option cores) and the availability of a map of the observed deposit (option hdeposit), 2 ROC Plots relating impact indicator index map to the observed deposition area are created: one plot includes the entire study area ([prefix]_roc.png), the second one uses a normalized area of true negative predictions ([prefix]_rocn.png). The area under the curve AUCROC is displayed as the key indicator for the prediction quality.
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 2.4.
Please cite this site and its content as: Mergili, M., 2014-2020. r.avaflow - The mass flow simulation tool. r.avaflow 2.4 User manual. https://www.avaflow.org/manual.php