landlab.components.space.space

class Space[source]

Bases: _GeneralizedErosionDeposition

Stream Power with Alluvium Conservation and Entrainment (SPACE)

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 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 a 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: If timesteps are large enough that Es*dt (sediment erosion) exceeds sediment thickness H, the ‘adaptive’ solver is necessary to subdivide timesteps. Compare Es and H arrays to determine whether timesteps are appropriate or too large for the ‘basic’ solver.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> from landlab.components import (
...     FlowAccumulator,
...     DepressionFinderAndRouter,
...     Space,
...     FastscapeEroder,
... )
>>> np.random.seed(seed=5000)

Define grid and initial topography:

  • 5x5 grid with base level in the lower left corner

  • All other boundary nodes closed

  • Initial topography is plane tilted up to the upper right with noise

>>> mg = RasterModelGrid((5, 5), xy_spacing=10.0)
>>> _ = mg.add_zeros("topographic__elevation", at="node")
>>> mg.at_node["topographic__elevation"] += (
...     mg.node_y / 10.0 + mg.node_x / 10.0 + np.random.rand(len(mg.node_y)) / 10.0
... )
>>> 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
... )
>>> fsc_dt = 100.0
>>> space_dt = 100.0

Instantiate Fastscape eroder, flow router, and depression finder

>>> fr = FlowAccumulator(mg, flow_director="D8")
>>> df = DepressionFinderAndRouter(mg)
>>> fsc = FastscapeEroder(mg, K_sp=0.001, m_sp=0.5, n_sp=1)

Burn in an initial drainage network using the Fastscape eroder:

>>> for _ in range(100):
...     fr.run_one_step()
...     df.map_depressions()
...     fsc.run_one_step(dt=fsc_dt)
...     mg.at_node["topographic__elevation"][0] -= 0.001  # Uplift
...

Add some soil to the drainage network:

>>> _ = mg.add_zeros("soil__depth", at="node", dtype=float)
>>> mg.at_node["soil__depth"] += 0.5
>>> mg.at_node["topographic__elevation"] += mg.at_node["soil__depth"]

Instantiate the Space component:

>>> ha = Space(
...     mg,
...     K_sed=0.00001,
...     K_br=0.00000000001,
...     F_f=0.5,
...     phi=0.1,
...     H_star=1.0,
...     v_s=0.001,
...     m_sp=0.5,
...     n_sp=1.0,
...     sp_crit_sed=0,
...     sp_crit_br=0,
... )

Now run the Space component for 2000 short timesteps:

>>> for _ in range(2000):  # Space component loop
...     fr.run_one_step()
...     df.map_depressions()
...     ha.run_one_step(dt=space_dt)
...     mg.at_node["bedrock__elevation"][0] -= 2e-6 * space_dt
...

Now we test to see if soil depth and topography are right:

>>> np.around(mg.at_node["soil__depth"], decimals=3)
array([0.5  , 0.5  , 0.5  , 0.5  , 0.5  , 0.5  , 0.495, 0.492,
       0.491, 0.5  , 0.5  , 0.492, 0.492, 0.49 , 0.5  , 0.5  ,
       0.491, 0.49 , 0.484, 0.5  , 0.5  , 0.5  , 0.5  , 0.5  ,
       0.5  ])

>>> np.around(mg.at_node["topographic__elevation"], decimals=3)
array([0.423, 1.536, 2.573, 3.511, 4.561, 1.582, 0.424, 0.428,
       0.438, 5.51 , 2.54 , 0.428, 0.428, 0.438, 6.526, 3.559,
       0.438, 0.438, 0.45 , 7.553, 4.559, 5.541, 6.57 , 7.504,
       8.51 ])

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 Space model.

Parameters:

  • grid (ModelGrid) – Landlab ModelGrid object

  • K_sed (float, field name, or array) – Erodibility for sediment (units vary).

  • K_br (float, field name, or array) – Erodibility for bedrock (units vary).

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

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

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

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

  • m_sp (float) – Drainage area exponent (units vary)

  • n_sp (float) – Slope exponent (units vary)

  • sp_crit_sed (float, field name, or array) – Critical stream power to erode sediment [E/(TL^2)]

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

  • discharge_field (float, field name, or array) – 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.

  • solver (string) –

    Solver to use. Options at present include:

    1. ’basic’ (default): explicit forward-time extrapolation. Simple but will become unstable if time step is too large.

    2. ’adaptive’: subdivides global time step as needed to prevent slopes from reversing and alluvium from going negative.

