r.avaflow.direct Web interface
by Martin Mergili
r.avaflow.direct offers a convenient web interface for the preparation of r.avaflow 3 simulations. With its integrated manual, it guides users through the process step-by-step. Simulations are then run locally, either on Windows or on Linux, supported by automatically generated start scripts. Optional visualization interfaces are available for R (ground plots, profiles, diagrams) and Paraview (3D scenes) as well as Blender and Unreal Engine (3D scenes and virtual reality).
Please choose below your preferred software environment for r.avaflow. The C code used for the flow simulation is essentially identical in both releases. And, of course, all components of r.avaflow are fully open-source.
If you have questions regarding the use of r.avaflow, please directly contact martin.mergili@uni-graz.at. However, be aware that r.avaflow is no commercial software, and the resources for support are extremely limited. Please carefully read the manual and consult the FAQ section before asking questions, and note that no support for basic issues on the installation of r.avaflow and its software prerequisites can be provided. I will try to react to all other support requests as quickly as possible, but please understand that I have various other responsibilities, so that my answers might be delayed.
Get ready for using r.avaflow with GRASS
r.avaflow 3G runs on LINUX operating systems. It relies on GRASS GIS and some further software packages. Please note that the consistent installation of all required software prerequisites may represent a challenge for non-experienced users. If you work within an organization, it is recommended to consult with your IT specialist. In detail, the requirements and recommendations are as follows:
- The operating system Ubuntu 20.04 LTS. r.avaflow 3G is expected to work in other LINUX environments, too, but this cannot be guaranteed.
- The GIS software GRASS version 7.8 or higher. Installation of r.avaflow 3G requires the grass-dev and grass-doc packages.
- The programming language Python 3
- The R Project for Statistical Computing (recommended version: 4.2.3 or higher). The following packages of R are required in order to fully explore the functionalities offered by r.avaflow3G: stats, codetools, Rcpp, terra, lattice, sp, raster, and ROCR.
- The Python Imaging Library Pillow
Advanced 3D visualization of the r.avaflow simulation results (including immersive VR gaming applications) requires the following programmes:
- The visualization software Paraview (recommended version: 5.11 or higher)
- The 3D computer graphics software tool Blender (recommended version: 3.4 or higher)
- The 3D computer graphics game engine Unreal Engine (recommended version: 5.1 or higher)
These programmes can be installed on Windows systems as they are not directly used within r.avaflow simulations. Instead, the simulation results can be imported through Python scripts automatically generated by r.avaflow.
The script grass.install.sh provided along with r.avaflow 3G can be used to automatically install all the software needed on fresh installations of Ubuntu 20.04 LTS, 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. 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 grass.install.sh
As soon as all software requirements are fulfilled, the installation of r.avaflow 3G is straightforward, using the built-in GRASS module g.extension. Please download the latest source code of r.avaflow 3G: Assuming that the folder with the r.avaflow source code is stored in the directory /home/user1/, installation just requires starting GRASS GIS in any location of your choice, and the execution of the following command:
g.extension extension=r.avaflow url=/home/user1/r.avaflow/
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/scriptsand /usr/lib/grass78/bin in order to make sure that the r.avaflow command really calls the newly installed version.
Please note that no support can be provided until this point. Users are expected to manage the installation of the software prerequisites and r.avaflow by themselves or with their own IT support. Further, a basic understanding of the principles of GRASS GIS is expected. All support requests are expected to be founded on a proper installation of r.avaflow and the successful completion of the training examples.
Get ready for using r.avaflow on Windows
r.avaflow 3W represents a stand-alone tool that runs on Windows systems (Windows 10 and 11) and needs a minimum of software requirements. As the executable file r.avaflow.exe was created from the source r.avaflow.main.c using Cygwin, the file cygwin1.dll is required as a prerequisite. No other specific programmes or libraries are necessary. However, the open-source tools Paraview and The R Project for Statistical Computing can be used for the visualization of the model results.
Advanced 3D visualization of the r.avaflow simulation results (including immersive VR gaming applications) requires the 3D computer graphics software tool Blender (recommended version: 3.4 or higher) and the 3D computer graphics game engine Unreal Engine (recommended version: 5.1 or higher). They are not directly used within r.avaflow simulations. Instead, the simulation results can be imported through Python scripts automatically generated by r.avaflow.
You also have to install Cygwin, or just download the file cygwin1.dll from a repository of your choice. Make sure that you know the directory where you have stored cygwin1.dll. If you have installed Cygwin, this will be the lib directory in your Cygwin installation (e.g., C:/cygwin64/lib/).
Please note that no support can be provided until this point. Users are expected to manage the installation of the software prerequisites and r.avaflow by themselves or with their own IT support. All support requests are expected to be founded on a proper installation of r.avaflow and the successful completion of the training examples.
Further, be aware that r.avaflow 3W works for small study areas only: on most systems, raster sizes up to approx. 40,000 cells are supported. The system may crash if the software is executed with larger rasters. No responsibility for damages to data, software, or hardware can be accepted in such cases. Please use r.avaflow 3G for larger study areas.
Develop and save your start script
Develop and save your parameter file
A large choice of parameters is available as input for r.avaflow, organized into various categories. You can expand the corresponding parameters by clicking on the category names below. Below, you can filter the parameter list depending on the type of model you intend to use (mixture model, one-phase model, or multi-phase model). Alternatively to starting from scratch, you can also import a parameter file from a previous simulation and modify it according to your needs. However, please note that parameter files always refer to single model runs and will therefore provide only incomplete input if multiple simulations (flag -m) are intended with r.avaflow 3G. Whichever way you choose - when completed, you can merge all parameters into a a start script named [prefix].avaflow.start.sh (for r.avaflow 3G) or a parameter file named [prefix]_param1.txt (for r.avaflow 3W), where [prefix] stands for the prefix parameter of the simulation and which will be stored in the default download directory of your web browser.
The training examples include some data and parameter files for mixture, one-phase, and multi-phase simulations.
Before moving on, you should make sure the following:
- All the input maps needed for the simulation have to be ready as ascii or tiff rasters. Store all your raster maps and text files in one directory of your choice, to be specified through the parameter indir.
- You have to know the default download directory of your web browser. All old versions of [prefix].avaflow.start.sh have to be removed from your browser's default download directory. Depending on the settings, your newly created sh file might otherwise be assigned an inappropriate file name.
Before moving on with the next steps, you should make sure the following:
- All the input maps needed for the simulation have to be ready as ascii rasters with exactly the same spatial extent and cellsize, i.e. the headers and the numbers of rows and columns have to be identical. Please consult the training data for the exact formatting required. Store all your ascii rasters and text files in one directory of your choice, to be specified through the parameter indir.
- You have to know the default download directory of your web browser. All old versions of r.avaflow.exe, [prefix]_avaflow.cmd, and the parameter file [prefix]_param1.txt have to be removed from your browser's default download directory. Depending on the settings, your newly created txt and cmd files might otherwise be assigned inappropriate file names.
Not all parameters are needed for all types of simulations - in fact, simple simulations can be performed with very little input, as almost all parameters are equipped with default values. You have to provide at least
- a prefix as the identifier for your simulation (parameter prefix),
- an elevation raster map (parameter elevation),
- and a release height raster map or an input hydrograph (parameters hrelease1, hrelease2 and/or hrelease3, or parameters hydrograph and hydrocoords)
to run a simulation. The directory where the input data are located (parameter indir) is needed with r.avaflow 3W and recommended with r.avaflow 3G. The mixture and one-phase models are best suitable for simulations of ordinary landslide processes such as debris flows, earth flows, or rock avalanches. The multi-phase model has to be used in those cases where landslides interact with glaciers or water bodies, or where erosion or phase transformation processes lead to a notable change of the flow characteristics (parameter model with r.avaflow 3W). Thereby, it is recommended to define the material as solid or fluid. Fine-solid material should only be applied by very experienced users (parameter phases).
The main governing parameters are the basal friction angle and the turbulent friction for mixtures, the basal friction angle for solid material and the fluid friction number (Manning's n) for fluid material (friction parameters). The kinematic viscosity is important for slow flows (viscosity and slomo parameters). Please check carefully which further parameters you need for your specific simulation, and replace the default values by more suitable entries, where needed.
Also note that r.avaflow is quite sensitive to the quality of the input raster data. Most importantly, it is absolutely necessary that flat water surfaces are really absolutely flat also in their representation as raster maps. Otherwise, simulations might result in an unexpected dynamic behaviour of the water. The tool r.lakefill provided along with r.avaflow 3G can be used to automatically create appropriate fluid release raster maps. Further, note that release raster maps (parameters hrelease1, hrelease2, and hrelease3) are always imposed on the elevation raster map (parameter elevation). This means that the elevation raster map has to represent the basal surface of the release mass (e.g. sliding surface or lake bottom). In those cases where the elevation map shows the surface of the release mass, it has to be preprocessed accordingly, i.e. reduced by the release mass, before being used for r.avaflow simulations.
Mixture model
One-phase model
Multi-phase model
Clear filter
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.
Run your simulation with the start script
r.avaflow3 is most efficiently operated through shell scripting, using the start script produced in the previous step. You will not use the GUI of GRASS, but work in the terminal. 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 call GRASS from the terminal and to create a GRASS location with a Generic XY coordinate system. You do not have to define the spatial extent of the location, and you can work with the default PERMANENT mapset (no need to create a new mapset). The command line prompt should start with the GRASS version and, in brackets, the location. If this is the case, it means that you are really in GRASS. You can now change to the directory where your start script is stored, and execute the script:
cd [directory with start script]
sh [prefix].avaflow.start.sh
The automatically generated start script contains the following series of commands:
- The script will first make sure that the default region of the location is restored, just to be on the safe side for the case that it has been previously modified (command g.region -d).
- Then, the ascii or tiff rasters are converted to GRASS raster maps (command r.in.gdal).
- The default region is set to the extent and cell size of the elevation raster map (command g.region -s rast=[elevation]).
- r.avaflow is computed with all the previously set parameters as arguments (command r.avaflow)
- The default region is restored (command g.region -d).
Experienced users might prefer to create start scripts manually, or to modify the automatically generated scripts, enabling a high level of flexibility of combining r.avaflow simulations with other functionalities of GRASS. It is, for example, possible to concatenate various calls to r.avaflow, to automatically execute several simulations with different input. But you can also add other GRASS commands. For example, you can create generic landcapes (command r.mapcalc), preprocess raster maps (command r.mapcalc), or compute statistics of deposited volumes (command r.volume). Examples of such start scripts can be found in the training data.You can go for a beer, to sleep, or even on holiday, and see the results when you have returned, without any intervention required in between.
You can find the folder with the results of the simulation in the same directory as the start script.
Create a start script and run your simulation
The start script [prefix]_avaflow.cmd, along with the executable r.avaflow code r.avaflow.exe, will be stored in the default download directory of your browser.
You can now run the simulation by double-clicking [prefix]_avaflow.cmd, opening the command line interface. Note that you will probably receive a warning that the programme is potentially harmful to your computer, which you have to override. Also note that, in case that the simulation fails for some reason, the command line window will close immediately. Alternatively, you can start the command line interface and execute [prefix]_avaflow.cmd there, with the advantage that the Window does not close immediately if the simulation fails , so that you can inspect the error message. In both cases, the parameter file [prefix]_param1.txt will be copied to your working directory as param1.txt, which is the mandatory name of r.avaflow parameter files. Old parameter files in the working directory will be deleted, and old result folders with the same prefix will be deleted, too. You will have to confirm the deletion in the command line interface. The simulation will then start and the command line interface will keep you updated about the progress as long as the simulation is running. The simulation results will be stored in your working directory.
Explore and visualize your simulation results
r.avaflow produces a set of of asc, txt, png, gif, and csv files as well as py and cmd scripts stored in subfolders of the folder [prefix]_results. The names of most output files start with the prefix defined by the parameter prefix.
- Exported ascii raster maps for use with GIS software are stored in the subfolder [prefix]_ascii.
- GRASS rasters are stored in the active GRASS mapset.
- Text files are stored in the subfolder [prefix]_files.
- Output hydrographs, maps and derived animations, profile plots and derived animations, ROC Plots, and further plots generated with R are stored in the subfolder [prefix]_plots.
- Input files for model evaluation, parameter sensitivity analysis and parameter optimization with the software AIMEC are stored in the subfolder [prefix]_aimec.
- Comma-delimited text (csv) files are stored in the folder [prefix]_vr. They can directly be converted to Paraview visualization files through the automatically generated script pvimport.py or to Blender meshes and objects through the automatically generated script blimport.py. Further, animations (level sequences) in Unreal Engine can be generated from imported Blender meshes through the automatically generated script unimport.py.
Ascii rasters
Ascii rasters of result files which can be exported for use in most GIS programmes
[prefix]_ascii
r.avaflow.direct produces the following output ascii raster maps which can be visualized and further processed with your preferred GIS software package.
- [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 output control set to 1.
- [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 output control set to 1.
- [prefix]_vflow[timestep]: flow velocity for the time step [timestep] in m/s, one map is produced for each time step, only with output control set to 1.
- [prefix]_tflow[timestep]: flow kinetic energy for the time step [timestep] in J, one map is produced for each time step, only with output control set to 1.
- [prefix]_pflow[timestep]: flow pressure for the time step [timestep] in Pa, one map is produced for each time step, only with output control set to 1.
- [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 tsunami control set to 1.
- [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 as the criterion. The time of reach is also shown in the control points output file.
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.
In addition to the output maps, some input raster maps are also stored as ascii rasters.
GRASS rasters
GRASS rasters of result files
Active GRASS mapset
With r.avaflow 3G, all those raster maps stored as ascii rasters are also stored as GRASS rasters in the active GRASS mapset. However, the flag -k has to be provided to use them after the end of the simulation - otherwise, they are deleted as soon as the simulation has finished.
Text files
Text files describing the simulation and its results
[prefix]_files
The following text files summarize the simulation or are needed for the visualization interfaces.
- [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 of all control points specified by the parameter ctrlpoints.
- [prefix]_directions[phase].txt: Velocities in x and y direction. This file can be used for the visualization of flow directions and velocities.
- [prefix]_hydinfo[hydrograph].txt, where [hydrograph] stands for the number of the hydrograph: output hydrograph data for each time step. 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.
- [prefix]_nout1.txt: some parameters needed for the visualization interfaces.
- [prefix]_paramcomm.txt: Commented input parameter file.
- [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.
- [prefix]_summary.txt: summary file of the simulation, each line documenting the main parameters of each time step. The content of the summary file 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 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 defined threshold flow height for display. 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 minimum flow height for display.
R plots
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.
- 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.
- 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.
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, the content and structure of this folder should not be manipulated manually.
Virtual reality interface
Comma-delimited (csv) files and scripts supporting the visualization of your results with Paraview, Blender, and Unreal Engine
[prefix]_vr
A set of csv files (one for each time step) is stored within the subfolder data. These files contain information optimized for 3D visualization in Paraview, Blender, and Unreal Engine.
- The csv files cannot directly be used in the Paraview environment, but have to be converted to an appropriate format. This can be done with the automatically generated script pvimport.py, which creates file sets for the representation of the surface as well as contour lines of flow height (or tsunami height, if the tsunami control is set to 1) and terrain height (including the first phase of the flow). Please note that pvimport.py cannot be run with ordinary Python, but only with the Python associated to Paraview (pvpython), which has to be installed on your computer before executing the script. If you have provided the Name of the pvpython installation through the parameter visualization, a cmd file (pvimport.cmd) will be available along with the Python script, the execution of which directly runs the Python script with pvpython. When the import is completed, you can open Paraview and load the surface.vtp (terrain and flow representation), contoursh.vtp (flow height or tsunami contours) and contoursz.vtp (elevation contours) datasets. Note that, for the surface.vtp layer, you have to select the rgb column for the symbology, and deselect the Map scalars box.
- The script blimport.py can be used in the scripting interface of Blender to generate a series of 3D meshes, one for each output time step of the simulation. Make sure that, before running the script, a light object named Light and a camera object named Camera are available in the active scene. Colouring of the meshes is implemented as vertex colours, prescribed by the rgb column of the csv files (set through the parameter visualization and the choice of orthophoto or hillshade as background). Export of the scene as a sequence of standard, anaglyph, or stereo 3D views is optional (to be activated in the Python script), light and camera parameters have to be manually adjusted in the script. The exported views can be combined to videos with any suitable video editing software (examples of such videos can be found at the YouTube playlist movemont.at). Further, it is optional to create an animation directly in Blender. If activating this option in the Python script, you have to create an armature object named Armature before.
- The script unimport.py can be used in the Python interface of Unreal Engine as soon as the meshes generated in Blender have been imported to Unreal Engine, and a new Level Sequence has been created. This Python script creates an animation (level sequence) that can be used, for example, in gaming applications. Manual adjustments to the script and the created animation may be necessary.
Browse through a selection of frequently asked questions (FAQ)
Which types of processes can I simulate with r.avaflow?
In principle, r.avaflow is suitable for the simulation of all types of mass flows. However, it was particularly designed, and most extensively tested, for complex geomorphologic process chains in mountain areas, such as landslide-triggered glacial lake outburst floods. r.avaflow can also be used for the simulation of ordinary debris flows or flow-like snow avalanches, but comparative simulations have shown that there are commercial software packages such as RAMMS that outperform r.avaflow, and come up with comprehensive guiding parameter sets, a service that cannot yet be provided for r.avaflow. Further, some tests have shown that r.avaflow is not very well suitable for the numerical reproduction of laboratory experiments.
The availability of Paraview, Blender, and Unreal Engine interfaces for 3D visualization, and the functions for slow processes make r.avaflow particularly suitable for the flexible demonstration of different types of phenomena for the purpose of environmental education.
What are the criteria for choosing between the mixture model, the one-phase model, and the multi-phase model?
The mixture and one-phase models are best suitable for simulations of ordinary landslide processes such as debris flows, earth flows, or rock avalanches. The multi-phase model has to be used in those cases where landslides interact with glaciers or water bodies, or where erosion or phase transformation processes lead to a notable change of the flow characteristics. Thereby, it is recommended to define the material as solid or fluid. Fine-solid material should only be applied by very experienced users (parameter phases).
Which data do I need to run r.avaflow simulations?
r.avaflow can be run with a complex combination of model input - however, not all parameters are needed for all types of simulations. Simple simulations can be performed with very little input, as almost all parameters are equipped with default values. You have to provide at least
- a prefix as the identifier for your simulation (parameter prefix),
- an elevation raster map (parameter elevation),
- and a release height raster map or an input hydrograph (parameters hrelease1, hrelease2 and/or hrelease3, or parameters hydrograph and hydrocoords)
to run a simulation. When working with the Windows-based version, you also have to provide the directory where the input data are located (parameter indir).
The main governing parameters are the basal friction angle and the turbulent friction for mixtures, the basal friction angle for solid material and the fluid friction number (Manning's n) for fluid material (friction parameters). The kinematic viscosity is important for slow flows (viscosity and slomo parameters). Please check carefully which further parameters you need for your specific simulation, and replace the default values by more suitable entries, where needed.
Which projection should I use for my simulation?
r.avaflow does not care about projections. It is important that all your input raster maps and coordinates (e.g., profile or hydrocoords)are provided in the same metric coordinate system, but the coordinate system itself does not have to be defined. r.avaflow always assumes that all horizontal dimensions, such as the cell size, are metres (the same is true for all vertical or slope-parallel dimensions), so you should NOT use data which are in a geographic coordinate systems with degrees as units. When using r.avaflow with GRASS, it is strongly recommended to use a generic XY coordinate system.
How do I properly prepare my release height maps?
The release height maps defined through hrelease, hrelease1, hrelease2, and/or hrelease3 have to contain positive numbers (release heights) for all raster cells from which there should be landslide release, and zero (NOT no data) for all raster cells where there should be no landslide release. Note that you should carefully check that all cells outside from the release area are REALLY EXACTLY ZERO, and not some small value. This is particularly important if you build the release area map(s) from differencing of pre- and post-event elevation maps, where even small inaccuracies may lead to non-zero values despite identical pre- and post-event terrain elevation. The spatial extent of the release height map(s) has to be exactly the same as the spatial extent of the elevation map (option elevation).
Further, make sure that your elevation map represents the BASAL SURFACE of the release mass, i.e., the sum of the elevation map and the release height map(s) have to represent the terrain height before the event for each raster cell. If you include a lake in your simulation, make sure that the lake surface is EXACTLY plane, otherwise the lake surface will start moving around without landslide impact. However, note that some minor oscillations of lake surfaces may also occur in case of a properly defined, exactly plane, initial surface, due to numerical reasons.
Which value should I provide for the width of my output hydrograph?
Your output hydrograph should be wide enough to cross the entire flow at any time of the simulation. All hydrograph profiles are displayed in the output R plots, so that you can check at the end of your simulation whether you have chosen an appropriate width.
My output hydrograph shows negative discharge values. How can that happen?
Negative discharge values occur when the flow moves against the flow direction used for the definition of the hydrograph profile. Most commonly, this occurs when the flow collects in a depression (which might be real, or the consequence of an artifact in the elevation raster map). But, negative discharge values might also point to a misplaced or inappropriately oriented hydrograph profile.
Phase 2 material does appear in my simulation results, even though I did not provide a phase 2 release mass or input hydrograph. What happened?
Most likely, you have activated entrainment, but not provided an appropriate combination of the options hentrmax, hentrmax1, hentrmax2, hentrmax3, and/or rhentrmax. In this case the model assumes that one third of the basal surface consists of each phase. As soon as the maximum depth of entrainment has been specified for at least one phase, no material of those phases for which the maximum depth of entrainment is not given will be eroded and entrained.
What do I have to do to properly consider entrainment in r.avaflow simulations?
Technically, you just have to activate the entrainment control in the control parameters. If you do so, the basal surface of the flow will be eroded and incorporated into the flow (entrained) according to a simple model where an entrainment coefficient is multiplied with the flow momentum. The default entrainment coefficient is set to -7.0 (which is the base 10-logarithm of the actual value). It can be adjusted through the option basal. There is no limit of the depth of entrainment and with the multi-phase model, it will be assumed that one third of the basal surface consists of each phase. If you would like to constrain erosion and entrainment to a certain depth or to certain phases, you can do so through the options hentrmax, hentrmax1, hentrmax2, hentrmax3, rhentrmax, and/or ventrmax1. As soon as the maximum depth of entrainment has been specified for at least one phase, no material of those phases for which the maximum depth of entrainment is not given will be eroded and entrained.
I have provided the impactarea and/or the hdeposit raster, but there are no meaningful evaluation results (all values in the [prefix]_evaluation.txt file are -9999). What is the reason for this?
Make sure that, in your impactarea raster, all cells with observed impact have the value 1, and all cells without observed impact have the value 0. In your hdeposit raster, all cells with observed deposition should represent the height of the observed deposition (even though, just for the evaluation, the exact value does not matter and the cells can just have any value larger or equal than the first value of the thresholds parameter), and all cells without observed deposition should have the value 0.
Note that there is a big difference between 0 and no data. It is a very common mistake that the no data value is assigned to those cells without observed impact or deposition, instead of zero. However, the no data value should only be given to those cells where it is not known whether there was an impact or deposition, or not.
Please cite this site and its content as: Mergili, M., 2014-2023. r.avaflow - The mass flow simulation tool. r.avaflow.direct Web interface. https://www.avaflow.org/direct.php