Ravaflow24 Mixture Model
r.avaflow 2.4 is a GIS-supported open source software for mass flow modeling. It is developed by Mergili et al. [2017]. For more information see its official user manual here.
In PSimPy.simulator.ravaflow24
, we have implemented class
Ravaflow24Mixture
. It provides an Python interface to directly run
the Voellmy-tpye shallow flow model of r.avaflow 2.4 from within Python.
For detailed theory of Voellmy-tpye shallow flow model, one can refer to
Christen et al. [2010] and Fischer et al. [2012].
Ravaflow24Mixture Class
The Ravaflow24Mixture
class is imported by:
from psimpy.simulator.ravaflow24 import Ravaflow24Mixture
Methods
- class Ravaflow24Mixture(dir_sim, time_step=10, time_end=300, cfl=0.4, time_step_length=0.001, conversion_control='0', curvature_control='1', surface_control='0', entrainment_control='0', shear_velocity_coef=0.05, basal_friction_diff=0.0, stopping_control='0', stopping_threshold=0.0, friction_control='0')[source]
r.avaflow 2.4 Mixture model (Voellmy-type shallow flow model).
- Parameters
dir_sim (str) – Directory to save output files generated by r.avaflow.
time_step (float or int) – Time step for simulation, in seconds.
time_end (float or int) – End time for simulation, in seconds.
cfl (float) – CFL criterion, a value being equal or smaller than 0.5.
time_step_length (float) – If
cfl
is not applicable,time_step_length
is used. In seconds. Recommended range is around \(0.1\) to \(0.5\).conversion_control (str) – ‘0’: no conversion of flow heights to flow depths. ‘1’: conversion is applied.
curvature_control (str) – ‘0’: curvature is neglected. ‘1’: curvature is considered in the decelerating source terms. ‘2’: curvature is considered in all relevant terms.
surface_control (str) – ‘0’: no balancing of forces. ‘1’: apply balancing of forces.
entrainment_control (str) – ‘0’: no entrainment. ‘1’: the entrainment coefficient is multiplied with flow momentum. ‘2’: simplified entrainment and deposition model is used. ‘3’: combination of ‘1’ for entrainmnet and ‘2’ for deposition. ‘4’: acceleration-deceleration entrainment and deposition model.
shear_velocity_coef (float) – Only used with
entrainment_control
being ‘2’ or ‘3’, range \([0,1]\).basal_friction_diff (float) – Difference between the basal friction angles of the basal surface and the flow, in degrees. Only used with
entrainment_control
being ‘2’ or ‘3’.stopping_control (str) – ‘0’: no stopping control is used. ‘1’: stop if the flow kinetic energy is equal or smaller than a given threshold. ‘2’: stop if the flow momentum is equal or smaller than a given threshold. ‘3’: stop if the dynamic flow pressure of all raster cells is euqal or smaller than a given threshold.
stopping_threshold (float) – Threshold value for
stopping_control
. Ifstopping_control
is ‘1’ or ‘2’,stopping_threshold
has to be given as the maximum value reached during the flow. Ifstopping_control
is ‘3’, the pressure threshold has to be specified.friction_control (str, optional) – ‘0’: no dynamic adaptation of friction parameters. ‘1’: dynamic adaptation of friction parameters (ignored for the mixture model).
- preprocess(prefix, elevation, hrelease, cellsize=20, hrelease_ratio=1.0, internal_friction=35, basal_friction=20, turbulent_friction=3, entrainment_coef=-7.0, EPSG=None)[source]
Preprocess simulation input data simulation.
- Parameters
prefix (str) – Prefix required by r.avaflow to name output files.
elevation (str) – Name of elevation raster file (including its path). The file format should be supported by GDAL. Its unit is in meters.
hrelease (str) – Name of release height raster file (including its path). The file format should be supported by GDAL. Its unit is in meters.
cellsize (float or int, optional) – Cell size in meters to be used for simulation.
hrelease_ratio (float, optional) – A positive value to multiple
hrelease
in order to control the release volume.internal_friction (float or int, optional) – Internal friction angle, in degrees, range \([0,90)\).
basal_friction (float or int, optional) – Basal friction angle, in degrees, range \([0,90)\).
turbulent_friction (float or int, optional) – Logarithm with base \(10\) of the turbulent friction, in \(m/s^2\).
entrainment_coef (float, optional) – Logarithm with base \(10\) of the entrainment coefficient, except for \(0\) meaning no entrainment.
EPSG (str, optional) – EPSG (European Petroleum Survey Group) code to create GRASS Location. If None,
elevation
must be a georeferenced file which has metadata to create the GRASS Location.
- Return type
tuple
[str
,str
]- Returns
grass_location (str) – Name of the GRASS Location (including path).
sh_file (str) – Name of the shell file (including path), which will be called by GRASS to run the simulation.
- run(grass_location, sh_file)[source]
Run simulation.
- Parameters
grass_location (str) – Name of the GRASS Location (including path).
sh_file (str) – Name of the shell file (including path).
- Return type
None
- extract_impact_area(prefix, qoi='h', threshold=0.5)[source]
Extract impact area defined by a given quantity of interest and its threshold.
- Parameters
prefix (str) – Prefix used by r.avaflow to name output files.
qoi (str) – Quantity of interest to determine the impact area. ‘h’: maximum flow height, in meters. ‘v’: maximum flow velocity, in \(m/s\). ‘p’: maximum flow pressure, in \(Pa\). ‘t’: maximum flow kinetic energy, in \(J\).
threshold (float or int) – Threshold of
qoi
to determine impact area. Areas whereqoi
is larger thanthreshold
are regarded as impar area.
- Returns
impact_area – A scalar value representing the overall impact area.
- Return type
float
- extract_qoi_max(prefix, qoi, aggregate=True)[source]
Extract the maximum value(s) of a quantity of interest.
- Parameters
prefix (str) – Prefix used by r.avaflow to name output files.
qoi (str) – Quantity of interest. ‘h’: maximum flow height, in meters. ‘v’: maximum flow velocity, in \(m/s\). ‘p’: maximum flow pressure, in \(Pa\). ‘t’: maximum flow kinetic energy, in \(J\).
aggregate (bool) – If True, returns the overall maximum value over all spatio-tempo grids. If False, returns the maximum values over all time steps at each spatio location, namely a raster of maximum values.
- Returns
qoi_max – Maximum value(s) of
qoi
in one simulation.- Return type
float or numpy array
- extract_qoi_max_loc(prefix, loc, qoi)[source]
Extract maximum value(s) of a quantity of interest at specific location(s).
- Parameters
prefix (str) – Prefix used by r.avaflow to name output files.
loc (numpy array) – Coordinates of interested locations. Shape
(nloc, 2)
, wherenloc
is the number of interested locations.loc[:,0]
corresponds to x coordinates andloc[:,1]
to y coordinates.qoi (str) – Quantity of interest. ‘h’: maximum flow height, in meters. ‘v’: maximum flow velocity, in \(m/s\). ‘p’: maximum flow pressure, in \(Pa\). ‘t’: maximum flow kinetic energy, in \(J\).
- Returns
qoi_max_loc – Consist of maximum value(s) of
qoi
at each location. Shape of(nloc,)
.- Return type
numpy array