Cascadia Generic Landscape

Cascadia is a generic high-mountain landscape. It is the digital representation of a physical landscape and geomorphological process model located at the University of Graz, Austria. It allows for the simulation and visualization of different types of high-mountain processes and process chains, including landslides, debris flows, floods, rock glaciers, deep-seated gravitational slope deformations, and glacial lake outburst floods. The landscape characteristics and the initial conditions are defined by a set of raster maps and hydrographs as well as a frictiograph. The start script for r.avaflow 3G includes a sequence of nine simulations, whereas four parameter files are provided for r.avaflow 3W.

Data and start script for r.avaflow 3G Data and parameter files for r.avaflow 3W

Acheron Rock Avalanche

The Acheron Rock Avalanche is a prehistoric event that occurred approx. 1100 years BP in Canterbury, New Zealand. It is characterized by an estimated volume of 6.4 million cubic metres and a travel distance of approx. 3.55 km. The flow path displays a sharp bend, and lateral spreading to some tributary valleys was limited. This example is used to test r.avaflow for rock avalanches, exploring the possibility of multiple parallel model runs and the complementary function for stopping. Some experiments performed on the Acheron Rock Avalanche are described in detail by Mergili et al. (2017).

Data and start script for r.avaflow 3G Data and parameter files for r.avaflow 3W

r.lakefill

Python-based GRASS GIS module for filling depressions in the terrain with water. The following parameters are required to run r.lakefill:

• cellsize: raster cell size for computation. Please apply the same cellsize as for r.avaflow simulations using the output. Otherwise, the lake surface might not be perfectly plane, which would result in numerical oscillations.
• elevation: name of input GRASS raster map representing the terrain surface (usually in metres asl).
• lakedepth: name of output GRASS raster map of the computed lake depth (usually in metres). In r.avaflow, this raster can be used as the fluid release height (parameter hrelease3).
• level: lake level (usually in metres asl). Note that the lake level has to be lower than or equal to the lowest point surrounding the depression to be filled in order to achieve the desired result.
• seedcoords: Two comma-separated values describing the x and y coordinates (usually in metres) of an arbirary location within the depression to be filled. The point defined by these coordinates will be used as seed for filling the depression.

The module is executed through the terminal by calling its name along with the parameters. It is used in the start script of the Cascadia training example. Another possible example:

r.lakefill cellsize=5 elevation=test_elev lakedepth=test_lakedepth level=4256 seedcoords=483370,5120580

The most fundamental changes in r.avaflow 3, compared to r.avaflow 2.4pre, are indicated below. This list is most useful for those users which have already been working with r.avaflow 2.4pre.

