r.avaflow
The mass flow simulation tool
r.avaflow 2.2 User manual
by Martin Mergili
r.avaflow 2.2 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, or particularly with the Pudasaini multi-phase flow model (Pudasaini and Mergili, 2019) with complementary empirical functions for entrainment and phase transformations. The starting mass may be defined through raster maps and/or hydrographs. r.avaflow 2.2 includes the possibility to explore multi-core computing environments to run multiple simulations at once as a basis for parameter sensitivity analysis and optimization.
Recent changes
r.avaflow 2.2 includes some substantial changes, compared to r.avaflow 2.0 and 2.1.
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.0 or 2.1, and are therefore familiar with the software.
- 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.2 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.2 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 parameter 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.2 runs on LINUX operating systems. It relies on GRASS 7 and R.
r.avaflow 2.2 was developed and tested on Ubuntu 18.04 LTS, but is expected to work in other LINUX environments, too. It relies on GRASS GIS 7 (Version 7.8 or higher is recommended to ensure compatibility with Python 3, earlier versions are still working with Python 2.7). Installation of r.avaflow 2.2 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.2: 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.2 can be used to automatically install all the software needed on fresh installations of Ubuntu 18.04LTS, and probably also on installations of other LINUX environments. This script is exclusively targeted at the use of Python 3 and GRASS GIS 7.8 or higher. 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.2 can be easily installed through a script provided along with the software.
As soon as all software requirements are fulfilled, the installation of r.avaflow 2.2 is straightforward and just requires a few more steps. Please note that you need administrator rights (access to sudo), and that existing installations of r.avaflow.are overwritten.
- Extract and save the directory r.avaflow somewhere in your home directory.
- Launch a terminal and change to the directory r.avaflow.
- Excecute the script r.avaflow.install.sh as superuser: sudo sh r.avaflow.install.sh
- You will be asked for the administrator password.
- You will be asked for the GRASS GIS 7 and Python versions installed on your system. Note that the script assumes GRASS GIS 7 and Python to be installed in the default directories. In case they are installed somewhere else, you have to manually modify the string variables PATHGRASS, PATHPYTHON and/or PATHDOCS in the installation scripts.
- First, the Python-based modules and R scripts for data management, pre- and post-processing, evaluation, and visualization, and then the C-based module for the simulation of granular avalanches and debris flows will be installed. A message will be printed when the installation has finished. Check for error messages and then press ENTER to complete the installation.
Operation
r.avaflow 2.2 is most efficiently operated through shell scripts.
r.avaflow 2.2 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.2 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.2 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.2 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.2. 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.2. 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 parameter delta1 is provided, the values of the raster map are applied to all pixels where delta1 is not -9999, and the values given by friction are applied to all other pixels. In an analogous way, the same is true for the parameters delta2, delta3, ny1, ny2, ny3, ambdrag, flufri, and centr.
All parameters for P2 and P3 have to be skipped for the one-phase and mixture models. For example, the parameter friction could look as follows for the one-phase model:
friction=35,20
For multiple simulations (flag m), 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 (parameter 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.
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 (parameter 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 map plots of flow pressure and kinetic energy, in addition to the map plots of flow height and change of the basal topography. It is deactivated by default.
-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 (parameters 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 (parameter 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 (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
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 parameter phases. An example of a multi-phase model would be (phasetext=Rock,Ice,Water). By default, the string Solid is used for the solid phase, the string Fine is used for the fine solid phase, and the string Fluid is used for the fluid phase. 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 (parameter elevation).
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 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.
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 parameter 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 parameter 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 parameter 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 (parameter phases). It can also be employed for the multi-phase model together with the parameter 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 parameter 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 parameter sampling). This parameter is ignored for the mixture and one-phase models (parameter 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 parameter sampling) of the release height between different model runs. The resulting number is multiplied with the values of the 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.
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, hrelease, a continuous release is considered and hrelease1, hrelease2, and hrelease3 have to be given in vertical metres per second.
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 parameter 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 parameter 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 parameter 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 parameter 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 parameter 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 parameter 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 (parameter 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 (parameter phases). It can also be employed for the multi-phase model together with the parameter 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 parameter 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 parameter sampling). This parameter is ignored for the mixture or one-phase models (parameter 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 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.
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 pixels with value -9999, the global value of the internal friction angle is taken from the friction parameters (see parameter friction).
phi2
Name of P2 internal friction angle raster map
Optional input raster map defining the spatial patterns of the internal friction angle of P2 in degrees. If this parameter is not given, and for all pixels with value -9999, the global value of the internal friction angle is taken from the friction parameters (see parameter friction).
phi3
Name of P3 internal friction angle raster map
Optional input raster map defining the spatial patterns of the internal friction angle of P3 in degrees. If this parameter is not given, and for all pixels with value -9999, the global value of the internal friction angle is taken from the friction parameters (see parameter friction).
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 pixels with value -9999, the global value of the basal friction angle is taken from the friction parameters (see parameter 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 pixels with value -9999, the global value of the basal friction angle is taken from the friction parameters (see parameter friction).
delta3
Name of P3 basal friction angle raster map
Optional input raster map defining the spatial patterns of the basal friction angle of P3 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 friction parameters (see parameter friction).
ny1
Name of P1 viscosity raster map
Optional input raster map defining the spatial patterns of the viscosity of P1, provided as logarithm (base 10). If this parameter is not given, and for all pixels with value -9999, the global value of the viscosity is taken from the viscosity parameters (see parameter viscosity).
ny2
Name of P2 viscosity raster map
Optional input raster map defining the spatial patterns of the viscosity of P2, provided as logarithm (base 10). If this parameter is not given, and for all pixels with value -9999, the global value of the viscosity is taken from the viscosity parameters (see parameter viscosity).
ny3
Name of P3 viscosity raster map
Optional input raster map defining the spatial patterns of the viscosity of P3, provided as logarithm (base 10). If this parameter is not given, and for all pixels with value -9999, the global value of the viscosity is taken from the viscosity parameters (see parameter viscosity).
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 pixels with value -9999, the global value of the ambient drag coefficient is taken from the ambient parameters (see parameter ambient).
flufri
Name of fluid friction coefficient raster map
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 ambient parameters (see parameter ambient).
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 pixels with value -9999, the global value of the entrainment coefficient is taken from the ambient parameters (see parameter ambient).
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 pixels with value -9999, the global value of the coefficient is taken from the transformation parameters (see parameter 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 pixels with value -9999, the global value of the coefficient is taken from the transformation parameters (see parameter 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 pixels with value -9999, the global value of the coefficient is taken from the transformation parameters (see parameter transformation).
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)
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.
density
Densities of the phases
density=2700,1800,1000
2000 for mixture
friction
Internal friction and and base friction angle associated to each phase
friction=35,20,15,5,0,0
viscosity
Viscosities of the phases
viscosity=-9999,-9999,-3.0,-9999,-3.0,0.0
ambient
Parameters governing the interaction of the flow with the atmosphere and the basal surface
ambient=0.02,0.004,-7.0,0.0
transformation
Transformation parameters, allowing for example the melting of ice
transformation=0.0,0.0,0.0
special
Parameters further refining the simulation, recommended to be modified only by advanced users
special=10,0.12,1,1,1,3,1,0.1,
1,1,1,1,1,0,0,0,1,1,1,10,0,0,1,1,1
dynfric
Dynamic adaptation of friction parameters
dynfric=2.0,1000000
controls
Control parameters.
controls=0,0,0,0,0,0
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 parameters 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.
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 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).
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.2 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 parameter prefix. r.avaflow 2.2 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 parameters 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.2 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 direction of the flow path for the time step [timestep] in m/s, one map is produced for each time step;
- [prefix]_vflowy[timestep]: flow velocity normal to the flow path for the time step [timestep] in m/s, one map is produced for each time step;
- [prefix]_vflow[timestep]: flow velocity for the time step [timestep] in m/s, one map is produced for each time step;
- [prefix]_tflow[timestep]: flow kinetic energy for the time step [timestep] in J, one map is produced for each time step;
- [prefix]_pflow[timestep]: flow pressure for the time step [timestep] in Pa, one map is produced for each time step;
- [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.
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 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 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.2, 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 parameter 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.2 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 (parameter 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 (parameter impactarea) or the observed height of deposit (parameter 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 parameter 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 parameter 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 parameter 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 (parameter hydrocoords) are displayed as well as the flow path (parameter profile), the observed impact area (parameter impactarea), the observed deposit (parameter hdeposit) and the locations and IDs of the control points (parameter ctrlpoints), if specified. If the parameter 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), 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 (parameter 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 parameter cores) and the availability of a map of the observed deposit (parameter 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.2.
Please cite this site and its content as: Mergili, M., 2014-2020. r.avaflow - The mass flow simulation tool. r.avaflow 2.2 User manual. https://www.avaflow.org/manual.php