landlab.components.space.space_large_scale_eroder

Grid-based simulation of lateral erosion by channels in a drainage network.

Benjamin Campforts

class SpaceLargeScaleEroder[source]

Bases: Component

Stream Power with Alluvium Conservation and Entrainment large scale eroder.

The SpaceLargeScaleEroder is based on the SPACE component and is designed to be more robust against large time steps and coded in such a way that mass conservation is explicitly conserved during calculation.

See the publication:

Shobe, C. M., Tucker, G. E., and Barnhart, K. R.: The SPACE 1.0 model: a Landlab component for 2-D calculation of sediment transport, bedrock erosion, and landscape evolution, Geosci. Model Dev., 10, 4577-4604, https://doi.org/10.5194/gmd-10-4577-2017, 2017.

Unlike other some other fluvial erosion componets in Landlab, in this component (and class:~landlab.components.ErosionDeposition) no erosion occurs in depressions or in areas with adverse slopes. There is no ability to pass a keyword argument erode_flooded_nodes.

If depressions are handled (as indicated by the presence of the field "flood_status_code" at nodes), then deposition occurs throughout the depression and sediment is passed out of the depression. Where pits are encountered, then all sediment is deposited at that node only.

Note

In the current version, we do not provide an adaptive time stepper. This will be addded in future versions of this component.

For more explanation and examples, check out the correponding notebook of this component.

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.components import PriorityFloodFlowRouter
>>> from landlab.components import SpaceLargeScaleEroder

>>> mg = RasterModelGrid((5, 4), xy_spacing=100.0)

>>> mg.at_node["soil__depth"] = [
...     [0.0, 0.0, 0.0, 0.0],
...     [0.0, 2.0, 2.0, 0.0],
...     [0.0, 2.0, 2.0, 0.0],
...     [0.0, 2.0, 2.0, 0.0],
...     [0.0, 0.0, 0.0, 0.0],
... ]
>>> mg.at_node["bedrock__elevation"] = mg.y_of_node / 10.0 + mg.x_of_node / 10.0
>>> mg.at_node["topographic__elevation"] = (
...     mg.at_node["bedrock__elevation"] + mg.at_node["soil__depth"]
... )

>>> mg.set_closed_boundaries_at_grid_edges(
...     bottom_is_closed=True,
...     left_is_closed=True,
...     right_is_closed=True,
...     top_is_closed=True,
... )
>>> mg.set_watershed_boundary_condition_outlet_id(
...     0, mg.at_node["topographic__elevation"], -9999.0
... )

>>> fr = PriorityFloodFlowRouter(mg, flow_metric="D8", suppress_out=True)
>>> sp = SpaceLargeScaleEroder(
...     mg,
...     K_sed=0.01,
...     K_br=0.001,
...     F_f=0.0,
...     phi=0.0,
...     H_star=1.0,
...     v_s=5.0,
...     m_sp=0.5,
...     n_sp=1.0,
...     sp_crit_sed=0,
...     sp_crit_br=0,
... )

>>> node_next_to_outlet = mg.shape[1] + 1
>>> sed_flux = []
>>> for _ in range(500):
...     fr.run_one_step()
...     _ = sp.run_one_step(dt=10.0)
...     sed_flux.append(mg.at_node["sediment__flux"][node_next_to_outlet])
...

Look at the results.

>>> mg.at_node["sediment__flux"].reshape(mg.shape)  
array([[0.        , 0.        , 0.        , 0.        ],
       [0.        , 0.26889843, 0.02719885, 0.        ],
       [0.        , 0.09130624, 0.13962599, 0.        ],
       [0.        , 0.06421368, 0.09527108, 0.        ],
       [0.        , 0.        , 0.        , 0.        ]])
>>> sed_flux[::100]  
[2053.1526698811363,
 601.0591808186842,
 405.95978528106235,
 272.8232194793999,
 176.63159183013272]

References

Required Software Citation(s) Specific to this Component