• An important bug has been fixed: in the older r.avaflow versions, the dynamic flow pressure had been computed incorrectly, resulting in roughly half of the correct value.
• r.avaflow 3 is fully compatible with GRASS 8 while maintaining compatibility with GRASS 7.8. The GRASS-based versions of r.avaflow 3 are released as r.avaflow 3G with the corresponding release date, but without subversion numbers. The new r.avaflow.direct web interface can be used to generate the input for r.avaflow 3G, but also for the Windows-based r.avaflow 3W releases which are, however, only applicable to case studies of limited size. Please always use the latest release of r.avaflow 3G or r.avaflow 3W, which can both be downloaded through r.avaflow.direct. Previous releases of r.avaflow 3G can be accessed directly by the release date: e.g., for downloading the version of 8 April 2023, please access https://www.landslidemodels.org/r.avaflow/software/r.avaflow3G_20230408.zip through the web browser of your preference. Older versions of r.avaflow can be downloaded below on this page, along with the corresponding manuals.
• All R scripts for visualization are now produced directly within r.avaflow during each simulation, and are not part of the r.avaflow releases any more. Execution of the R scripts runs quietly, without warning messages. Dependencies on deprecated R packages such as rgdal have been removed.
• 3D visualization and virtual reality (VR) interfaces. A set of output csv files contains information optimized for 3D visualization in Paraview, Blender, and Unreal Engine. The automatically generated Python scripts pvimport.py, blimport.py, and unimport.py facilitate the import of the csv files to the corresponding 3D animation and gaming software packages. Blender supports the composition of time series of standard, anaglyph, or 3D visualizations as well as immersive VR scene inspection (the latter depending on the availability of a gaming-ready computer and a VR headset). Unreal Engine allows to include r.avaflow simulation results in VR game development.
• The function for initial sliding (options tslide and slidepar) has been modified: r.avaflow 3 uses global values of topographic slope and therefore the gravity components, until the point in time defined by the cell values of the tslide raster map. This approach considers sliding of the moving mass as a rigid block, with internal deformation limited to numerical effects. It can be used to simulate the initial stage of a landslide before it evolves into a flow-type movement (e.g., a rock slide disintegrating to a rock avalanche). However, this sliding model often has to be combined with the flow model in order provide plausible results. The option slidepar allows to control the slide and flow components and their evolution in time. Initial sliding can be combined with the layer mode (option layers).
• Slow-flow model (option slomo): time scaling can be used for the simulation of very viscous, slow moving flows. If slomo is set to a value larger than 1, r.avaflow switches from a mass and momentum balance approach to an equilibrium velocity approach. In this case, the friction parameters are neglected, and the viscosity parameters are employed to compute, for each time step and each raster cell, the flow velocity evolving in equilibrium of accelerating gravity and decelerating viscosity. One-phase and multi-phase flows can be considered in the slow-flow model, but the definition of the individual phases is neglected, and all phases are treated equally. The meaning of the values provided through the option viscosity is partly different to the momentum balance model. Depending on the specific case, it might be very useful to combine the slow flow mode with the layer mode (layers=1) and/or the model for initial sliding (options tslide and slidepar). With the slow-flow model, r.avaflow can also be used to simulate the motion of glaciers. The adaptograph and frictiograph options offer various possibilities to include time dependency of mass production or removal (representing, e.g., accumulation and ablation of glacier ice), and of the viscosity (representing, e.g., seasonal changes of rock glacier temperatures).
• Layer mode (option layers): with activated layer mode, it is assumed that phase 1 always moves at the bottom, phase 2 above, and phase 3 at the top of the mass. The surface of phase 1 is used as the basal topography of phase 2, and the surface of phase 2 is used as the basal topography of phase 3. In addition, the input for the phases (option phases) is ignored, instead all phases - or layers - are treated equally, based on a simplified rheological model. Most of the friction and viscosity parameters have a different meaning when the layer mode has been activated. The layer mode can be combined with the model for initial sliding (options tslide and slidepar).
• In the control parameters, the options for height-to-depth-conversion have been removed. r.avaflow 3 uses a hybrid approach, where vertical heights and slope-normal depths or thicknesses are used in parallel, and all outputs are based on vertical flow heights and slope-parallel velocities. The diffusion control has been reactivated but remains experimental. Also phase separation, non-hydrostatic effects, and some of the entrainment models should only be enabled by experiences users.

The most fundamental changes in r.avaflow 2.4pre, compared to r.avaflow 2.3, are indicated below. This list is most useful for those users which have already been working with r.avaflow 2.3.

