landlab.components.stream_power.sed_flux_dep_incision

class SedDepEroder[source]

Bases: Component

This module implements sediment flux dependent channel incision following:

E = f(Qs, Qc) * ([a stream power-like term] - [an optional threshold]),

where E is the bed erosion rate, Qs is the volumetric sediment flux into a node, and Qc is the volumetric sediment transport capacity at that node.

This component is under active research and development; proceed with its use at your own risk.

The details of the implementation are a function of the two key arguments, sed_dependency_type and Qc. The former controls the shape of the sediment dependent response function f(Qs, Qc), the latter controls the way in which sediment transport capacities are calculated (primarily, whether a full Meyer-Peter Muller approach is used, or whether simpler stream-power-like equations can be assumed). For Qc, ‘power_law’ broadly follows the assumptions in Gasparini et al. 2006, 2007; ‘MPM’ broadly follows those in Hobley et al., 2011. Note that a convex-up channel can result in many cases assuming MPM, unless parameters b and c are carefully tuned.

If Qc == 'power_law':

E  = K_sp * f(Qs, Qc) * A ** m_sp * S ** n_sp;
Qc = K_t * A ** m_t * S ** n_t

If Qc == 'MPM':

shear_stress = fluid_density * g * depth * S
             = fluid_density * g * (mannings_n/k_w) ** 0.6 * (
               k_Q* A ** c_sp) ** (0.6 * (1. - b_sp)) * S ** 0.7,
               for consistency with MPM

E = K_sp * f(Qs, Qc) * (shear_stress ** a_sp - [threshold_sp])

Qc = 8 * C_MPM * sqrt((sed_density-fluid_density)/fluid_density *
     g * D_char**3) * (shields_stress - threshold_shields)**1.5

shields_stress = shear_stress / (g * (sed_density-fluid_density) *
                 D_char)

If you choose Qc=’MPM’, you may provide thresholds for both channel incision and shields number, or alternatively set either or both of these threshold dynamically. The minimum shear stress can be made equivalent to the Shields number using set_threshold_from_Dchar, for full consistency with the MPM approach (i.e., the threshold becomes a function of the characteristic grain size on the bed). The Shields threshold itself can also be a weak function of slope if slope_sensitive_threshold, following Lamb et al. 2008, taustar_c = 0.15 * S ** 0.25.

The component is able to handle flooded nodes, if created by a lake filler. It assumes the flow paths found in the fields already reflect any lake routing operations, and then requires the optional argument flooded_depths be passed to the run method. A flooded depression acts as a perfect sediment trap, and will be filled sequentially from the inflow points towards the outflow points.

References

Required Software Citation(s) Specific to this Component

None Listed

Additional References

Hobley, D. E. J., Sinclair, H. D., Mudd, S. M., and Cowie, P. A.: Field calibration of sediment flux dependent river incision, J. Geophys. Res., 116, F04017, doi:10.1029/2010JF001935, 2011.

Constructor for the class.

