landlab.components.mass_wasting_runout.mass_wasting_runout¶

class MassWastingRunout[source]¶

Bases: Component

a cellular-automata mass wasting runout model that routes an initial mass wasting body (e.g., a landslide) through a watershed, determines erosion and aggradation depths, evolves the terrain and regolith and tracks attributes of the regolith. This model is intended for modeling the runout extent, topographic change and sediment transport caused by a mapped landslide(s) or landslides inferred from a landslide hazard map.

Examples

Import necessary packages and components

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> from landlab.components import FlowDirectorMFD
>>> from landlab.components.mass_wasting_runout import MassWastingRunout

Define the topographic__elevation field of a 7 columns by 7 rows, 10-meter raster model grid

>>> dem = np.array(
...     [
...         [10, 8, 4, 3, 4, 7.5, 10],
...         [10, 9, 3.5, 4, 5, 8, 10],
...         [10, 9, 6.5, 5, 6, 8, 10],
...         [10, 9.5, 7, 6, 7, 9, 10],
...         [10, 10, 9.5, 8, 9, 9.5, 10],
...         [10, 10, 10, 10, 10, 10, 10],
...         [10, 10, 10, 10, 10, 10, 10],
...     ]
... )

>>> dem = np.hstack(dem).astype(float)
>>> mg = RasterModelGrid((7, 7), 10)
>>> _ = mg.add_field("topographic__elevation", dem, at="node")

Define boundary conditions

>>> mg.set_closed_boundaries_at_grid_edges(True, True, True, True)

Add multiflow direction fields, soil thickness (here set to 1 meter)

>>> fd = FlowDirectorMFD(mg, diagonals=True, partition_method="slope")
>>> fd.run_one_step()
>>> nn = mg.number_of_nodes
>>> depth = np.ones(nn) * 1
>>> _ = mg.add_field("soil__thickness", depth, at="node")

Define the initial landslide. Any mass_wasting_id value >1 is considered a landslide. The landslide extent is defined by assigining all nodes withing the landslide the same mass_wasting_id value. Here, the landslide is represented by a single node (node 38), which assigned a mass_wasting_id value of 1:

>>> mg.at_node["mass__wasting_id"] = np.zeros(nn).astype(int)
>>> mg.at_node["mass__wasting_id"][np.array([38])] = 1

Add attributes of the regolith as fields of the raster model grid that will be tracked by the model. These could be any attribute in which the tracking method used by MassWastingRunout reasonably represents movement of the attribute. Here we track the particle diameter and organic content of the regolith. Note, a particle__diameter field is required if shear stress is determined as a function of grain size.

>>> np.random.seed(seed=7)
>>> mg.at_node["particle__diameter"] = np.random.uniform(0.05, 0.25, nn)
>>> mg.at_node["organic__content"] = np.random.uniform(0.01, 0.10, nn)

Next define parameter values for MassWastingRunout and instantiate the model:

>>> Sc = [0.03]  # Sc, note: defined as a list (see below)
>>> qsc = 0.01  # qsc
>>> k = 0.02  # k
>>> h_max = 1
>>> tracked_attributes = ["particle__diameter", "organic__content"]
>>> example_square_MWR = MassWastingRunout(
...     mg,
...     critical_slope=Sc,
...     threshold_flux=qsc,
...     erosion_coefficient=k,
...     tracked_attributes=tracked_attributes,
...     effective_qsi=True,
...     max_flow_depth_observed_in_field=h_max,
...     save=True,
... )

Run MassWastingRunout

>>> example_square_MWR.run_one_step()

By subtracting the initial DEM from the final DEM, which has evolvod as a consequence of the runout, we can see areas of aggradation (positive values) and erosion (negative values). Nodes with non-zero topographic change represent the runout extent.

>>> DEM_initial = mg.at_node["topographic__initial_elevation"]
>>> DEM_final = mg.at_node["topographic__elevation"]
>>> DEM_final - DEM_initial
array([ 0.        ,  0.        ,  0.        ,  0.        ,  0.        ,
        0.        ,  0.        ,  0.        ,  0.        ,  0.96579201,
        0.52734339, -0.00778869,  0.        ,  0.        ,  0.        ,
        0.        , -0.00594927, -0.12261762, -0.0027898 ,  0.        ,
        0.        ,  0.        ,  0.        , -0.04562554, -0.10973222,
       -0.05776526,  0.        ,  0.        ,  0.        ,  0.        ,
       -0.01225359, -0.07973101, -0.04888238,  0.        ,  0.        ,
        0.        ,  0.        ,  0.        , -1.        ,  0.        ,
        0.        ,  0.        ,  0.        ,  0.        ,  0.        ,
        0.        ,  0.        ,  0.        ,  0.        ])

See how the landslide removes all of the regolith at node 38 (the negative -1)