Shobe, C., Tucker, G., Barnhart, K. (2017). The SPACE 1.0 model: a Landlab component for 2-D calculation of sediment transport, bedrock erosion, and landscape evolution. Geoscientific Model Development 10(12), 4577 - 4604. https://dx.doi.org/10.5194/gmd-10-4577-2017

Additional References

None Listed

Initialize the SpaceLargeScaleEroder model.

Parameters:

  • grid (ModelGrid) – Landlab ModelGrid object

  • K_sed (float, array of float, or str, optional) – Erodibility for sediment (units vary) as either a number or a field name.

  • K_br (float, array of float, or str, optional) – Erodibility for bedrock (units vary) as either a number or a field name.

  • F_f (float, optional) – Fraction of permanently suspendable fines in bedrock [-].

  • phi (float, optional) – Sediment porosity [-].

  • H_star (float, optional) – Sediment thickness required for full entrainment [L].

  • v_s (float, optional) – Effective settling velocity for chosen grain size metric [L/T].

  • v_s_lake (float, optional) – Effective settling velocity in lakes for chosen grain size metric [L/T].

  • m_sp (float, optional) – Drainage area exponent (units vary).

  • n_sp (float, optional) – Slope exponent (units vary).

  • sp_crit_sed (float, array of float, or str, optional) – Critical stream power to erode sediment [E/(TL^2)].

  • sp_crit_br (float, array of float, or str, optional) – Critical stream power to erode rock [E/(TL^2)]

  • discharge_field (float, array of float, or str, optional) – Discharge [L^2/T]. The default is to use the grid field ‘surface_water__discharge’, which is simply drainage area multiplied by the default rainfall rate (1 m/yr). To use custom spatially/temporally varying rainfall, use ‘water__unit_flux_in’ to specify water input to the FlowAccumulator.

  • erode_flooded_nodes (bool, optional) – Whether erosion occurs in flooded nodes identified by a depression/lake mapper (e.g., DepressionFinderAndRouter). When set to false, the field flood_status_code must be present on the grid (this is created by the DepressionFinderAndRouter). Default True.

property Er

Bedrock erosion term.

property Es

Sediment erosion term.

property K_br

Erodibility of bedrock(units depend on m_sp).

property K_sed

Erodibility of sediment(units depend on m_sp).

__init__(grid, K_sed=0.02, K_br=0.02, F_f=0.0, phi=0.3, H_star=0.1, v_s=1.0, v_s_lake=None, m_sp=0.5, n_sp=1.0, sp_crit_sed=0.0, sp_crit_br=0.0, discharge_field='surface_water__discharge', erode_flooded_nodes=False, thickness_lim=100.0)[source]

Initialize the SpaceLargeScaleEroder model.

Parameters:

  • grid (ModelGrid) – Landlab ModelGrid object

  • K_sed (float, array of float, or str, optional) – Erodibility for sediment (units vary) as either a number or a field name.

  • K_br (float, array of float, or str, optional) – Erodibility for bedrock (units vary) as either a number or a field name.

  • F_f (float, optional) – Fraction of permanently suspendable fines in bedrock [-].

  • phi (float, optional) – Sediment porosity [-].

  • H_star (float, optional) – Sediment thickness required for full entrainment [L].

  • v_s (float, optional) – Effective settling velocity for chosen grain size metric [L/T].

  • v_s_lake (float, optional) – Effective settling velocity in lakes for chosen grain size metric [L/T].

  • m_sp (float, optional) – Drainage area exponent (units vary).

  • n_sp (float, optional) – Slope exponent (units vary).

  • sp_crit_sed (float, array of float, or str, optional) – Critical stream power to erode sediment [E/(TL^2)].

  • sp_crit_br (float, array of float, or str, optional) – Critical stream power to erode rock [E/(TL^2)]

  • discharge_field (float, array of float, or str, optional) – Discharge [L^2/T]. The default is to use the grid field ‘surface_water__discharge’, which is simply drainage area multiplied by the default rainfall rate (1 m/yr). To use custom spatially/temporally varying rainfall, use ‘water__unit_flux_in’ to specify water input to the FlowAccumulator.

  • erode_flooded_nodes (bool, optional) – Whether erosion occurs in flooded nodes identified by a depression/lake mapper (e.g., DepressionFinderAndRouter). When set to false, the field flood_status_code must be present on the grid (this is created by the DepressionFinderAndRouter). Default True.

