r.avaflow.direct Web interface

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.

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.

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.

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.

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.

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.

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

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?

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.