• r.avaflow 2.4 only operates with Python 3 and GRASS 7.8. The use with Python 2.7 and older versions of GRASS GIS has been deprecated.
• The installation of r.avaflow 2.4 uses the built-in GRASS module g.extension. No installation script is provided any more.
• Mass point model for sliding: a completely new feature has been introduced, allowing to approximate the motion of slide-type movements with no or limited internal deformation. At each time step, the material at each raster cell is moved through a one-parameter or two-parameter friction model, based on the slope and aspect of the entire sliding mass or a user-defined neighbourhood zone. There is flexibility in transformation from sliding to flowing, and in spatially differentiating between zones of sliding and flowing. This feature is managed and parameterized through the newly introduced options tslide and slidepar. It is mainly intended for the very initial stage of landslide processes, before disintegration of the mass.
• Entrainment, deposition, and stopping: the models covering the interaction of the flow with the basal surface have been fundamentally revised and extended, allowing for a much more realistic representation of entrainment and deposition, but also stopping. Obsolete approaches have been removed. See options tstop, basal, and cvshear for more details.
• Flow parameters: some changes and rearrangements were made. The option ambient was replaced by the newly introduced option basal, which serves for the parameterization of the updated entrainment, deposition, and stopping models. The fluid friction number (which is related, but not similar to the Manning number) is now included in the option friction whereas the ambient drag coefficient, which has turned out to be hard to handle in practical applications, has been moved to the option special with a default value of 0.0.
• The function for the dynamic adaptation of the friction parameters has been modified in order to allow for a more convenient parameterization. If the function is activated (options controls), the friction parameters given through the option friction are valid for flows with zero kinetic energy (i.e. at rest). The exponential decrease of the friction is governed by a coefficient which is multiplied with the kinetic energy at a given raster cell. Further, the scaling of the friction parameters with the fraction of the respective case has been integrated. However, for most applications, it is strongly recommended to deactivate this function by setting the scaling exponent to zero.
• Progressive collapse: the possibility to consider progressive release though the options trelease and trelstop has been extended from the first phase to the entire mass. Still, this function should only be used for one single release mass, and cannot be combined with the extrusion-type progressive release.
• Curvature: the effects of topographic curvature can be more rigorously applied than in the previous versions. They can be switched on and off through the second value in the controls option: 0 = deactivated, 1 = only applied to decelerationg terms (comparable to the implementation in version 2.3), 2 = applied to all terms (slows down the simulation and may cause numerical issues). The default is 1. Note that deactivating curvature effects can make the simulated flow substantially more mobile.
• Diffusion control: this feature has been deprecated. Even though it has some effect in reducing computational times, unplausible behaviour has been observed in some specific flow situations.
• Option hydrocoords: the aspects of the hydrograph profiles have to be provided in degrees instead of radians.
• The maximum flow velocity displayed in the map plots, which sometimes used to show unrealistically high values, is now computed in a different way, better approximating the real conditions.
• Additional output raster maps of frontal and maximum flow velocities and phase fractions are automatically generated, depending on the model used.
• The accessibility of the map plots displaying the output of the mixture or one-phase model has been improved by adapting the colour schemes.

The major changes in r.avaflow 2.3, compared to r.avaflow 2.2, are indicated below. This list is most useful for those users which have already been working with r.avaflow 2.2.

• Numerical issues with the Voellmy-type mixture model, which were observed in the previous versions, have been fixed. Decelerating forces are now treated separately from the accelerating forces (as it had been implemented earlier for the Pudasaini and Mergili, 2019 multi-phase model), in order to avoid changes of the flow direction due to deceleration effects, having caused the numerical instabilities.
• Progressive collapse: the possibility to consider progressive release though the options trelease and trelstop has been extended. It is now possible to simulate the progressive collapse of a release mass, starting from its summit, instead of the progressive extrusion of the release mass from its basis. Progressive collapse is activated by providing trelstop with negative sign. Note that this function is still experimental and, when used with the multi-phase model, is only applied to the the first phase. It should only be used for one single release mass, and cannot be combined with the extrusion-type progressive release.
• Ambient drag: the default value of the ambient drag coefficient has been changed to 0.0. Experience and feedback from users have shown that setting the ambient drag coefficient (mainly used for air resistance) in a reliable way is a considerable challenge. Therefore, it is now recommended not to consider air resistance in a direct way, but rather to include its effect in the friction parameters (basal friction and turbulent friction in the Voellmy-type model, basal friction in the Pudasaini and Mergili, 2019 model).
• Internal friction and basal friction: if the internal friction is lower than the basal friction, it is set equal to the basal friction. This means that, in simulations with varying basal friction, the internal friction can be globally set to the basal friction by choosing a very low value.
• Fluid friction: Manning's n is now used as the fluid friction coefficient, the default value is 0.05. As Mannings n is widely used, it is supposed to greatly facilitate the choice of appropriate values. This change was mostly implemented by Sigríður S. Gylfadóttir from the Iceland Meteorological Office.
• Stopping: an additional stopping criterion has been introduced. When setting the fifth value in the controls parameters to 7, the flow stops when there is no raster cell at which the dynamic flow pressure is larger than the threshold value for flow pressure given in the thresholds parameter.
• Flow pressure: only the dynamic component of the pressure is considered, whereas the static component has been removed.
• Time of reach: the time of reach is now automatically provided as an additional output GRASS raster, ASCII raster, and map plot, indicated by the string treach. It shows the time in seconds after which the flow first reaches each raster cell, using the mimimum flow height for display (thresholds parameters) as the criterion. Time of reach is also shown in the control points output files. With multiple simulations (flag m), the ratio between the time of reach and the observed time of reach is included in the evaluation. Observed times of reach can be provided through the newly introduced option reftime, where comma-separated values indicate the observed travel times to each control point in seconds.
• Not providing the flag a has a more "aggressive" impact than in the previous versions. The output in terms of GRASS raster maps, ASCII rasters, and map plots is reduced to an absolute minimum (flow heights, change of basal topography if relevant, time of reach) in order to save time and memory. Note that no profile graphs can be produced without this flag. However, note that the flag a is now automatically enabled for multiple simulations (flag m).
• Some further bugs were fixed, such as another issue with progressive release.