static __new__(cls, *args, **kwds)
cite_as = '\n    @Article{gmd-10-4577-2017,\n        AUTHOR = {Shobe, C. M. and Tucker, G. E. and Barnhart, K. R.},\n        TITLE = {The SPACE~1.0 model: a~Landlab component for 2-D calculation\n                 of sediment transport, bedrock erosion, and landscape evolution},\n        JOURNAL = {Geoscientific Model Development},\n        VOLUME = {10},\n        YEAR = {2017},\n        NUMBER = {12},\n        PAGES = {4577--4604},\n        URL = {https://www.geosci-model-dev.net/10/4577/2017/},\n        DOI = {10.5194/gmd-10-4577-2017}\n    }'
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 = (('bedrock__erosion_flux', 'Bedrock erosion flux from bedrock to water column (depth eroded per unit time)'), ('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'), ('sediment__deposition_flux', 'Sediment deposition flux from water column to bed (depth deposited per unit time)'), ('sediment__erosion_flux', 'Sediment erosion flux from bed to water column (depth eroded per unit time)'), ('sediment__influx', 'Sediment flux (volume per unit time of sediment entering each node)'), ('sediment__outflux', 'Sediment flux (volume per unit time of sediment leaving each node)'), ('soil__depth', 'Depth of soil or weathered bedrock'), ('surface_water__discharge', 'Volumetric discharge of surface water'), ('topographic__elevation', 'Land surface topographic elevation'), ('topographic__steepest_slope', 'The steepest *downhill* slope'))
property drainage_area_exp

Drainage area exponent (units vary).

property fraction_fines

Fraction of permanently suspendable fines in bedrock [-].

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__upstream_node_order', 'soil__depth', 'surface_water__discharge', 'topographic__elevation')
name = 'SpaceLargeScaleEroder'
optional_var_names = ('flow__link_to_receiver_node', 'topographic__steepest_slope')
output_var_names = ('bedrock__erosion_flux', 'sediment__deposition_flux', 'sediment__erosion_flux', 'sediment__influx', 'sediment__outflux', 'soil__depth', 'topographic__elevation')
run_one_step(dt)[source]

Returns: - vol_SSY_riv (float): Suspended sediment yield leaving the domain as wash load - V_leaving_riv (float): Volume of bedload sediment leaving the domain.

run_one_step_basic(dt=10)[source]
property sediment_influx

Volumetric sediment influx to each node.

property sediment_porosity

Sediment porosity [-].

property settling_velocity

Effective settling velocity for chosen grain size metric [L/T].

property shape

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

property slope_exp

Slope exponent (units vary).

unit_agnostic = True
units = (('bedrock__erosion_flux', 'm/s'), ('flow__link_to_receiver_node', '-'), ('flow__receiver_node', '-'), ('flow__upstream_node_order', '-'), ('sediment__deposition_flux', 'm/s'), ('sediment__erosion_flux', 'm/s'), ('sediment__influx', 'm3/s'), ('sediment__outflux', 'm3/s'), ('soil__depth', 'm'), ('surface_water__discharge', 'm**3/s'), ('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 = (('bedrock__erosion_flux', 'node'), ('flow__link_to_receiver_node', 'node'), ('flow__receiver_node', 'node'), ('flow__upstream_node_order', 'node'), ('sediment__deposition_flux', 'node'), ('sediment__erosion_flux', 'node'), ('sediment__influx', 'node'), ('sediment__outflux', 'node'), ('soil__depth', 'node'), ('surface_water__discharge', '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