Parameters:

  • grid (a ModelGrid) – A grid.

  • K_sp (float (time unit must be years)) – K in the stream power equation; the prefactor on the erosion equation (units vary with other parameters).

  • g (float (m/s**2)) – Acceleration due to gravity.

  • rock_density (float (Kg m**-3)) – Bulk intact rock density.

  • sediment_density (float (Kg m**-3)) – Typical density of loose sediment on the bed.

  • fluid_density (float (Kg m**-3)) – Density of the fluid.

  • runoff_rate (float, array or field name (m/s)) – The rate of excess overland flow production at each node (i.e., rainfall rate less infiltration).

  • pseudoimplicit_repeats (int) – Number of loops to perform with the pseudoimplicit iterator, seeking a stable solution. Convergence is typically rapid.

  • return_stream_properties (bool) – Whether to perform a few additional calculations in order to set the additional optional output fields, ‘channel__width’, ‘channel__depth’, and ‘channel__discharge’ (default False).

  • sed_dependency_type ({'generalized_humped', 'None', 'linear_decline',) – ‘almost_parabolic’} The shape of the sediment flux function. For definitions, see Hobley et al., 2011. ‘None’ gives a constant value of 1. NB: ‘parabolic’ is currently not supported, due to numerical stability issues at channel heads.

  • Qc ({'power_law', 'MPM'}) – Whether to use simple stream-power-like equations for both sediment transport capacity and erosion rate, or more complex forms based directly on the Meyer-Peter Muller equation and a shear stress based erosion model consistent with MPM (per Hobley et al., 2011).

  • 'generalized_humped'... (If sed_dependency_type ==)

  • kappa_hump (float) – Shape parameter for sediment flux function. Primarily controls function amplitude (i.e., scales the function to a maximum of 1). Default follows Leh valley values from Hobley et al., 2011.

  • nu_hump (float) – Shape parameter for sediment flux function. Primarily controls rate of rise of the “tools” limb. Default follows Leh valley values from Hobley et al., 2011.

  • phi_hump (float) – Shape parameter for sediment flux function. Primarily controls rate of fall of the “cover” limb. Default follows Leh valley values from Hobley et al., 2011.

  • c_hump (float) – Shape parameter for sediment flux function. Primarily controls degree of function asymmetry. Default follows Leh valley values from Hobley et al., 2011.

  • 'power_law'... (If Qc ==)

  • m_sp (float) – Power on drainage area in the erosion equation.

  • n_sp (float) – Power on slope in the erosion equation.

  • K_t (float (time unit must be in years)) – Prefactor in the transport capacity equation.

  • m_t (float) – Power on drainage area in the transport capacity equation.

  • n_t (float) – Power on slope in the transport capacity equation.

  • 'MPM'... (if Qc ==)

  • C_MPM (float) – A prefactor on the MPM relation, allowing tuning to known sediment saturation conditions (leave as 1. in most cases).

  • a_sp (float) – Power on shear stress to give erosion rate.

  • b_sp (float) – Power on drainage area to give channel width.

  • c_sp (float) – Power on drainage area to give discharge.

  • k_w (float (unit variable with b_sp)) – Prefactor on A**b_sp to give channel width.

  • k_Q (float (unit variable with c_sp, but time unit in seconds)) – Prefactor on A**c_sp to give discharge.

  • mannings_n (float) – Manning’s n for the channel.

  • threshold_shear_stress (None or float (Pa)) – The threshold shear stress in the equation for erosion rate. If None, implies that set_threshold_from_Dchar is True, and this parameter will get set from the Dchar value and critical Shields number.

  • Dchar (None, float, array, or field name (m)) – The characteristic grain size on the bed, that controls the relationship between critical Shields number and critical shear stress. If None, implies that set_Dchar_from_threshold is True, and this parameter will get set from the threshold_shear_stress value and critical Shields number.

  • set_threshold_from_Dchar (bool) – If True (default), threshold_shear_stress will be set based on Dchar and threshold_Shields.

  • set_Dchar_from_threshold (bool) – If True, Dchar will be set based on threshold_shear_stress and threshold_Shields. Default is False.

  • threshold_Shields (None or float) – The threshold Shields number. If None, implies that slope_sensitive_threshold is True.

  • slope_sensitive_threshold (bool) – If True, the threshold_Shields will be set according to 0.15 * S ** 0.25, per Lamb et al., 2008 & Hobley et al., 2011.

  • flooded_depths (array or field name (m)) – Depths of flooding at each node, zero where no lake. Note that the component will dynamically update this array as it fills nodes with sediment (…but does NOT update any other related lake fields).

__init__(grid, K_sp=1e-06, g=scipy.constants.g, rock_density=2700, sediment_density=2700, fluid_density=1000, runoff_rate=1.0, sed_dependency_type='generalized_humped', kappa_hump=13.683, nu_hump=1.13, phi_hump=4.24, c_hump=0.00181, Qc='power_law', m_sp=0.5, n_sp=1.0, K_t=0.0001, m_t=1.5, n_t=1.0, C_MPM=1.0, a_sp=1.0, b_sp=0.5, c_sp=1.0, k_w=2.5, k_Q=2.5e-07, mannings_n=0.05, threshold_shear_stress=None, Dchar=0.05, set_threshold_from_Dchar=True, set_Dchar_from_threshold=False, threshold_Shields=0.05, slope_sensitive_threshold=False, pseudoimplicit_repeats=5, return_stream_properties=False, flooded_depths=None)[source]

Constructor for the class.