Look at the final spatial distribution of regolith particle diameter.

>>> mg.at_node["particle__diameter"]
array([0.06526166, 0.20598376, 0.13768185, 0.19469304, 0.2455979 ,
       0.15769917, 0.15022409, 0.06441023, 0.1036878 , 0.15619144,
       0.17680799, 0.21074781, 0.12618823, 0.06318727, 0.10762912,
       0.23191871, 0.09295928, 0.14042479, 0.23545374, 0.05497985,
       0.17010978, 0.2400259 , 0.09606058, 0.15969798, 0.23182567,
       0.07663389, 0.15468252, 0.20008197, 0.18380265, 0.14355057,
       0.09096982, 0.14815318, 0.12447694, 0.14548023, 0.12317808,
       0.2175836 , 0.2037295 , 0.11279894, 0.        , 0.10520981,
       0.14056859, 0.12059567, 0.18147989, 0.12407022, 0.1418186 ,
       0.19386482, 0.13259837, 0.23128465, 0.08609032])

Also note that the attribute value is set to zero at any node in which the regolith depth is 0.

References

Keck, J., Istanbulluoglu, E., Campforts, B., Tucker G., Horner-Devine A., A landslide runout model for sediment transport, landscape evolution and hazard assessment applications, submitted to Earth Surface Dynamics (2023)

Parameters:

grid (landlab raster model grid)
critical_slope (list of floats) – critical slope (angle of repose if no cohesion) of mass wasting material , L/L list of length 1 for a basin uniform Sc value list of length 2 for hydraulic geometry defined Sc, where the first and second values in the list are the coefficient and exponent of a user defined function for crictical slope that varies with contributing area [m2] to a node (e.g., [0.146,0.051] sets Sc<=0.1 at contributing area > ~1100 m2).
threshold_flux (float) – minimum volumetric flux per unit contour width, [L3/L2/iterataion] or [L/iteration]. Flux below this threshold stops at the cell as a deposit
erosion_coefficient (float) – coefficient used to convert total basal shear stress [kPa] of the runout material to a scour depth [m]
tracked_attributes (list of str or None) – A list of the attribute names (strings) that will be tracked by the runout model. Attributes in tracked_attributes must also be a field on the model grid and names in list must match the grid field names. Default is None.
deposition_rule (str) – Can be either “critical_slope”, “L_metric” or “both”. “critical_slope” is deposition rule used in Keck et al. 2023. “L_metric” is a variation of rule described by Campforts et al. 2020. “both” uses the minimum value of both rules. Default value is “critical_slope”.
grain_shear (bool) – Indicate whether to define shear stress at the base of the runout material as a function of grain size using Equation 13 (True) or the depth-slope approximation using Equation 12 (False). Default is True.
effective_qsi (bool) – Indicate whether to limit erosion and aggradation rates to <= the erosion and aggradation rates coorisponding to the maximum observed flow depth. All results in Keck et al. 2023 use this constraint. Default is True.
E_constraint (bool) – Indicate if erosion can not simultaneously occur with aggradation. If True, aggradation > 0, then erosion = 0. This is True in Keck et al., 2023. Default is True.
settle_deposit (bool) – Indicate whether to allow deposits to settle before the next model iteration is implemented. Settlement is determined the critical slope as evaluated from the lowest adjacent node to the deposit. This is not used in Keck et al. 2023 but tends to allow model to better reproduce smooth, evenly sloped deposits. Default is False.
save (bool) – Save topographic elevation of watershed after each model iteration? This uses a lot of memory but is helpful for illustrating runout. The default is False.
be (These parameters have a lesser impact on model behavior or may not)
applicable
options. (depending on model run)
typical_flow_thickness_of_erosion_zone (float) – field estimated flow thickness in the erosion-dominatedd reaches of the runout path [m], used to estimate erosion_coefficient k using erosion_coef_k function. Default value: 3
slope_of_erosion_zone (typical) – field or remote sensing estimated slope in the scour dominated reach of the runout path [L/L], used to estimate erosion_coefficient k using erosion_coef_k function. Default value: 0.4
erosion_exponent (float) – The exponent of equation 11, that scales erosion depth as a function of shear stress. Default value: 0.5
max_flow_depth_observed (float) – Maximum observed flow depth, over the entire runout path [m], h_max in equation 24. Only used effective_qsi is True. Default value: 4
vol_solids_concentration (float) – The ratio of the volume of the solids to the total volume of the flow mixture. Default value: 0.6
solids (density) – The density of the solids [kg/m3]. Default value: 2650
fluid (density) – The density of the fluid [kg/m3]. Default value: 1000
gravity (float) – Acceleration due to gravity [m2/s]. Default value: 9.81
dist_to_full_qsc_constraint (float) – distance in meters at which qsc is applied to runout. If the landslide initiates on relatively flat terrain, it may be difficult to determine a qsc value that allows the model start and deposit in a way that matches the observed. In Keck et al. 2023, dist_to_full_qsc_constraint = 0, but other landslides may need dist_to_full_qsc_constraint = 20 to 50 meters.
itL (int) – maximum number of iterations the model runs before it is forced to stop. The default is 1000. Ideally, if properly parameterized, the model should stop on its own. All modeled runout in Keck et al. 2023 stopped on its own.
run_id (float, int or str) – label for landslide run, can be the time or some other identifier. This can be updated each time model is implemnted with “run_one_step”

