r.slope.stability
The slope stability model
r.slope.stability 2.0 User manual
by Martin Mergili
r.slope.stability is designed for physically-based slope stability analyses over large areas (up to hundreds of square kilometres). It offers five modes of physically-based slope stability simulations. Four of them build on large numbers of randomly located, randomly sized slip surfaces, ellipsoidal in shape, whereas one employs the infinite slope stability model. In principle, r.slope.stability uses an elevation raster map and a system of soil classes and layers. Each soil class or layer is associated with geometric and geotechnical characteristics. For the ellipsoid-based simulations, it can be chosen whether to consider only the ellipsoid bottom or also the bottom of layers intersecting the ellipsoid. It is further possible to test only one ellipsoid with fixed parameters.
Limit equilibrium approaches with a Mohr-Coulomb failure criterion is applied. Thereby, for the ellipsoid-based simulations, two versions of the Hovland (1977) model can be used to compute the factor of safety for each slip surface. This model works for dry or fully saturated soil and can deal with slope-parallel and layer-parallel seepage. The geotechnical details of the model are outlined in Mergili et al. (2014b). In addition, seismic slope stability can be computed using the pseudostatic or the Newmark approach.
Alternatively to the factor of safety, r.slope.stability can be used to compute the slope failure probability: for each ellipsoid, user-defined numbers of values of cohesion, angle of internal friction and - optionally - truncated depth are tested within prescribed ranges. Using probability density functions, a probability of slope failure in the range 0-1 is derived for each raster cell (Mergili et al. (2014a).
r.slope.stability further offers the possibility for exploiting the advantages of multi-core computers in order to reduce computational time (Mergili et al., 2014a) and allows choosing inhowfar to use the GRASS Segment Library. It contains comprehensive functionalities for the empirical confirmation of the model results against a landslide inventory and for the visualization of the results.
Requirements
r.slope.stability 2.0 runs on LINUX operating systems. It relies on GRASS 7, Python 3, and R.
r.slope.stability 2.0 was developed and tested on Ubuntu 20.04 LTS, but is expected to work in other LINUX environments, too. It relies on GRASS GIS 7 (Version 7.8 or higher is recommended to ensure compatibility with Python 3 - Python 2.7 is not supported any more). Installation of r.slope.stability 2.0 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). The following packages of R are required in order to fully explore the functionalities offered by r.slope.stability 2.0: maptools, stats, sp, rgeos, rgdal, ROCR, and raster. The code builds on Python and C. The script grass7.install.sh provided with r.slope.stability 2.0 can be used to automatically install all the software needed on fresh installations of Ubuntu 20.04LTS, and probably also on installations of other LINUX environments. 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.slope.stability 2.0 can be easily installed through the command g.extension.
As soon as all software requirements are fulfilled, the installation of r.slope.stability 2.0 is straightforward, using the built-in GRASS module g.extension. Assuming that the folder with the r.slope.stability source code is stored in the directory /home/user1/, installation just requires the execution of the following command:
g.extension extension=r.slope.stability url=/home/user1/r.slope.stability/
Please note that, if you have installed earlier versions of r.slope stability using the script r.slope.stability.install.sh, you have to manually remove the old files installed e.g. in the folders /usr/lib/grass78/scripts and /usr/lib/grass78/bin in order to make sure that the r.slope.stability command really calls the newly installed version.
Operation
r.slope.stability 2.0 is most efficiently operated through shell scripts.
r.slope.stability 2.0 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.slope.stability 2.0 by typing the arguments directly into the command line:
r.slope.stability -v prefix=test model=i elevation=slst_elev
In this case, r.slope.stability 2.0 would run a simulation with the infinite slope stability model and evaluate and visualize the results, using the elevation map slst_elev 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.slope.stability 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.slope.stability 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.slopestability.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.slopestability.start.sh
You will find the folder with the results of the computation in the directory projects/test. Using shell scripts, you cannot only run several calculations 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)
Examples of such start scipts can be found in the training data.
Input
r.slope.stability 2.0 is very flexible with regard to input.
A large choice of options is available for the definition of the initial conditions and the parameterization of r.slope.stability 2.0. Not all options are needed for all types of calculations - in fact, simple calculations 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.
All
Flags
Key parameters
Infinite slope stability model
Soil class mode
Layer mode
Factor of safety
Slope failure probability
Single-core processing
Multi-core processing
Options for seismic slope stability
Options for empirical confirmation
The flags can be combined almost arbitrarily, even though some combinations are automatically disabled.
These are the options beginners should start with.
These options serve for the empirical confirmation (evaluation) of the model results.
This set of options is relevant for the soil class-based model.
This set of options is relevant for the layer-based model.
These options serve for the input for calculations of the factor of safety.
This set of options is relevant for the calculation of slope failure probability.
This set of options is relevant for single-core processing.
This set of options is relevant for multi-core processing.
These options serve for the computation of seismic slope stability. For this purpose, r.slope.stability offers two approaches:
- Pseudostatic seismic slope stability analysis (option pseudostatic): seismic forces are directly included in the calculation of the shear resistance and the shear force, based on the peak ground acceleration and a seismic coefficient.
- Newmark seismic slope stability analysis (option newmark): the displacement due to seismic effects is computed from the factor of safety, moment magnitude, and distance from the epicentre or place of fault rupture. With the flag p, the Newmark displacement is related to the critical displacement (option newmarkref) in order to compute the slope failure probability.
Only one of the approaches should be used within each slope stability calculation. Even though, technically, both approaches can be combined, this would make no sense from a scientific point of view. Providing neither of the options pseudostatic and newmark leads to the disregard of seismic effects on slope stability.
This set of options is relevant for running the infinite slope stability model.
-a
Additional output rasters
If this flag is not specified, only the factor of safety or the slope failure probability (flag p) is provided as output raster. Reducing the number of output raster maps may be useful particularly for parallel processing (flag m with large numbers of tiles. If the flag is specified, several more output raster maps are produced (see section Results). This flag is disregarded with model=i.
-d
Documentation
A summary file is written, containing the geometric parameters and factors of safety of each ellipsoid tested. Each line of the file corresponds to one ellipsoid. Please note that the summary file can get very large in case a large number of ellipsoids is tested. With multi-core processing (flag m), one summary file is written for each tile.
-m
Multi-core processing
The study area is split into a defined number of tiles (options tilesx, tilesy and overlap). Slope stability is computed separately from each tile, making use of multiple cores, if available (option ncores). Finally, the results from all tiles are put together. This strategy helps to reduce computing time particularly in case of large study areas.
-p
Slope failure probability
Slope failure probability is assigned to each pixel in addition to a factor of safety (see options geotech, depthstats and sampling and section Results). Samples of the geotechnical parameters and, optionally, truncated depth, are considered for each ellipsoid.
-s
Excessive use of GRASS Segment Library
The GRASS segment library enables the efficient storage of large rasters. It can deal with much larger datasets than arrays, however at a reduced performance. r.slope.stability makes use of the segment library by default, but also uses arrays. Providing the flag s suppresses the use of arrays, applying the segment library more extensively instead. This is particularly useful in case that the maximum extent of the largest possible ellipsoid is very large, compared to the raster cell size (option cellsize), when the simulation fails otherwise.
-t
Truncation of ellipsoids
Not only the ellipsoid bottom is considered as possible slip surface, but also the bottom of layers, if it is above the ellipsoid bottom. This possibly results in multiple factors of safety for one slip surface. All of them are given in the summary file (if the flag d is specified), the lowest safety factor and the associated slip surface are considered for the output maps. This flag is not relevant for model=i.
-v
Empirical confirmation and visualization
A number of evaluation procedures is carried out with the model results, requiring a map of observed landslides (option observed). These results are visualized by diagram plots. Further, map layouts of the main output raster maps are produced.
-z
Test mode for multi-core processing
The results from the tiles are not put together, saving computing time when testing model performance. This flag is only relevant in combination with multi-core processing (flag m).
prefix
Prefix for output files and folders
prefix=slst
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-8 characters characterizing the simulation.
cellsize
Raster cell size in metres
cellsize=[cell size of elevation raster map]
Cell size in metres to be used for the model. If the cell size is not given, it is taken from the input elevation raster map (option elevation).
model
Model to be used
This option determines which type of limit equilibrium slope stability model is applied to which type of geometry. Each model is used to compute a factor of safety FS, representing the ratio between stabilizing and destabilizing forces (shear resistance and shear force) acting on a given element of a slope (raster cell or assemblage of raster cells). The Mohr-Coulomb failure criterion is used in all cases. Optionally, seismic effects can be considered (see options pseudostatic and newmark). One of five choices has to be selected:
- i: infinite slope stability model
- c: Hovland model in soil class mode
- l: Hovland model in layer mode
- cr: Revised Hovland model in soil class mode
- lr: Revised Hovland model in layer mode
The infinite slope stability model is a very simple, purely raster cell-based approach suitable only for shallow slope stability. It assumes translational failure of a slope of infinite length. Failure occurs along a slope-parallel failure plane, and FS for each pixel is computed as follows:
- FS = ( c' A + Ws cos β tan φ' ) / ( Ws sin β + S )
where c' (N/m2) and φ' are effective cohesion and effective internal friction angle, Ws (N) is the submerged weight, A (m) is the area of the failure surface of one raster cell, β is the slope angle, and S (N) is the seepage force.
The Hovland model and the revised Hovland model can be used to compute FS for curved failure surfaces. Within r.slope.stability, they are applied to ellipsoid-shaped (see option ellips) or truncated (see flag t) surfaces. The portion of the slope above the failure surface is divided into a number of colums, and the ear resistance and shear forces for each column are summed up to compute FS for the entire surface:
- FS = Σ ( c' A + (WS cos βc + Sn) tan φ' ) / Σ ( Ws sin βm + St )
where βc is the slope angle in the direction of the steepest local slope, βm is the slope angle in the downslope direction of the entire sliding surface, Sn (N) is the contribution of the seepage force to the shear resistance, and St (N) is the contribution of the seepage force to the shear force. As all inter-column forces are neglected, the Hovland model only provides exact results for spherical sliding surfaces, but can be considered a reasonable approximation for ellipsoid-shaped or truncated sliding surfaces. The same is true for the revised Hovland model, where both the shear resistance and the shear force are multiplied with cos βm:
- FS = Σ (( c' A + (WS cos βc + Sn) tan φ' ) cos βm ) / Σ (( Ws sin βm + St ) cos βm )
The Hovland and revised Hovland models can be used with the soil class mode or the layer mode. Both modes yield identical results, but the soil class mode is rather useful for simple subsurface stuctures, whereas the computationally more expensive layer mode is better suited for mor complex subsurface layering:
- Soil class mode: the study area is horizontally split into a number of soil classes. Each soil class is associated with a defined number of layers (the number of layers may be different for different soil classes), carrying information on depth and geotechnical parameters. The soil class-based mode is suitable for relatively simple geological conditions (few layers with more or less regular depth) or relatively shallow potential landslides. A large number of randomized ellipsoidal or truncated slip surfaces is tested.
- Layer mode: a number of geological layers is defined by a set of raster maps of layer bottom depth. The number of the layers may be large (>50) and their geometry may be irregular. Not all of the layers have to extend over the entire study area, they may reach the terrain surface or disappear in the depth. Each of the layers is assigned to a soil class associated with geotechnical parameters. A large number of randomized ellipsoidal or - typically - truncated slip surfaces is tested.
The flag t and the options ellips and elldens are important for the parameterization of the soil class and layer modes. They are neglected with the infinite slope stability model, which otherwise takes the same options as the Hovland models with the soil class mode. The soil class and layer modes may be run for multiple ellipsoids or for one single ellipsoid with exactly defined parameters (see options ellips and elldens).
ellips
Ellipsoid parameters
Typically, r.slope.stability makes use of a large number of randomized ellipsoids (option model=c,l,cr or cl). The following parameters determine how the randomization is constrained. They have to be entered in the specified sequence, separated by commas:
- Maximum slip surface length in the direction of the steepest slope
- Minimum slip surface length in the direction of the steepest slope
- Maximum slip surface width perpendicular to the steepest slope
- Minimum slip surface width perpendicular to the steepest slope
- Maximum vertical depth of the deepest point of the ellipsoid
- Minimum vertical depth of the deepest point of the ellipsoid
- Maximum offset of the ellipsoid centre above the terrain (fraction of depth)
- Minimum offset of the ellipsoid centre above the terrain (fraction of depth)
- Maximum length to width ratio of the slip surface
- Minimum length to width ratio of the slip surface
- X coordinate of ellipsoid centre. If the value is set to -9999, the coordinate is randomized
- Y coordinate of ellipsoid centre. If the value is set to -9999, the coordinate is randomized
- Aspect of ellipsoid in degrees (clockwise, north=0). If the value is set to -9999, the aspect is set to the direction of the steepest terrain slope
- Slope of ellipsoid in degrees. If the value is set to -9999, the slope is set to the terrain slope
Most applications - particularly those testing a large number of ellipsoids - will build on randomized center coordinates and with ellipsoids aligned to the slope. However, specifying the coordinates, aspect and slope is useful for testing one single ellipsoid (option elldens=0).
elldens
Ellipsoid density
elldens=2000
The ellipsoid density stands for the average number of ellipsoids touching each raster cell. Due to the randomized simulation process it is an approximate value which is used to determine the number of ellipsoids to be tested. The ellipsoid density should be large enough to cover all possible situations so that the area with a factor of safety smaller than 1 remains constant also when testing further ellipsoids. The evolution plot (see section Results) indicates whether this criterion has been fulfilled or whether the simulation has to be repeated with a higher ellipsoid density. The ellipsoid density required to fulfill this criterion depends on the specific situation, but typically exceeds values of 2000.
If a value of 0 is specified, only one single ellipsoid is tested (see also option ellips).
observed
Name of observed landslides raster map
Raster map of observed landslides, required for empirical confirmation of the results (some functions associated with the flag v). Raster cells with observed landslides have to be assigned the value of 1, cells with no observed landslides the value 0. Here, it is important to differentiate between 0 and no data cells.
elevation
Name of elevation raster map
Name of the input raster map representing the terrain elevation in metres above any defined level.
soilclass
Name of raster map of soil classes
Soil class raster map. Each soil class has to be represented by an integer number. It is required to use consecutive numbers starting from 1: if the study area is split into four soil classes, it is obligatory to use numbers 1,2,3 and 4 and not, e.g., 1, 3, 6 and 8. Pixels with 0 are treated as no data. In the layer mode (see option model), the soil classes specified in the soil class map are used for those pixels where no layer is specified.
gwdepth
Name of groundwater table raster map
Raster map describing the depth of the groundwater table below the terrain surface in metres.
pseudostatic
Pseudostatic seismic slope stability analysis
Parameters for pseudostatic seismic slope stability analysis, consisting of two comma-separated parameters:
- Name of raster map of the peak ground acceleration PGA (m/s2)
- Dimensionless seismic coefficient Cs
The seismic force is computed by the multiplication of PGA and Cs and included in the calculation of the shear force and the shear resistance. The pseudostatic seismic slope stability analysis can be combined with all available models and geometries (see option model).
newmark
Newmark seismic slope stability analysis
Parameters for Newmark seismic slope stability analysis, consisting of five comma-separated parameters:
- Name of the raster map of the epicentral distance R (km)
- Focal depth of the earthquake H (km)
- Moment magnitude of the earthquake M
- Site-specific option S1: 0 for rock or for soil <20 m deep, 1 for soil ≥20 m deep
- Site-specific option S2: 0 for rock of for soil ≥20 m deep, 1 for soil <20 m deep
Theses parameters are needed for the computation of the Arias intensity (see option arias) and, finally, the Newmark displacement (see option newmarkcoef) and the slope failure probability (flag p, see option newmarkref). H, S1, and S2 are only used in selected equations for the Arias intensity and are otherwise neglected. However, numbers have to be provided in any case.
The Newmark seismic slope stability analysis can be combined with all available models and geometries (see option model). Note that, with the flag p, the uncertainties in the calculation of the Arias intensity and the Newmark displacement are superimposed with the uncertainties of the geotechnical parameters and sliding surface depth in order to compute the slope failure probability. However, the standard deviation of the Newmark displacement only represents the uncertainies of the geotechnical parameters and sliding surface depth, but not those related to the uncertainties in the calculation of the Arias intensity and the Newmark displacement.
newmarkcoef
Coefficients for Newmark displacement
newmarkcoef=0.847,-10.62,6.587,1.84,0.295
The Newmark displacement is computed according an empirical equation suggested by Hsieh and Lee (2011).
- log Dn = C1 log Ia + C2 Ac + C3 Ac log Ia + C4 ± C5
Dn (cm) is the Newmark displacement, Ia is the Arias intensity (see option arias), and Ac (m/s2) is the critical acceleration:
- Ac = (FS - 1) g sin β,
where FS is the factor of safety, g is gravitational acceleration (m/s2), and β is the inclination of the sliding surface. If FS≤1, Dn is set to the critical displacement (see option newmarkref).
The coefficients C1-C5 may vary for different regions of the world. The default values are derived from a worldwide dataset. If other values should be used, they have to be provided as five comma-separated parameters.
With the flag p, the probability that the Newmark displacement exceeds the critical displacement (see option newmarkref) is computed, assuming a normal distribution with the uncertainty measure C5 interpreted as the standard deviation. Also the uncertainties of the Arias intensity are considered (see option arias).
newmarkref
Name of raster map of critical displacement
Name of raster map of critical displacement (cm) for Newmark seismic slope stability analysis, i.e. the displacement at which the slope will fail. With the flag p, the slope failure probability is identical to the probability of exceedance of the critical displacement. Further, all values of the Newmark displacement are contrained by the critical displacement. Without the flag p, the critical displacement can be used to constrain the Newmark displacement, which is convenient for display of the results, but is of no further consequence for the simulation. If newmarkref is not provided, its value is set to 9999 cm for each raster cell of the study area.
arias
Equations for Arias intensity
arias=4
Empirical equations according to which the Arias intensity will be computed, compiled from Chousianitis et al. (2014).
- log Ia = -4.1 + M - 2 log r ± 0.44 (Wilson, 1993)
- log Ia = -4.9 + 0.98 M - 1.35 log r (Jibson, 1987)
- log Ia = -2.659 + 0.601 M - log R - 0.011 R ± 0.430 (Rajabi et al., 2010)
- log Ia = -4.066 + 0.911 M - 1.818 log √(R2 + 28.09) + 0.139 S1 + 0.244 S2± 0.397 (Sabetta and Pugliese, 1996)
- log Ia = -3.88 + 0.810 M - log √(R2 + H2) - 0.002 √(R2 + H2) (Mahdavifar et al., 2007)
Ia is the Arias intensity, M is the moment magnitude of the earthquake, r (km) is the distance from the fault rupture zone, R (km) is the epicentral distance, and H (km) is the focal depth. S1 and S2 describe the site characteristics. All these parameters have to be provided with the option newmark, with the exception of r, which is set equal to √(R2 + H2).
As the default, only 4. is used. arias=1,4, for example, would use the equations 1. and 4. to compute the Arias intensity. Without the flag p, only the last equation in the list will be considered, and the given uncertainty measures will be disregarded. With the flag p, the probability of failure will be derived from the statistical distribution of all selected equations. Thereby, all selected equations are weighted equally, uncertainty measures are interpreted as standard deviations of a normal distribution, and a uniform distribution is assumed for those equations where no uncertainty measure is provided.
slopeunits
Name of slope units raster map
Map of slope units for the study area, useful for empirical confirmation (flag v). Each slope unit has to be represented by a unique positive integer value. 0 is treated as no data.
dxl
Average slope of layers in x direction raster map
Average slope of all the layers in x direction, expressed as ratio. This raster map is required in the layer mode (model=l or model=lr) when the option seepage is set to 2 (layer-parallel seepage). If, in this case, dxl is not specified, it is computed automatically, slightly increasing the computing time.
dyl
Average slope of layers in y direction raster map
Average slope of all the layers in y direction, expressed as ratio. This raster map is required in the layer mode (model=l or model=lr) when the option seepage is set to 2 (layer-parallel seepage). If, in this case, dyl is not specified, it is computed automatically, slightly increasing the computing time.
numlayers
Number of layers for each soil class
In the soil class mode (model=c or model=cr) and the infinite slope stability mode (model=i), the number of layers has to be specified for each soil class, separated by commas. For a study area with six soil classes, each of them with two layers, the input would look as follows:
numlayers=2,2,2,2,2,2
depthmaps
Names of depth of layer bottom raster maps
In the soil class mode (model=c or model=cr) and the infinite slope stability mode (model=i), the depth of each layer can be specified using a raster map containing the depth of the layer bottom in metres. The names of the maps, one for each layer, have to be separated by commas. The input for a three-layer study area could look as follows:
depthmaps=depth1,depth2,depth3
depthvals
Depth of layer bottom values
In the soil class mode (model=c or model=cr) and the infinite slope stability mode (model=i), depthvals can be specified alternatively to depthmaps (one of the two parameters is required). Here, the depth of the bottom of each layer of each soil class has to be specified in metres. Input has to start with the first (top) layer of soil class 1, followed by the second layer of soil class 1 etc. When the input for soil class 1 is completed, the same procedure follows for soil class 2, 3 and so on. The input for a study area with four soil classes, each with two layers with bottom depths of 2 and 10 m, would look as follows:
depthvals=2,10,2,10,2,10,2,10
depthstats
Statistical properties of top layer depth
This parameter may be specified in the soil class or infinite slope stability modes (model=c, model=cr, or model=i) in combination with the flag p, in order to sample not only multiple values of the the geotechnical parameters, but also of truncated depth. It consists in a series of four comma-separated values: average, standard deviation, minimum and maximum truncated depth, which will most commonly coincide with the depth of soil or regolith. These values are needed for construction a probability density function of depth and to constrain sampling (see option sampling).
prelayers
Prefix for depth of layer bottom raster maps
In the layer mode (model=l or model=lr), the prefix for the names of the layer bottom depth maps has to be specified. This means that the maps for all layers have to be named consistently with of the prefix and the number of the layer.
classlayers
Soil class to be assigned to each layer
In the layer mode (model=l or model=lr), the soil class for each layer has to be specified, separated by commas. For a study area with five layers and four soil classes, the input could look as follows:
classlayers=3,1,4,4,2
maxlayers
Maximum number of layers relevant for one ellipsoid
In the layer mode (model=l or model=lr), the maximum number of layers relevant for a single ellipsoid cannot be determined analytically at the start. However, this parameter is important for dimensioning of arrays needed for the simulation. If the value is too large, memory is used unnecessarily. If the value is too small, the simulation does not yield valid results. Usually, the number specified will be a first guess and, if it is inappropriate, the simulation has to be repeated (the real maximum number of layers is printed at the end of the simulation). If maxlayers is not specified, the value is automatically set to four times the maximum number of layers for one raster cell.
geotech
Geotechnical parameters for each soil class and/or layer
For computing the factor of safety, four parameters are required for each soil class or layer:
- Soil dry specific weight γd (N/m2)
- Effective cohesion c' (N/m2)
- Effective angle of internal friction φ' (degree)
- Soil water content θs (per cent of volume)
Technically, any soil water content can be entered. However, as r.slope.stability cannot deal with partial saturation, it is highly recommended to specify either 0 (for dry soil) or the saturated water content (for saturated soil). Note that, in the case the option gwdepth is provided, the soil above the groundwater table is considered dry, overruling the soil water content given for the respective soil class and layer.
In the soil class mode (model=c or model=cr) or the infinite slope stability mode (model=i), the four comma-separated parameters in the sequence given above are preceded by the number of the soil class and the number of the layer. Input has to start with the first (top) layer of soil class 1, followed by the second layer of soil class 1 etc. When the input for soil class 1 is completed, the same procedure follows for soil classes 2, 3 and so on. Given that we have two soil classes with two layers each, the input could look as follows:
geotech=1,1,18000,2000,35,40,1,2,17000,15000,25,35,2,1,19000,5000,38,42,2,2,19000,0,45,37
In the layer mode (model=l or model=lr), the four comma-separated parameters in the sequence given above are preceded by the number of the soil class. Input has to start with soil class 1, followed by soil class 2, 3 and so on. The parameters are then automatically assigned to the layers, based on the soil class given for each layer (option classlayers. Given that we have three soil classes, the input could look as follows:
geotech=1,17000,15000,25,35,2,19000,5000,38,42,3,18000,2000,35,40
For computing the slope failure probability (flag p), six additional comma-separated parameters have to be defined for each soil class and layer in the following sequence after θs:
- Standard deviation of c'
- Minimum of c'
- Maximum of c'
- Standard deviation of φ'
- Minimum of φ'
- Maximum of φ'
The original value (which would be used for the factor of safety) is taken as average for building the probability density functions. The minima and maxima of the parameters determine the constraints for looping over a range of values. The sampling strategy is defined by the option sampling.
seepage
Seepage direction
seepage=1
r.slope.stability can work with three assumptions of seepage direction
- 0: Dry soil, no seepage
- 1: Slope-parallel seepage
- 2: Layer-parallel seepage, only meaningful for the layer mode (model=l or model=lr)
sampling
Sampling parameters
sampling=2,4,4,0,1,1,1
The slope failure probability (flag p) is derived by computing the factor of safety for a number of combinations of c', φ' and, optionally, (truncated) depth. The higher the number of combinations yielding a factor of safety smaller than 1, the higher the slope failure probability. The parameter values are sampled according to the constraints and statistical properties defined by the options geotech and depthstats. The sampling strategy is defined by seven comma separated integer numbers:
- Type of sampling: 0 = random sampling of parameter combinations, 1 = random sampling of parameters, 2 = regular sampling of parameters. With random sampling, the values are randomly determined within the constraints defined by the options geotech and depthstats. The probability of a value to be sampled relates to its assumed probability density. Different samples are tested for each ellipsoid. Random sampling of parameter combinations (0) means that the combined probability density of all parameters is used to sample n combinations of parameters, where n is the product of the number of values to be sampled for each parameter (see below). This mode is very costly in terms of computing time. Random sampling of parameters (1) means that each parameter is sampled saparately, and all possible combinations of the sampled parameters are tested. With regular sampling, the sampled parameter values are equally distributed according to the assumed cumulative density function of each parameter. The same sample is used throughout the entire calculation. In the infinite slope stability mode (model=i), regular sampling is always applied, independently of the parameter entry. Also for the ellipsoid modes (model=c,cr,l or lr), it is strongly recommended to use regular sampling.
- Number of effective cohesion values to be sampled (>1).
- Number of effective angle of internal friction values to be sampled (>1).
- Number of values of truncated depth to be sampled (0 or 1 means no sampling of truncated depth values).
- Type of probability density function (pdf) assumed for c': 0 = rectangular pdf, 1 = normal (gaussian) pdf, 2 = log-normal pdf, 3 = exponential pdf, 4 = normal pdf of deviation from empirical c'- φ' relationship (see option regpar).
- Type of probability density function (pdf) assumed for φ', same options as for c' except for 4.
- Type of probability density function (pdf) assumed for truncated depth, same options as for φ.
With the option newmark, the slope failure probability represents the fraction of parameter combinations yielding a Newmark displacement larger than the critical displacement (option newmarkref). Uncertainties in the equations of the Arias intensity and the Newmark displacement are automatically included. If, with the option newmark, only the uncertainties in the equations of the Arias intensity and the Newmark displacement should be considered, but not the uncertainies in the geotechnical parameters or the (truncated) depth, random sampling of parameters with one effective cohesion value and one effective internal friction angle has to be applied:
sampling=1,1,1,0,0,0,0
In this case, only the averages of the geotechnical parameters (see option geotech) are used, but values also have to be provided for minimum, maximum, and standard deviation.
regpar
Regression parameters
regpar=-583,21711
This parameter is regarded when computing slope failure probability (flag p) employing an empirical c'- φ' relationship (see option sampling). Two parameters have to be provided, describing the slope and intercept of a linear regression function (two comma-separated numbers):
- Change of c' with φ (N/m2/degree)
- Intercept of c' (N/m2)
Note that, when using regpar, the mean values provided for c' in the geotech option have to be set to zero, and the minima and maxima have to be set to the maximum negative and positive deviations from the regression line to be considered.
segsize
Size of one segment in rows or columns
16
Size of one segment (GRASS Segment Library). If not specified, the value is set to 16.
nsegs
Number of segments to be held in memory
16
Number of segments to be held in memory (GRASS Segment Library). If not specified, the value is set to 16.
tilesx
Number of tiles in x direction
Number of tiles in x direction, required for multi-core processing (flag m). Any positive integer number is valid in principle. However, tiles should not be too small (they should have several times the extent of the largest possible ellipsoid, option ellips).
tilesy
Number of tiles in y direction
Number of tiles in y direction, required for multi-core processing (flag m). Any positive integer number is valid in principle. However, tiles should not be too small (they should have several times the extent of the largest possible ellipsoid, option ellips).
overlap
Overlap of tiles
Overlap between tiles (multi-core processing, flag m) in order to ensure full coverage by the largest possible ellipsoid (option ellips). The overlap is also used for empirical confirmation (flag v) in order to exclude lateral areas not fully covered by the computation.
ncores
Number of cores
ncores=8
Number of cores to use for multi-core processing (flag m).
adm
Detail bounding box
Bounding box of detailed output maps (with flag v). The coordinates (in metres) have to be entered separated by commas in the following sequence: north, south, west, east. If the parameter is not specified, no detailed output maps are produced.
Results
r.slope.stability 2.0 automatically creates raster maps, graphics, and other files.
The names of all output raster maps, folders and files start with the prefix defined by the option prefix. r.slope.stability produces a set of output GRASS raster maps stored in the active mapset as well as a set of txt and tif files stored in subfolders of the folder [prefix]_results:
- Text files are stored in the folder [prefix]_files.
- Maps with hillshade background (suited for colour visualization) are stored in the folder [prefix]_hmaps.
- Maps without hillshade (suited mainly for greyscale visualization) are stored in the folder [prefix]_maps.
- Plots, most of them visualizing the outcomes of the empirical confirmation, are stored in the folder [prefix]_plots.
- Exported raster maps for use with other software packages are stored in the folder [prefix]_tiffs.
The folders [prefix]_hmaps, [prefix]_maps and [prefix]_plots including their content as well as part of the content of the folder [prefix]_files are produced only with the flag v (empirical confirmation and and visualization). If the flag was not specified, the output can be procuced afterwards by the command
If the flag v was not specified when executing the model, the visualization can be performed afterwards by running the command:
r.slope.stability -v prefix=[prefix]
Note that, in this case, also the flags a and t may be provided at this point. This step is only possible if the output raster maps still exist in the active GRASS mapset 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.slope.stability produces the following output raster maps (if the flag a is not specified, usually only the factor of safety and the failure depth, or the slope failure probability are provided as output raster map):
- [prefix]_fos: Factor of safety for each pixel (for model=c,cr,l or lr: minimum of all tested slip surfaces touching each pixel). With the flag p, the mean value of the factor of safety is given.
- [prefix]_pf: Slope failure probability for each pixel (for flag p only): for model=c,cr,l or lr, maximum value out of all tested slip surfaces touching each pixel.
- [prefix]_pf: Standard deviation of the factor of safety for each pixel (for flag p only): for model=c,cr,l or lr, the value computed for the relevant slip surface with the lowest mean factor of safety is applied to each pixel.
- [prefix]_depth: Depth in metres associated to the minimum factor of safety.
- [prefix]_sindex: Fraction of ellipsoids with a factor of safety smaller than 1 out of all tested ellipsoids (for model=c,cr,l or lr only).
- [prefix]_lcrit: Slip surface length in metres associated to the minimum factor of safety (for model=c,cr,l or lr only).
- [prefix]_wcrit: Slip surface width in metres associated to the minimum factor of safety (for model=c,cr,l or lr only).
- [prefix]_zbcrit: Relative offset of ellipsoid centre above terrain associated with the minimum factor of safety (for model=c,cr,l or lr only).
- [prefix]_layer: Id of layer associated to the minimum factor of safety (for model=l or model=lr only).
- [prefix]_dnewmark: Newmark displacement in cm (for newmark without p only).
- [prefix]_dnewmark_mean: Mean value of Newmark displacement in cm (for newmark with p only).
- [prefix]_dnewmark_stdev: Standard deviation of Newmark displacement in cm (for newmark with p only).
Tiff rasters
Tiff rasters of result files which can be exported for use in other software packages.
[prefix]_tiff
The output raster maps are exported as geotiff images in order to be accessible with other software packages. The naming scheme follows the one used for the GRASS raster maps: [prefix]_[content].tif, where [content] stands for the content of the map.
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 plots in the folder [prefix]_plots:
- [prefix]_documentation.txt: Summary of the flags and parameters specified when starting the simulation as well as some further parameters needed for constructing the plots in the folder [prefix]_plots.
- [prefix]_evolution.txt: Ratio of pixels with factor of safety smaller than one, or average slope failure probability (p), for each increase of ellipsoid density by 1 (for flags c or l only). For multi-core processing (flag m) these parameters are given separately for each tile (see also [prefix]_plot_evolution.tif).
- [prefix]_profile.txt: If only one ellipsoid is tested (option elldens=0, a longitudinal profile of terrain and slip surfaces is stored along with the minimum factor of safety and the number of the critical slip surface. This information is needed for the construction of the plot [prefix]_plot_profile.tif.
- [prefix]_time.txt: Time in seconds needed for the computation (excluding pre- and post-processing of data as well as empirical confirmation).
- [prefix]_confirmation.txt: Summary of the empirical confirmation of the model results with observed landslides (for flag v only)
- [prefix]_summary.txt: Summary file of the computation, each line documenting the geometry of one ellipsoid and the associated factor(s) of safety (for flag d only)
Map layouts with hillshade
Layouts to be used for quick interpretation or presentation.
[prefix]_hmaps
Colour layouts of the output raster maps are produced both for the entire study area ([prefix]_map_[content].tif) and, if specified, for the extent given by the option adm ([prefix]_dmap_[content].tif), where [content] stands for the content of the map and follows the same scheme as for the GRASS raster maps. If a raster map of observed landslides was specified (option observed), the landslide boundaries are displayed as lines as well as the extent used for the empirical confirmation of the results. A hillshade derived from the elevation raster map is shown as background.
Map layouts without hillshade
Map layouts to be used for quick interpretation or presentation.
[prefix]_maps
The content is largely identical to the content of the folder [prefix]_hmaps, but no hillshades are shown as background. Even though provided in colour, these maps are also suitable for presentation in shades of gray.
Graphical layouts
Graphic representation of the main simulation results.
[prefix]_plots
All layouts are provided in colours, but are also well readable when converted to shades of gray:
- [prefix]_plot_evolution.tif: Line graph(s) illustrating the ratio of cells with factor of safety smaller than one, or the average slope failure probability (p), for each increase of ellipsoid density by 1 (for model=c,cr,l or lr only). For multi-core processing (flag m) separate line graphs are shown for each tile and, as an average, for the entire study area.
- [prefix]_plot_rad.tif: Radar chart illustrating the correspondence between areas with a factor of safety smaller than 1 and observed landslide areas, expressed in rates of true positives (rTN), true negatives (rTN), false positives (rFP) and false negatives (rFN).
- [prefix]_plot_reg.tif: Scatterplot with regression, relating the ratio of pixels with factor of safety smaller than 1, or the average slope failure probability (flag p), to the ratio of pixels with observed landslides for each slope unit. The plot is produced only when the slope units raster map (option slope units) and the raster map of observed landslides (option observed) were specified.
- [prefix]_plot_profile.tif: Plot illustrating a longitudinal profile through the ellipsoid (for option elldens=0 only).
- [prefix]_plot_roc.tif: ROC (Receiver Operating Characteristics) curve relating the slope failure probability to the observed landslides (for flag p only). Without flag p, the ROC curve relates the fraction of ellipsoids with factor of safety lower than 1 to the observed landslides (model=c,cr,l or lr only). In any case, the raster map of observed landslides (option observed) is needed for this type of output.
Please cite this site and its content as: Mergili, M., 2014-2021. r.slope.stability - The slope stability model. r.slope.stability 2.0 User manual. https://www.slopestability.org/manual.php