Parameters:

  • grid (a ModelGrid) – A grid.

  • K_sp (float (time unit must be years)) – K in the stream power equation; the prefactor on the erosion equation (units vary with other parameters).

  • g (float (m/s**2)) – Acceleration due to gravity.

  • rock_density (float (Kg m**-3)) – Bulk intact rock density.

  • sediment_density (float (Kg m**-3)) – Typical density of loose sediment on the bed.

  • fluid_density (float (Kg m**-3)) – Density of the fluid.

  • runoff_rate (float, array or field name (m/s)) – The rate of excess overland flow production at each node (i.e., rainfall rate less infiltration).

  • pseudoimplicit_repeats (int) – Number of loops to perform with the pseudoimplicit iterator, seeking a stable solution. Convergence is typically rapid.

  • return_stream_properties (bool) – Whether to perform a few additional calculations in order to set the additional optional output fields, ‘channel__width’, ‘channel__depth’, and ‘channel__discharge’ (default False).

  • sed_dependency_type ({'generalized_humped', 'None', 'linear_decline',) – ‘almost_parabolic’} The shape of the sediment flux function. For definitions, see Hobley et al., 2011. ‘None’ gives a constant value of 1. NB: ‘parabolic’ is currently not supported, due to numerical stability issues at channel heads.

  • Qc ({'power_law', 'MPM'}) – Whether to use simple stream-power-like equations for both sediment transport capacity and erosion rate, or more complex forms based directly on the Meyer-Peter Muller equation and a shear stress based erosion model consistent with MPM (per Hobley et al., 2011).

  • 'generalized_humped'... (If sed_dependency_type ==)

  • kappa_hump (float) – Shape parameter for sediment flux function. Primarily controls function amplitude (i.e., scales the function to a maximum of 1). Default follows Leh valley values from Hobley et al., 2011.

  • nu_hump (float) – Shape parameter for sediment flux function. Primarily controls rate of rise of the “tools” limb. Default follows Leh valley values from Hobley et al., 2011.

  • phi_hump (float) – Shape parameter for sediment flux function. Primarily controls rate of fall of the “cover” limb. Default follows Leh valley values from Hobley et al., 2011.

  • c_hump (float) – Shape parameter for sediment flux function. Primarily controls degree of function asymmetry. Default follows Leh valley values from Hobley et al., 2011.

  • 'power_law'... (If Qc ==)

  • m_sp (float) – Power on drainage area in the erosion equation.

  • n_sp (float) – Power on slope in the erosion equation.

  • K_t (float (time unit must be in years)) – Prefactor in the transport capacity equation.

  • m_t (float) – Power on drainage area in the transport capacity equation.

  • n_t (float) – Power on slope in the transport capacity equation.

  • 'MPM'... (if Qc ==)

  • C_MPM (float) – A prefactor on the MPM relation, allowing tuning to known sediment saturation conditions (leave as 1. in most cases).

  • a_sp (float) – Power on shear stress to give erosion rate.

  • b_sp (float) – Power on drainage area to give channel width.

  • c_sp (float) – Power on drainage area to give discharge.

  • k_w (float (unit variable with b_sp)) – Prefactor on A**b_sp to give channel width.

  • k_Q (float (unit variable with c_sp, but time unit in seconds)) – Prefactor on A**c_sp to give discharge.

  • mannings_n (float) – Manning’s n for the channel.

  • threshold_shear_stress (None or float (Pa)) – The threshold shear stress in the equation for erosion rate. If None, implies that set_threshold_from_Dchar is True, and this parameter will get set from the Dchar value and critical Shields number.

  • Dchar (None, float, array, or field name (m)) – The characteristic grain size on the bed, that controls the relationship between critical Shields number and critical shear stress. If None, implies that set_Dchar_from_threshold is True, and this parameter will get set from the threshold_shear_stress value and critical Shields number.

  • set_threshold_from_Dchar (bool) – If True (default), threshold_shear_stress will be set based on Dchar and threshold_Shields.

  • set_Dchar_from_threshold (bool) – If True, Dchar will be set based on threshold_shear_stress and threshold_Shields. Default is False.

  • threshold_Shields (None or float) – The threshold Shields number. If None, implies that slope_sensitive_threshold is True.

  • slope_sensitive_threshold (bool) – If True, the threshold_Shields will be set according to 0.15 * S ** 0.25, per Lamb et al., 2008 & Hobley et al., 2011.

  • flooded_depths (array or field name (m)) – Depths of flooding at each node, zero where no lake. Note that the component will dynamically update this array as it fills nodes with sediment (…but does NOT update any other related lake fields).

static __new__(cls, *args, **kwds)
property characteristic_grainsize

Return the characteristic grain size used by the component.

Particularly useful if the set_Dchar_from_threshold flag was True at initialization.

Returns:

Dchar

Return type:

float or array

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.components import FlowAccumulator, SedDepEroder
>>> mg1 = RasterModelGrid((3, 4))
>>> z1 = mg1.add_zeros("node", "topographic__elevation")
>>> fa1 = FlowAccumulator(mg1)
>>> thresh_shields = np.arange(1, mg1.number_of_nodes + 1, dtype=float)
>>> thresh_shields /= 100.0
>>> sde1 = SedDepEroder(
...     mg1,
...     threshold_shear_stress=100.0,
...     Qc="MPM",
...     Dchar=None,
...     set_threshold_from_Dchar=False,
...     set_Dchar_from_threshold=True,
...     threshold_Shields=thresh_shields,
...     g=9.81,
... )
>>> sde1.characteristic_grainsize.reshape(mg1.shape)
array([[0.59962823, 0.29981412, 0.19987608, 0.14990706],
       [0.11992565, 0.09993804, 0.08566118, 0.07495353],
       [0.06662536, 0.05996282, 0.05451166, 0.04996902]])

