landlab.components.detachment_ltd_erosion.generate_erosion_by_depth_slope

Landlab component that simulates detachment-limited river erosion.

This component calculates changes in elevation in response to vertical incision.

class DepthSlopeProductErosion[source]

Bases: Component

Calculate erosion rate as a function of the depth-slope product.

Erosion rate is calculated as, erosion_rate = k_e * ((tau ** a - tau_crit ** a))

k_e

Erodibility coefficient

tau

Bed shear stress: tau = rho * g * h * S

rho

Density of fluid

g

Gravitational acceleration

h

Water depths

S

Slope

tau_crit

Critical shear stress

a

Positive exponent

Note this equation was presented in Tucker, G.T., 2004, Drainage basin sensitivity to tectonic and climatic forcing: Implications of a stochastic model for the role of entrainment and erosion thresholds, Earth Surface Processes and Landforms.

More generalized than other erosion components, as it doesn’t require the upstream node order, links to flow receiver and flow receiver fields. Instead, takes in the water depth and slope fields on NODES calculated by the OverlandFlow class and erodes the landscape in response to the hydrograph generted by that method.

As of right now, this component relies on the OverlandFlow component for stability. There are no stability criteria implemented in this class. To ensure model stability, use StreamPowerEroder or FastscapeEroder components instead.

Code author: Jordan Adams

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> from landlab.components import DepthSlopeProductErosion

Create a grid on which to calculate detachment ltd sediment transport.

>>> grid = RasterModelGrid((5, 5))

The grid will need some data to provide the detachment limited sediment transport component. To check the names of the fields that provide input to the detachment ltd transport component, use the input_var_names class property.

Create fields of data for each of these input variables.

First create topography. This is a flat surface of elevation 10 m.

>>> grid.at_node["topographic__elevation"] = np.ones(grid.number_of_nodes)
>>> grid.at_node["topographic__elevation"] *= 10.0
>>> grid.at_node["topographic__elevation"] = [
...     [10.0, 10.0, 10.0, 10.0, 10.0],
...     [10.0, 10.0, 10.0, 10.0, 10.0],
...     [10.0, 10.0, 10.0, 10.0, 10.0],
...     [10.0, 10.0, 10.0, 10.0, 10.0],
...     [10.0, 10.0, 10.0, 10.0, 10.0],
... ]

Now we’ll add an arbitrary water depth field on top of that topography.

>>> grid.at_node["surface_water__depth"] = [
...     [5.0, 5.0, 5.0, 5.0, 5.0],
...     [4.0, 4.0, 4.0, 4.0, 4.0],
...     [3.0, 3.0, 3.0, 3.0, 3.0],
...     [2.0, 2.0, 2.0, 2.0, 2.0],
...     [1.0, 1.0, 1.0, 1.0, 1.0],
... ]

Using the set topography, now we will calculate slopes on all nodes.

First calculating slopes on links

>>> grid.at_link["water_surface__slope"] = grid.calc_grad_at_link(
...     "surface_water__depth"
... )

Now putting slopes on nodes

>>> grid.at_node["water_surface__slope"] = (
...     grid.at_link["water_surface__slope"][grid.links_at_node]
...     * grid.active_link_dirs_at_node
... ).max(axis=1)
>>> grid.at_node["water_surface__slope"][grid.core_nodes]
array([1., 1., 1., 1., 1., 1., 1., 1., 1.])

Instantiate the DepthSlopeProductErosion component to work on this grid, and run it. In this simple case, we need to pass it a time step (‘dt’) and also an erodibility factor (‘k_e’).

>>> dt = 1.0
>>> dspe = DepthSlopeProductErosion(
...     grid, k_e=0.00005, g=9.81, slope="water_surface__slope"
... )
>>> dspe.run_one_step(
...     dt=dt,
... )

Now we test to see how the topography changed as a function of the erosion rate. First, we’ll look at the erosion rate:

>>> dspe.dz.reshape(grid.shape)
array([[ 0.    , -2.4525, -2.4525, -2.4525,  0.    ],
       [ 0.    , -1.962 , -1.962 , -1.962 ,  0.    ],
       [ 0.    , -1.4715, -1.4715, -1.4715,  0.    ],
       [ 0.    , -0.981 , -0.981 , -0.981 ,  0.    ],
       [ 0.    ,  0.    ,  0.    ,  0.    ,  0.    ]])

Now, our updated topography…

>>> grid.at_node["topographic__elevation"].reshape(grid.shape)
array([[10.    ,  7.5475,  7.5475,  7.5475, 10.    ],
       [10.    ,  8.038 ,  8.038 ,  8.038 , 10.    ],
       [10.    ,  8.5285,  8.5285,  8.5285, 10.    ],
       [10.    ,  9.019 ,  9.019 ,  9.019 , 10.    ],
       [10.    , 10.    , 10.    , 10.    , 10.    ]])

Calculate detachment limited erosion rate on nodes using the shear stress equation, solved using the depth slope product.

Landlab component that generalizes the detachment limited erosion equation, primarily to be coupled to the the Landlab OverlandFlow component.

This component adjusts topographic elevation and is contained in the landlab.components.detachment_ltd_erosion folder.

Parameters:

  • grid (RasterModelGrid) – A landlab grid.

  • k_e (float) – Erodibility parameter, (m^(1+a_exp)*s^(2*a_exp-1)/kg^a_exp)

  • fluid_density (float, optional) – Density of fluid, default set to water density of 1000 kg / m^3

  • g (float, optional) – Acceleration due to gravity (m/s^2).

  • a_exp (float, optional) – exponent on shear stress, positive, unitless

  • tau_crit (float, optional) – threshold for sediment movement, (kg/m/s^2)

  • uplift_rate (float, optional) – uplift rate applied to the topographic surface, m/s

  • slope (str) – Field name of an at-node field that contains the slope.

__init__(grid, k_e=0.001, fluid_density=1000.0, g=scipy.constants.g, a_exp=1.0, tau_crit=0.0, uplift_rate=0.0, slope='topographic__slope')[source]

Calculate detachment limited erosion rate on nodes using the shear stress equation, solved using the depth slope product.

Landlab component that generalizes the detachment limited erosion equation, primarily to be coupled to the the Landlab OverlandFlow component.

This component adjusts topographic elevation and is contained in the landlab.components.detachment_ltd_erosion folder.

Parameters:

  • grid (RasterModelGrid) – A landlab grid.

  • k_e (float) – Erodibility parameter, (m^(1+a_exp)*s^(2*a_exp-1)/kg^a_exp)

  • fluid_density (float, optional) – Density of fluid, default set to water density of 1000 kg / m^3

  • g (float, optional) – Acceleration due to gravity (m/s^2).

  • a_exp (float, optional) – exponent on shear stress, positive, unitless

  • tau_crit (float, optional) – threshold for sediment movement, (kg/m/s^2)

  • uplift_rate (float, optional) – uplift rate applied to the topographic surface, m/s

  • slope (str) – Field name of an at-node field that contains the slope.

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 = (('surface_water__depth', 'Depth of water on the surface'), ('topographic__elevation', 'Land surface topographic elevation'), ('topographic__slope', 'gradient of the ground surface'))
property dz

Magnitude of change of the topographic__elevation due to erosion [L].

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 = ('surface_water__depth', 'topographic__elevation')
name = 'DepthSlopeProductErosion'
optional_var_names = ('topographic__slope',)
output_var_names = ('topographic__elevation',)
run_one_step(dt)[source]

Erode into grid topography.

For one time step, this erodes into the grid topography using the water discharge and topographic slope.

The grid field ‘topographic__elevation’ is altered each time step.

Parameters:

dt (float) – Time step.

property shape

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

unit_agnostic = True
units = (('surface_water__depth', 'm'), ('topographic__elevation', 'm'), ('topographic__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 = (('surface_water__depth', 'node'), ('topographic__elevation', 'node'), ('topographic__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