Return type:

None

__init__(grid, critical_slope=0.05, threshold_flux=0.25, erosion_coefficient=0.005, tracked_attributes=None, deposition_rule='critical_slope', grain_shear=True, effective_qsi=False, settle_deposit=False, E_constraint=True, save=False, typical_flow_thickness_of_erosion_zone=2, typical_slope_of_erosion_zone=0.15, erosion_exponent=0.2, max_flow_depth_observed_in_field=None, vol_solids_concentration=0.6, density_solids=2650, density_fluid=1000, gravity=9.81, dist_to_full_qsc_constraint=0, itL=1000, run_id=0)[source]¶

Parameters:

grid (landlab raster model grid)
critical_slope (list of floats) – critical slope (angle of repose if no cohesion) of mass wasting material , L/L list of length 1 for a basin uniform Sc value list of length 2 for hydraulic geometry defined Sc, where the first and second values in the list are the coefficient and exponent of a user defined function for crictical slope that varies with contributing area [m2] to a node (e.g., [0.146,0.051] sets Sc<=0.1 at contributing area > ~1100 m2).
threshold_flux (float) – minimum volumetric flux per unit contour width, [L3/L2/iterataion] or [L/iteration]. Flux below this threshold stops at the cell as a deposit
erosion_coefficient (float) – coefficient used to convert total basal shear stress [kPa] of the runout material to a scour depth [m]
tracked_attributes (list of str or None) – A list of the attribute names (strings) that will be tracked by the runout model. Attributes in tracked_attributes must also be a field on the model grid and names in list must match the grid field names. Default is None.
deposition_rule (str) – Can be either “critical_slope”, “L_metric” or “both”. “critical_slope” is deposition rule used in Keck et al. 2023. “L_metric” is a variation of rule described by Campforts et al. 2020. “both” uses the minimum value of both rules. Default value is “critical_slope”.
grain_shear (bool) – Indicate whether to define shear stress at the base of the runout material as a function of grain size using Equation 13 (True) or the depth-slope approximation using Equation 12 (False). Default is True.
effective_qsi (bool) – Indicate whether to limit erosion and aggradation rates to <= the erosion and aggradation rates coorisponding to the maximum observed flow depth. All results in Keck et al. 2023 use this constraint. Default is True.
E_constraint (bool) – Indicate if erosion can not simultaneously occur with aggradation. If True, aggradation > 0, then erosion = 0. This is True in Keck et al., 2023. Default is True.
settle_deposit (bool) – Indicate whether to allow deposits to settle before the next model iteration is implemented. Settlement is determined the critical slope as evaluated from the lowest adjacent node to the deposit. This is not used in Keck et al. 2023 but tends to allow model to better reproduce smooth, evenly sloped deposits. Default is False.
save (bool) – Save topographic elevation of watershed after each model iteration? This uses a lot of memory but is helpful for illustrating runout. The default is False.
be (These parameters have a lesser impact on model behavior or may not)
applicable
options. (depending on model run)
typical_flow_thickness_of_erosion_zone (float) – field estimated flow thickness in the erosion-dominatedd reaches of the runout path [m], used to estimate erosion_coefficient k using erosion_coef_k function. Default value: 3
slope_of_erosion_zone (typical) – field or remote sensing estimated slope in the scour dominated reach of the runout path [L/L], used to estimate erosion_coefficient k using erosion_coef_k function. Default value: 0.4
erosion_exponent (float) – The exponent of equation 11, that scales erosion depth as a function of shear stress. Default value: 0.5
max_flow_depth_observed (float) – Maximum observed flow depth, over the entire runout path [m], h_max in equation 24. Only used effective_qsi is True. Default value: 4
vol_solids_concentration (float) – The ratio of the volume of the solids to the total volume of the flow mixture. Default value: 0.6
solids (density) – The density of the solids [kg/m3]. Default value: 2650
fluid (density) – The density of the fluid [kg/m3]. Default value: 1000
gravity (float) – Acceleration due to gravity [m2/s]. Default value: 9.81
dist_to_full_qsc_constraint (float) – distance in meters at which qsc is applied to runout. If the landslide initiates on relatively flat terrain, it may be difficult to determine a qsc value that allows the model start and deposit in a way that matches the observed. In Keck et al. 2023, dist_to_full_qsc_constraint = 0, but other landslides may need dist_to_full_qsc_constraint = 20 to 50 meters.
itL (int) – maximum number of iterations the model runs before it is forced to stop. The default is 1000. Ideally, if properly parameterized, the model should stop on its own. All modeled runout in Keck et al. 2023 stopped on its own.
run_id (float, int or str) – label for landslide run, can be the time or some other identifier. This can be updated each time model is implemnted with “run_one_step”

