landlab.components.network_sediment_transporter.network_sediment_transporter

Simulate transport of bed material through a 1-D river network.

Landlab component that simulates the transport of bed material sediment through a 1-D river network, while tracking the resulting changes in bed material grain size and river bed elevation. Model framework described in Czuba (2018). Additions include: particle abrasion, variable active layer thickness (Wong et al., 2007).

Code author: Allison Pfeiffer, Katy Barnhart, Jon Czuba, Eric Hutton

class NetworkSedimentTransporter[source]

Bases: Component

Move sediment parcels on a river network.

Landlab component that simulates the transport of bed material sediment through a 1-D river network, while tracking the resulting changes in bed material grain size and river bed elevation. Model framework described in Czuba (2018). Additions include: particle abrasion, and variable active layer thickness (Wong et al., 2007).

This component cares about units. Its time, length, and mass units are seconds, meters, and kilograms, by default. The horizontal unit of the grid, and the units of the parameters g and fluid_density are what specify the component units. In addition, the expressions used to calculate the transport have units (Wilcock and Crowe, 2003).

There is a function that assists in plotting the output of this component. It is called plot_network_and_parcels. Examples of its usage can be found in the NetworkSedimentTransporter notebooks (located in the “notebooks” folder).

Examples

>>> import numpy as np
>>> from landlab.components import FlowDirectorSteepest, NetworkSedimentTransporter
>>> from landlab import NetworkModelGrid
>>> from landlab.data_record import DataRecord

The NetworkSedimentTransporter moves “parcels” of sediment down a network based on a given flow and a given sediment transport formulation. The river network is represented by a landlab NetworkModelGrid. Flow direction in the network is determined using a landlab flow director. Sediment parcels are represented as items within a landlab DataRecord. The landlab DataRecord is used to track the location, grain size, sediment density, and total volume of each parcel.

Create a NetworkModelGrid to represent the river channel network. In this case, the grid is a single line of 4 nodes connected by 3 links. Each link represents a reach of river.

>>> y_of_node = (0, 0, 0, 0)
>>> x_of_node = (0, 100, 200, 300)
>>> nodes_at_link = ((0, 1), (1, 2), (2, 3))
>>> nmg = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)

Add required channel and topographic variables to the NetworkModelGrid.

>>> _ = nmg.add_field("bedrock__elevation", [3.0, 2.0, 1.0, 0.0], at="node")  # m
>>> _ = nmg.add_field("reach_length", [100.0, 100.0, 100.0], at="link")  # m
>>> _ = nmg.add_field("channel_width", (15 * np.ones(nmg.size("link"))), at="link")
>>> _ = nmg.add_field("flow_depth", (2 * np.ones(nmg.size("link"))), at="link")  # m

Add "topographic__elevation" to the grid because the FlowDirectorSteepest will look to it to determine the direction of sediment transport through the network. Each time we run the NetworkSedimentTransporter the topography will be updated based on the bedrock elevation and the distribution of alluvium.

>>> _ = nmg.add_field(
...     "topographic__elevation",
...     np.copy(nmg.at_node["bedrock__elevation"]),
...     at="node",
... )

Run FlowDirectorSteepest to determine the direction of sediment transport through the network.

>>> flow_director = FlowDirectorSteepest(nmg)
>>> flow_director.run_one_step()

Define the starting time and the number of timesteps for this model run.

>>> timesteps = 10
>>> time = [0.0]

Define the sediment characteristics that will be used to create the parcels DataRecord.

>>> items = {"grid_element": "link", "element_id": np.array([[0]])}

>>> variables = {
...     "starting_link": (["item_id"], np.array([0])),
...     "abrasion_rate": (["item_id"], np.array([0])),
...     "density": (["item_id"], np.array([2650])),
...     "time_arrival_in_link": (["item_id", "time"], np.array([[0]])),
...     "active_layer": (["item_id", "time"], np.array([[1]])),
...     "location_in_link": (["item_id", "time"], np.array([[0]])),
...     "D": (["item_id", "time"], np.array([[0.05]])),
...     "volume": (["item_id", "time"], np.array([[1]])),
... }

Create the sediment parcel DataRecord. In this case, we are creating a single sediment parcel with all of the required attributes.

>>> one_parcel = DataRecord(
...     nmg,
...     items=items,
...     time=time,
...     data_vars=variables,
...     dummy_elements={"link": [NetworkSedimentTransporter.OUT_OF_NETWORK]},
... )

Instantiate the model run

>>> nst = NetworkSedimentTransporter(
...     nmg,
...     one_parcel,
...     flow_director,
...     bed_porosity=0.03,
...     g=9.81,
...     fluid_density=1000,
...     transport_method="WilcockCrowe",
...     active_layer_method="WongParker",
... )

>>> dt = 60  # (seconds) 1 min timestep

Run the model

>>> for _ in range(timesteps):
...     nst.run_one_step(dt)
...

We can the link location of the parcel at each timestep

>>> one_parcel.dataset.element_id.values
array([[0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 2.]])

References

Required Software Citation(s) Specific to this Component

Pfeiffer, A., Barnhart, K., Czuba, J., & Hutton, E. (2020). NetworkSedimentTransporter: A Landlab component for bed material transport through river networks. Journal of Open Source Software, 5(53).

Additional References

Czuba, J. A. (2018). A Lagrangian framework for exploring complexities of mixed-size sediment transport in gravel-bedded river networks. Geomorphology, 321, 146-152.

Wilcock, P. R., & Crowe, J. C. (2003). Surface-based transport model for mixed-size sediment. Journal of Hydraulic Engineering, 129(2), 120-128.

