NetworkSedimentTransporter: Lagrangian sediment transport in a river network#

class NetworkSedimentTransporter(*args, **kwds)[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, 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., 2., 1., 0.], at="node") # m
>>> _ = nmg.add_field("reach_length", [100., 100., 100.], 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 t in range(0, (timesteps * dt), dt):
...     nst.run_one_step(dt)

We can the link location of the parcel at each timestep

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

References

Required Software Citation(s) Specific to this Component

A JOSS submission has been prepared.

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. Default value is 0.3.

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

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

  • transport_method (string) – Sediment transport equation option. Default (and currently only) option is “WilcockCrowe”.

  • active_layer_method (string, optional) – Option for treating sediment active layer as a constant or variable (default, “WongParker”)

OUT_OF_NETWORK = -2#

Indicates a parcel is out of network

__init__(grid, parcels, flow_director, bed_porosity=0.3, g=9.80665, fluid_density=1000.0, transport_method='WilcockCrowe', active_layer_method='WongParker', active_layer_d_multiplier=2)[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. Default value is 0.3.

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

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

  • transport_method (string) – Sediment transport equation option. Default (and currently only) option is “WilcockCrowe”.

  • active_layer_method (string, optional) – Option for treating sediment active layer as a constant or variable (default, “WongParker”)

property d_mean_active#

Mean parcel grain size of active parcels aggregated at link.

property rhos_mean_active#

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 identifed 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.

Return type

RuntimeError if no parcels remain on the grid.

property time#

Return current time.