Return type:

None

static __new__(cls, *args, **kwds)¶

cite_as = ''¶

property coords¶: Return the coordinates of nodes on grid attached to the component.

property current_time¶

Current time.

Some components may keep track of the current time. In this case, the current_time attribute is incremented. Otherwise it is set to None.

Return type:: current_time

definitions = (('flow__receiver_node', 'Node array of receivers (node that receives flow from current node)'), ('flow__receiver_proportions', 'Node array of proportion of flow sent to each receiver.'), ('mass__wasting_id', 'interger or float id of each mass wasting area is assigned to all nodes representing the mass wasting area.'), ('particle__diameter', 'representative particle diameter at each node, this might vary with underlying geology, contributing area or field observations'), ('soil__thickness', 'soil depth to restrictive layer'), ('topographic__elevation', 'Land surface topographic elevation'), ('topographic__steepest_slope', 'The steepest *downhill* slope'))¶

classmethod from_path(grid, path)¶

Create a component from an input file.

Parameters:

grid (ModelGrid) – A landlab grid.
path (str or file_like) – Path to a parameter file, contents of a parameter file, or a file-like object.

Returns:

A newly-created component.

Return type:

Component

property grid¶: Return the grid attached to the component.

initialize_optional_output_fields()¶

Create fields for a component based on its optional field outputs, if declared in _optional_var_names.

This method will create new fields (without overwrite) for any fields output by the component as optional. New fields are initialized to zero. New fields are created as arrays of floats, unless the component also contains the specifying property _var_type.

initialize_output_fields(values_per_element=None)¶

Create fields for a component based on its input and output var names.

This method will create new fields (without overwrite) for any fields output by, but not supplied to, the component. New fields are initialized to zero. Ignores optional fields. New fields are created as arrays of floats, unless the component specifies the variable type.

Parameters:: values_per_element (int (optional)) – On occasion, it is necessary to create a field that is of size (n_grid_elements, values_per_element) instead of the default size (n_grid_elements,). Use this keyword argument to acomplish this task.

input_var_names = ('flow__receiver_node', 'flow__receiver_proportions', 'mass__wasting_id', 'soil__thickness', 'topographic__steepest_slope')¶

name = 'MassWastingRunout'¶

optional_var_names = ('particle__diameter', 'topographic__elevation')¶

output_var_names = ('soil__thickness',)¶

run_one_step()[source]¶: run MWR

property shape¶: Return the grid shape attached to the component, if defined.

unit_agnostic = False¶

units = (('flow__receiver_node', '-'), ('flow__receiver_proportions', '-'), ('mass__wasting_id', '-'), ('particle__diameter', 'm'), ('soil__thickness', 'm'), ('topographic__elevation', 'm'), ('topographic__steepest_slope', '-'))¶

classmethod var_definition(name)¶

Get a description of a particular field.

Parameters:: name (str) – A field name.
Returns:: A description of each field.
Return type:: tuple of (name, *description*)

classmethod var_help(name)¶

Print a help message for a particular field.

Parameters:: name (str) – A field name.

classmethod var_loc(name)¶

Location where a particular variable is defined.

Parameters:: name (str) – A field name.
Returns:: The location (‘node’, ‘link’, etc.) where a variable is defined.
Return type:: str

var_mapping = (('flow__receiver_node', 'node'), ('flow__receiver_proportions', 'node'), ('mass__wasting_id', 'node'), ('particle__diameter', 'node'), ('soil__thickness', 'node'), ('topographic__elevation', 'node'), ('topographic__steepest_slope', 'node'))¶

classmethod var_type(name)¶

Returns the dtype of a field (float, int, bool, str…).

Parameters:: name (str) – A field name.
Returns:: The dtype of the field.
Return type:: dtype

classmethod var_units(name)¶

Get the units of a particular field.

Parameters:: name (str) – A field name.
Returns:: Units for the given field.
Return type:: str

erosion_coef_k(E_l, tau, f, dx)[source]¶

erosion_rate(k, tau, f, dx)[source]¶

flow_velocity(Dp, h, s, g)[source]¶

shear_stress_grains(vs, ros, Dp, h, s, g)[source]¶

shear_stress_static(vs, ros, rof, h, s, g)[source]¶