The major changes in r.avaflow 2.2, compared to r.avaflow 2.1, are summarized as follows. This list is most useful for those users which have already been working with r.avaflow 2.1.

• An important bugfix has been included, concerning the treatment of hydrographs with Python 3.
• In the input hydrographs, the discharge in cubic metres per seconds now has to be provided instead of the flow height, whereas flow velocity has to be provided in the same way as before. Discharge and flow velocity are always applied to the centre of the hydrograph profile. The profile length is only used for the output hydrographs, but has to be provided also for the input hydrographs.
• After the flexibility in the combination of phases had been strictly constrained in r.avaflow 2.1, r.avaflow 2.4 again allows for the combination of two solid phases and one fluid phase (phases=s,s,f). However, this is the only exception from the rule that the sequence always has to be solid - fine solid - fluid when considering more than one phase. Simulations with two solid phases and one fluid phase should still be considered experimental. They can be useful when considering avalanches of rock and ice, since the consideration of granular flows of ice blocks as fine solid is not necessarily appropriate.

The list below summarizes the most important changes introduced in r.avaflow 2.1, compared to r.avaflow 2.0. It is most useful for those users which have already been working with r.avaflow 2.0.

• r.avaflow 2.4 can be run with Python 2.7 or Python 3. Installation with Python 2.7 is only recommended if the setup with all required software packages is already available. The script grass7.install.sh is exclusively targeted at the setup for the application of r.avaflow with Python 3 and GRASS GIS 7.8 or higher.
• The combination of phases is more restricted than in r.avaflow 2.0, in order to ensure a more rigorous application of the Pudasaini and Mergili, 2019 model and its extensions. Previously optimized model parameters might have to be revised. From an operational point of view, there is no two-phase model directly available any more, and the first phase in the multi-phase model is always solid, the second phase is always fine solid, and the third phase is always fluid. The multi-phase model is selected by entering phases=m. Input of material through the release, entrainment, and hydrograph parameters governs which phases are effectively considered and which are not. Providing input, for example, for the phases 1 and 3, but not for phase 2, effectively results in a two-phase model of solid and fluid material. It is noted that the fine solid phase can be represented by a wide variety of materials, ranging from rather solid ice to rather fluid slurry. Defining hrelease together with rhrelease1 results in an effectively two-phase simulation of solid and fluid (i.e. the phases 1 and 3), where rhrelease1 represents the fraction of solid release material. One-phase models can be used in the same way as in the version 2.0, with the difference that the Voellmy-type mixture model is selected through phases=x.
• Balancing of forces has been improved, so that numerical oscillations on water surfaces are strongly reduced, though not completely eliminated. Still, the new functionality has to be activated through the surface control in the controls parameter. Also, the boundary conditions have been revised, so that water surfaces can now extend all the way to the margin of the area of interest, without draining towards outside. These improvments make r.avaflow potentially suitable for the simulation of tsunamis. As a consequence, an additional set of map plots displaying the evolution and maximum of the heights of impact waves or tsunamis can be generated optionally, by providing the flag t.
• There are two new stopping criteria available: with stopping=4, the flow stops when its kinetic energy reaches a certain fraction of its maximum kinetic energy during the simulation. This fraction is defined through an additional value in the ambient parameter. 0.05 (the default) would mean that the flow stops as soon as its kinetic energy drops below 5 per cent of its maximum kinetic energy. With stopping=5, the same principle applies, but considering flow momentum instead of kinetic energy. Note that the additional value in the ambient parameter has to be provided in any case - but it is only used if one of the new stopping criteria are applied.
• Also, the flexibility with regard to entrainment has been increased: with entrainment=2, the entrainment coefficient is multiplied with the flow momentum instead of the flow kinetic energy at a given raster cell.
• Non-hydrostatic effects are now optionally considered, including enhanced gravity and dispersion. This function is activated by setting the surface control to a value of 2 in the controls parameter. Please note that this function is still in its experimental stage and undergoes further testing.
• A new, still experimental function for time scaling can be used for the simulation of very viscous, slow moving one-phase flows. Setting the new slomo parameter to a value larger than 1 means that the time is not measured in seconds, but in seconds multiplied with the value provided. slomo=86400 would scale the time from seconds to days, resulting in output velocities of metres per day. However, such changes of units are not indicated in the output data.
• The friction parameters can be dynamically adapted to the flow kinetic energy, in order to account for fluidization and lubrication effects. This function is activated by setting the last (additional) value of the controls parameter to 1. The necessary constraints are provided through the new option dynfric. Also this function is still in its experimental stage.
• Providing the flag a in addition to v results in the generation of map plots for flow kinetic energy and flow pressure. In older versions of r.avaflow, these plots were created automatically with the flag v. However, they are not always needed, so that it appears appropriate to make them optional outputs.

