landlab.components.detachment_ltd_erosion.generate_detachment_ltd_erosion¶

Landlab component that simulates detachment-limited river erosion.

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

class DetachmentLtdErosion[source]¶

Bases: Component

Simulate detachment limited sediment transport.

Landlab component that simulates detachment limited sediment transport is more general than the stream power component. Doesn’t require the upstream node order, links to flow receiver and flow receiver fields. Instead, takes in the discharge values on NODES calculated by the OverlandFlow class and erodes the landscape in response to the output discharge.

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 DetachmentLtdErosion

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

>>> grid = RasterModelGrid((4, 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.

>>> grid.at_node["topographic__elevation"] = [
...     [0.0, 0.0, 0.0, 0.0, 0.0],
...     [1.0, 1.0, 1.0, 1.0, 1.0],
...     [2.0, 2.0, 2.0, 2.0, 2.0],
...     [3.0, 3.0, 3.0, 3.0, 3.0],
... ]

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

>>> grid.at_node["topographic__slope"] = [
...     [0.0, 0.0, 0.0, 0.0, 0.0],
...     [0.70710678, 1.0, 1.0, 1.0, 0.70710678],
...     [0.70710678, 1.0, 1.0, 1.0, 0.70710678],
...     [0.70710678, 1.0, 1.0, 1.0, 0.70710678],
... ]

Now we will arbitrarily add water discharge to each node for simplicity.

>>> grid.at_node["surface_water__discharge"] = [
...     [30.0, 30.0, 30.0, 30.0, 30.0],
...     [20.0, 20.0, 20.0, 20.0, 20.0],
...     [10.0, 10.0, 10.0, 10.0, 10.0],
...     [5.0, 5.0, 5.0, 5.0, 5.0],
... ]

Instantiate the DetachmentLtdErosion component to work on this grid, and run it. In this simple case, we need to pass it a time step (‘dt’)

>>> dt = 10.0
>>> dle = DetachmentLtdErosion(grid)
>>> dle.run_one_step(dt=dt)

After calculating the erosion rate, the elevation field is updated in the grid. Use the output_var_names property to see the names of the fields that have been changed.

>>> dle.output_var_names
('topographic__elevation',)

The topographic__elevation field is defined at nodes.

>>> dle.var_loc("topographic__elevation")
'node'

Now we test to see how the topography changed as a function of the erosion rate.

>>> grid.at_node["topographic__elevation"].reshape(grid.shape)
array([[0.        , 0.        , 0.        , 0.        , 0.        ],
       [0.99936754, 0.99910557, 0.99910557, 0.99910557, 0.99936754],
       [1.99955279, 1.99936754, 1.99936754, 1.99936754, 1.99955279],
       [2.99968377, 2.99955279, 2.99955279, 2.99955279, 2.99968377]])

References

Required Software Citation(s) Specific to this Component

None Listed

Additional References

Howard, A. (1994). A detachment-limited model of drainage basin evolution. Water Resources Research 30(7), 2261-2285. https://dx.doi.org/10.1029/94wr00757

Calculate detachment limited erosion rate on nodes.

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

This component adjusts topographic elevation.

Parameters:

grid (RasterModelGrid) – A landlab grid.
K_sp (float, optional) – K in the stream power equation (units vary with other parameters - if used with the de Almeida equation it is paramount to make sure the time component is set to seconds, not years!)
m_sp (float, optional) – Stream power exponent, power on discharge
n_sp (float, optional) – Stream power exponent, power on slope
uplift_rate (float, optional) – changes in topographic elevation due to tectonic uplift
entrainment_threshold (float, optional) – threshold for sediment movement
slope (str) – Field name of an at-node field that contains the slope.

__init__(grid, K_sp=2e-05, m_sp=0.5, n_sp=1.0, uplift_rate=0.0, entrainment_threshold=0.0, slope='topographic__slope')[source]¶

Calculate detachment limited erosion rate on nodes.

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

This component adjusts topographic elevation.

Parameters:

grid (RasterModelGrid) – A landlab grid.
K_sp (float, optional) – K in the stream power equation (units vary with other parameters - if used with the de Almeida equation it is paramount to make sure the time component is set to seconds, not years!)
m_sp (float, optional) – Stream power exponent, power on discharge
n_sp (float, optional) – Stream power exponent, power on slope
uplift_rate (float, optional) – changes in topographic elevation due to tectonic uplift
entrainment_threshold (float, optional) – threshold for sediment movement
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__discharge', 'Volumetric discharge of surface water'), ('topographic__elevation', 'Land surface topographic elevation'), ('topographic__slope', 'gradient of the ground surface'))¶

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__discharge', 'topographic__elevation')¶

name = 'DetachmentLtdErosion'¶

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__discharge', 'm**3/s'), ('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__discharge', '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