Ravaflow3G Mixture Model

r.avaflow 3G 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.ravaflow3G, we have implemented class Ravaflow3GMixture. It provides a Python interface to directly run the Voellmy-type shallow flow model of r.avaflow 3G from within Python. For detailed theory of Voellmy-type shallow flow model, please refer to Christen et al. [2010] and Fischer et al. [2012].

Please note that the PSimPy.simulator.ravaflow24 module corresponding to r.avaflow 2.4 has been deprecated.

Ravaflow3GMixture Class

The Ravaflow3GMixture class is imported by:

from psimpy.simulator.ravaflow3G import Ravaflow3GMixture

Methods

class Ravaflow3GMixture(dir_sim, time_step=10, time_end=300, cfl=0.4, time_step_length=0.001, diffusion_control='0', curvature_control='1', surface_control='0', entrainment_control='0', stopping_control='0', stopping_threshold=0.0, friction_control='0', non_hydro_control='0', phase_sep_control='0', hydrograph_control='2', deceleration_control='0')[source]

r.avaflow 3G 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\).

  • diffusion_control (str) – ‘0’: no diffusion control (default) ‘1’: experimental diffusion control is applied

  • curvature_control (str) – ‘0’: curvature is neglected (default). ‘1’: curvature is considered in the decelerating source terms (default). ‘2’: curvature is considered in all relevant terms.

  • surface_control (str) – ‘0’: no balancing of forces (default). ‘1’: apply balancing of forces.

  • entrainment_control (str) – ‘0’: no entrainment (default). ‘1’: the entrainment coefficient (see preprocess) 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.

  • stopping_control (str) – ‘0’: no stopping control is used (default). ‘1’: stop if the flow kinetic energy ratio is equal or smaller than given threshold stopping_threshold. ‘2’: stop if the flow momentum ratio is equal or smaller than given threshold stopping_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’, a stopping_threshold has to be given with respect to maximal flow kinetic energy/momentum. If stopping_control is ‘3’, the pressure threshold has to be specified.

  • friction_control (str, optional) – ‘0’: no dynamic adaptation of friction parameters (default). ‘1’: dynamic adaptation of friction parameters (ignored for the mixture model).

  • non_hydro_control (str) – ‘0’: Non-hydrostatic effects are excluded (default). ‘1’: Only dispersion is considered. ‘2’: Only enhanced gravity is considered. ‘3’: Both dispersion and enhanced gravity are considered.

  • phase_sep_control (str) – ‘0’: Phase separation is neglected (default). ‘1’: Phase separation is considered.

  • hydrograph_control (str) – ‘0’: Impose hydrograph on the flow. ‘1’: Reset flow at the hydrograph profile before imposing the hydrograph. ‘2’: Impose the entire material added through the hydrograph on the centre of the hydrograph profile (default).

  • deceleration_control (str) – ‘0’: Suppress change of direction induced by frictional or viscous forces (default). ‘1’: Do not suppress the change of direction.

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.

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 impact 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-temporal grids. If False, returns the maximum values over all time steps at each spatial 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