Wong, M., Parker, G., DeVries, P., Brown, T. M., & Burges, S. J. (2007). Experiments on dispersion of tracer stones under lower‐regime plane‐bed equilibrium bed load transport. Water Resources Research, 43(3).

Parameters:

  • grid (NetworkModelGrid) – A NetworkModelGrid in which links are stream channel segments.

  • parcels (DataRecord) – A landlab DataRecord describing the characteristics and location of sediment “parcels”. At any given timestep, each parcel is located at a specified point along (location_in_link) a particular link (element_id). Each parcel has a total sediment volume (volume), sediment grain size (D), sediment density (density), and bed material abrasion rate (abrasion_rate). During a given timestep, parcels may be in the “active layer” of most recently deposited sediment (active_layer = 1), or they may be buried and not subject to transport (active_layer = 0). Whether a sediment parcel is active or not is determined based on flow conditions and parcel attributes in run_one_step.

  • flow_director (FlowDirectorSteepest) – A landlab flow director. Currently, must be FlowDirectorSteepest.

  • bed_porosity (float, optional) – Proportion of void space between grains in the river channel bed.

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

  • fluid_density (float, optional) – Density of the fluid (generally, water) in which sediment is moving [kg / m^3].

  • transport_method ({"WilcockCrowe"}, optional) – Sediment transport equation option.

  • active_layer_method ({"WongParker", "GrainSizeDependent", "Constant10cm"}, optional) – Option for treating sediment active layer as a constant or variable.

  • slope_threshold (float, optional) – Minimum channel slope at any given link. Slopes lower than this value will default to the threshold.

  • k_transp_dep_abr (float, optional) – Coefficient of enhanced abrasion at high bedload transport stage, as in Pfeiffer et al. (2022)

OUT_OF_NETWORK = -2

Indicates a parcel is out of network

__init__(grid, parcels, flow_director, bed_porosity=0.3, g=scipy.constants.g, fluid_density=1000.0, transport_method='WilcockCrowe', active_layer_method='WongParker', active_layer_d_multiplier=2, slope_threshold=0.0001, k_transp_dep_abr=None)[source]
Parameters:

  • grid (NetworkModelGrid) – A NetworkModelGrid in which links are stream channel segments.

  • parcels (DataRecord) – A landlab DataRecord describing the characteristics and location of sediment “parcels”. At any given timestep, each parcel is located at a specified point along (location_in_link) a particular link (element_id). Each parcel has a total sediment volume (volume), sediment grain size (D), sediment density (density), and bed material abrasion rate (abrasion_rate). During a given timestep, parcels may be in the “active layer” of most recently deposited sediment (active_layer = 1), or they may be buried and not subject to transport (active_layer = 0). Whether a sediment parcel is active or not is determined based on flow conditions and parcel attributes in run_one_step.

  • flow_director (FlowDirectorSteepest) – A landlab flow director. Currently, must be FlowDirectorSteepest.

  • bed_porosity (float, optional) – Proportion of void space between grains in the river channel bed.

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

  • fluid_density (float, optional) – Density of the fluid (generally, water) in which sediment is moving [kg / m^3].

  • transport_method ({"WilcockCrowe"}, optional) – Sediment transport equation option.

  • active_layer_method ({"WongParker", "GrainSizeDependent", "Constant10cm"}, optional) – Option for treating sediment active layer as a constant or variable.

  • slope_threshold (float, optional) – Minimum channel slope at any given link. Slopes lower than this value will default to the threshold.

  • k_transp_dep_abr (float, optional) – Coefficient of enhanced abrasion at high bedload transport stage, as in Pfeiffer et al. (2022)

  • active_layer_d_multiplier (int)

Return type:

None

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

property d_mean_active: float

Mean parcel grain size of active parcels aggregated at link.

definitions = (('bedrock__elevation', 'elevation of the bedrock surface'), ('channel_slope', 'Slope of the river channel through each reach'), ('channel_width', 'Flow width of the channel, assuming constant width'), ('flow_depth', 'Flow depth of the channel'), ('reach_length', 'Length of each reach'), ('topographic__elevation', 'Land surface topographic elevation'))
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 = ('bedrock__elevation', 'channel_width', 'flow_depth', 'reach_length')
name = 'NetworkSedimentTransporter'
optional_var_names = ()
output_var_names = ('channel_slope', 'topographic__elevation')
property rhos_mean_active: float

Mean parcel density of active parcels aggregated at link.

run_one_step(dt)[source]

Run NetworkSedimentTransporter forward in time.

When the NetworkSedimentTransporter runs forward in time the following steps occur:

  1. A new set of records is created in the Parcels that corresponds to the new time

  2. If parcels are on the network then:

    1. Active parcels are identified based on entrainment critera.

    2. Effective bed slope is calculated based on inactive parcel volumes.

    3. Transport rate is calculated.

    4. Active parcels are moved based on the tranport rate.

Parameters:

dt (float) – Duration of time to run the NetworkSedimentTransporter forward.

Raises:

RuntimeError – If no parcels remain on the grid.

Return type:

None

property shape

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

property time: float

Return current time.

unit_agnostic = False
units = (('bedrock__elevation', 'm'), ('channel_slope', 'm/m'), ('channel_width', 'm'), ('flow_depth', 'm'), ('reach_length', 'm'), ('topographic__elevation', 'm'))
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__elevation', 'node'), ('channel_slope', 'link'), ('channel_width', 'link'), ('flow_depth', 'link'), ('reach_length', 'link'), ('topographic__elevation', '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