>>> mg2 = RasterModelGrid((3, 4))
>>> z2 = mg2.add_zeros("node", "topographic__elevation")
>>> fa2 = FlowAccumulator(mg2)
>>> sde2 = SedDepEroder(
...     mg2,
...     threshold_shear_stress=100.0,
...     Qc="MPM",
...     Dchar=None,
...     set_threshold_from_Dchar=False,
...     set_Dchar_from_threshold=True,
...     threshold_Shields=None,
...     slope_sensitive_threshold=True,
...     g=9.81,
... )
>>> S = mg2.at_node["topographic__steepest_slope"]
>>> S[:] = 0.05  # thresh = 100 Pa @ 5pc slope
>>> sde2.characteristic_grainsize.reshape(mg2.shape)
array([[0.08453729, 0.08453729, 0.08453729, 0.08453729],
       [0.08453729, 0.08453729, 0.08453729, 0.08453729],
       [0.08453729, 0.08453729, 0.08453729, 0.08453729]])
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 = (('channel__bed_shear_stress', 'Shear exerted on the bed of the channel, assuming all discharge travels along a single, self-formed channel'), ('channel__depth', 'Depth of the a single channel carrying all runoff through the node'), ('channel__discharge', 'Volumetric water flux of the a single channel carrying all runoff through the node'), ('channel__width', 'Width of the a single channel carrying all runoff through the node'), ('channel_sediment__relative_flux', 'The fluvial_sediment_flux_into_node divided by the fluvial_sediment_transport_capacity'), ('channel_sediment__volumetric_flux', 'Total volumetric fluvial sediment flux brought into the node from upstream'), ('channel_sediment__volumetric_transport_capacity', 'Volumetric transport capacity of a channel carrying all runoff through the node, assuming the Meyer-Peter Muller transport equation'), ('drainage_area', "Upstream accumulated surface area contributing to the node's discharge"), ('flow__link_to_receiver_node', 'ID of link downstream of each node, which carries the discharge'), ('flow__receiver_node', 'Node array of receivers (node that receives flow from current node)'), ('flow__upstream_node_order', 'Node array containing downstream-to-upstream ordered list of node IDs'), ('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

get_sed_flux_function(rel_sed_flux)[source]

Get the sediment flux function.

Parameters:

rel_sed_flux

get_sed_flux_function_pseudoimplicit(sed_in, trans_cap_vol_out, prefactor_for_volume, prefactor_for_dz)[source]

Get the pseudoimplicit sediment flux function.

Parameters:

  • sed_in

  • trans_cap_vol_out

  • prefactor_for_volume

  • prefactor_for_dz

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 = ('drainage_area', 'flow__link_to_receiver_node', 'flow__receiver_node', 'flow__upstream_node_order', 'topographic__elevation', 'topographic__steepest_slope')
name = 'SedDepEroder'
optional_var_names = ('channel__depth', 'channel__width')
output_var_names = ('channel__bed_shear_stress', 'channel__discharge', 'channel_sediment__relative_flux', 'channel_sediment__volumetric_flux', 'channel_sediment__volumetric_transport_capacity', 'topographic__elevation')
run_one_step(dt)[source]

Run the component across one timestep increment, dt.

Erosion occurs according to the sediment dependent rules specified during initialization. Method is fully equivalent to the erode method.

Parameters:

dt (float (years, only!)) – Timestep for which to run the component.

property shape

Return the grid shape attached to the component, if defined.

unit_agnostic = False
units = (('channel__bed_shear_stress', 'Pa'), ('channel__depth', 'm'), ('channel__discharge', 'm**3/s'), ('channel__width', 'm'), ('channel_sediment__relative_flux', '-'), ('channel_sediment__volumetric_flux', 'm**3/s'), ('channel_sediment__volumetric_transport_capacity', 'm**3/s'), ('drainage_area', 'm**2'), ('flow__link_to_receiver_node', '-'), ('flow__receiver_node', '-'), ('flow__upstream_node_order', '-'), ('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 = (('channel__bed_shear_stress', 'node'), ('channel__depth', 'node'), ('channel__discharge', 'node'), ('channel__width', 'node'), ('channel_sediment__relative_flux', 'node'), ('channel_sediment__volumetric_flux', 'node'), ('channel_sediment__volumetric_transport_capacity', 'node'), ('drainage_area', 'node'), ('flow__link_to_receiver_node', 'node'), ('flow__receiver_node', 'node'), ('flow__upstream_node_order', '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