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. If stopping_control is ‘1’ or ‘2’, stopping_threshold has to be given as the maximum value reached during the flow. If stopping_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 where qoi is larger than threshold 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), where nloc is the number of interested locations. loc[:,0] corresponds to x coordinates and loc[:,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