property Er

Bedrock erosion term.

property Es

Sediment erosion term.

property H

Sediment thickness.

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.002, K_br=0.002, F_f=0.0, phi=0.3, H_star=0.1, v_s=1.0, m_sp=0.5, n_sp=1.0, sp_crit_sed=0.0, sp_crit_br=0.0, discharge_field='surface_water__discharge', solver='basic', dt_min=0.001)[source]

Initialize the Space model.

Parameters:

  • grid (ModelGrid) – Landlab ModelGrid object

  • K_sed (float, field name, or array) – Erodibility for sediment (units vary).

  • K_br (float, field name, or array) – Erodibility for bedrock (units vary).

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

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

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

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

  • m_sp (float) – Drainage area exponent (units vary)

  • n_sp (float) – Slope exponent (units vary)

  • sp_crit_sed (float, field name, or array) – Critical stream power to erode sediment [E/(TL^2)]

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

  • discharge_field (float, field name, or array) – 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.

  • solver (string) –

    Solver to use. Options at present include:

    1. ’basic’ (default): explicit forward-time extrapolation. Simple but will become unstable if time step is too large.

    2. ’adaptive’: subdivides global time step as needed to prevent slopes from reversing and alluvium from going negative.

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 = (('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__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'))
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__link_to_receiver_node', 'flow__receiver_node', 'flow__upstream_node_order', 'soil__depth', 'surface_water__discharge', 'topographic__elevation', 'topographic__steepest_slope')
property m_sp

Discharge exponent (units vary).

property n_sp

Slope exponent (units vary).

name = 'Space'
optional_var_names = ()
output_var_names = ('sediment__influx', 'sediment__outflux', 'soil__depth', 'topographic__elevation')
run_one_step_basic(dt=1.0)[source]

Calculate change in rock and alluvium thickness for a time period ‘dt’.

Parameters:

dt (float) – Model timestep [T]

run_with_adaptive_time_step_solver(dt=1.0)[source]

Run step with CHILD-like solver that adjusts time steps to prevent slope flattening.

Parameters:

dt (float) – Model timestep [T]

Examples

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

>>> rg = RasterModelGrid((3, 4))
>>> z = rg.add_zeros("topographic__elevation", at="node")
>>> z[:] = 0.1 * rg.x_of_node
>>> H = rg.add_zeros("soil__depth", at="node")
>>> H += 0.1
>>> br = rg.add_zeros("bedrock__elevation", at="node")
>>> br[:] = z - H

>>> fa = FlowAccumulator(rg, flow_director="FlowDirectorSteepest")
>>> fa.run_one_step()
>>> sp = Space(
...     rg,
...     K_sed=1.0,
...     K_br=0.1,
...     F_f=0.5,
...     phi=0.0,
...     H_star=1.0,
...     v_s=1.0,
...     m_sp=0.5,
...     n_sp=1.0,
...     sp_crit_sed=0,
...     sp_crit_br=0,
...     solver="adaptive",
... )
>>> sp.run_one_step(dt=10.0)

>>> np.round(sp.Es[5:7], 4)
array([0.0029, 0.0074])
>>> np.round(sp.Er[5:7], 4)
array([0.0032, 0.0085])
>>> np.round(H[5:7], 3)
array([0.088, 0.078])
property sediment_influx

Volumetric sediment influx to each node.

property shape

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

unit_agnostic = True
units = (('flow__link_to_receiver_node', '-'), ('flow__receiver_node', '-'), ('flow__upstream_node_order', '-'), ('sediment__influx', 'm3/s'), ('sediment__outflux', 'm3/s'), ('soil__depth', 'm'), ('surface_water__discharge', 'm**3/s'), ('topographic__elevation', 'm'), ('topographic__steepest_slope', '-'))
property v_s

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

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__link_to_receiver_node', 'node'), ('flow__receiver_node', 'node'), ('flow__upstream_node_order', '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