Further, note that some bugs were identified and fixed, in comparison to r.avaflow 2.0. It is therefore not recommended to use r.avaflow 2.0 any more. If you encouter possible bugs in this version, or have ideas for improvement of the software, please do not hesitate to contact martin.mergili@boku.ac.at. Note that r.avaflow is not a commercial software, nor is its development subject of an ongoing funded project. However, it is always attempted to provide adequate support as timely as possible.

Older versions of r.avaflow and the associated complementary tools are provided for reference. However, note that the use of older releases is strongly discouraged. No support can be provided for versions 2.4pre or lower. If you decide to use one of these versions, be aware that the resulting flow pressures have to be multiplied with a factor of 2 to obtain the depth-avaraged dynamic flow pressures.

This script assists in visualizing the dimension of time in the results of r.avaflow 2.4 in Windows environments with ArcGIS. Essentially, a polygon shapefile is produced where each individual polygon shows the time after wich the corresponding area is reached by the mass flow under investigation. A certain understanding of ArcGIS, Python scripting, and the execution of Python scripts is required as well as an ArcGIS license (10.5 or higher) including the Spatial Analyst. A cmd script for starting the timestepper and an ArcMap 10.5 project file providing an example of how to visualize the outcomes can be downloaded along with the training data for the Acheron Rock Avalanche. The result of an application of the timestepper is shown in Mergili et al., 2018b.

The superprofiler helps to illustrate vertical longitudinal profiles of the frontal velocities of r.avaflow 2.4 mass flow simulations in Windows environments with ArcGIS. Polygon shapefiles are generated where the frontal velocity is shown for each individual time step of the simulation. This script depends on the outcome of the timestepper. A certain understanding of ArcGIS, Python scripting, and the execution of Python scripts is required as well as an ArcGIS license (10.5 or higher) including the Spatial Analyst and the 3D Analyst. A cmd script for starting the superprofiler and an ArcMap 10.5 project file providing an example of how to visualize the outcomes can be downloaded along with the training data for the Acheron Rock Avalanche. The result of an application of the superprofiler is shown in Mergili et al., 2018b.

The animator automatically creates input files necessary to generate 3D animations of r.avaflow 2.4 results in Windows environments with ArcGIS Pro. A certain understanding of ArcGIS Pro, Python scripting, and the execution of Python scripts is required as well as an ArcGIS Pro license. Note that the animator may fail for very large data sets in terms of raster cells and number of time steps. In such cases, subsets of time steps have to be processed individually. A cmd script for starting the animator and an ArcGIS Pro project file providing an example for an animation can be downloaded along with the training data for the landslide-reservoir interactions.