NetworkSedimentTransporter: Lagrangian sediment transport in a river network#

class BedParcelInitializerArea(*args, **kwds)[source]#

Bases: BedParcelInitializerBase

Create a landlab DataRecord to represent parcels of sediment on a river network.

The function takes a coefficient and exponent in a grain size-drainage area power law scaling relationship, as well as channel attribute (drainage_area, channel_width, reach_length, channel_slope) fields attached to the NetworkModelGrid.

This function currently estimates median parcel grain size at a link using a power-law scaling relationship between drainage area and median grain size (\(d_{50} = c A^n\)), assuming a lognormal parcel grain size distribution.

Code author: Eric Hutton, Allison Pfeiffer, Muneer Ahammad

Parameters:

  • grid (ModelGrid) – landlab ModelGrid to place sediment parcels on.

  • time (float, optional) – The initial time to add to the record.

  • drainage_area_coefficient (float, optional) – Coefficient in a power law grain size-drainage area scaling relationship.

  • drainage_area_exponent (float, optional) – Exponent in a power law grain size-drainage area scaling relationship.

  • rho_sediment (float, optional) – Sediment grain density [kg / m^3].

  • rho_water (float, optional) – Density of water [kg / m^3].

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

  • D84_D50 (float, optional) – Ratio of D84:D50, used to set lognormal distribution of grain size.

  • sed_thickness (float, optional) – Sediment thickness in multiples of d84.

  • abrasion_rate (float, optional) – Abrasion rate of parcels during transport [1 / m].

  • median_number_of_starting_parcels (int, optional) – Median number of parcels in a link.

  • extra_parcel_attributes (str or list of str, optional) – Name of user-defined parcel attribute to be added to parcel data record, which will be returned as an empty parcel attribute.

Examples

>>> from landlab import NetworkModelGrid
>>> from landlab.components.network_sediment_transporter import (
...     BedParcelInitializerArea,
... )

>>> y_of_node = (0, 100, 200, 200, 300, 400, 400, 125)
>>> x_of_node = (0, 0, 100, -50, -100, 50, -150, -100)
>>> nodes_at_link = ((1, 0), (2, 1), (1, 7), (3, 1), (3, 4), (4, 5), (4, 6))

>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)

>>> _ = grid.add_full("channel_width", 1.0, at="link")  # m
>>> _ = grid.add_full("channel_slope", 0.01, at="link")  # m / m
>>> _ = grid.add_full("reach_length", 100.0, at="link")  # m
>>> _ = grid.add_full("drainage_area", 100.0, at="link")

>>> initialize_parcels = BedParcelInitializerArea(
...     grid, drainage_area_coefficient=0.1, drainage_area_exponent=0.3
... )
>>> parcels = initialize_parcels()
calc_d50()[source]#
class BedParcelInitializerDepth(*args, **kwds)[source]#

Bases: BedParcelInitializerBase

Create a landlab DataRecord to represent parcels of sediment on a river network.

The function takes dominant flow depth for each link as input, as well as channel geometry (channel_width, reach_length, channel_slope) fields attached to the NetworkModelGrid.

This function currently estimates median parcel grain size at a link using the formative Shields stress (as in Pfeiffer et al., 2017), assuming a lognormal parcel grain size distribution.

Code author: Eric Hutton, Allison Pfeiffer, Muneer Ahammad

Parameters:

  • grid (ModelGrid) – landlab ModelGrid to place sediment parcels on.

  • time (float, optional) – The initial time to add to the record.

  • flow_depth_at_link (float, optional) – Dominant/formative flow depth at each link in the network.

  • tau_c_multiplier (float, optional) – Coefficient to relate critical and dominant/bankfull/formative Shields stress. Dominant/formative/bankfull Shields stress is calculated as multiplier * critical.

  • tau_c_50 (float, optional) – Critical Shields stress for d50 at dominant discharge for all links, used to calculate median parcel grain size

  • rho_sediment (float, optional) – Sediment grain density [kg / m^3].

  • rho_water (float, optional) – Density of water [kg / m^3].

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

  • D84_D50 (float, optional) – Ratio of D84:D50, used to set lognormal distribution of grain size.

  • sed_thickness (float, optional) – Sediment thickness in multiples of d84.

  • abrasion_rate (float, optional) – Abrasion rate of parcels during transport [1 / m].

  • median_number_of_starting_parcels (int, optional) – Median number of parcels in a link.

  • extra_parcel_attributes (str or list of str, optional) – Name of user-defined parcel attribute to be added to parcel data record, which will be returned as an empty parcel attribute.

Examples

>>> from landlab import NetworkModelGrid
>>> from landlab.components.network_sediment_transporter import (
...     BedParcelInitializerDepth,
... )

>>> y_of_node = (0, 100, 200, 200, 300, 400, 400, 125)
>>> x_of_node = (0, 0, 100, -50, -100, 50, -150, -100)
>>> nodes_at_link = ((1, 0), (2, 1), (1, 7), (3, 1), (3, 4), (4, 5), (4, 6))
>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)
>>> _ = grid.add_full("channel_width", 1.0, at="link")  # m
>>> _ = grid.add_full("channel_slope", 0.01, at="link")  # m / m
>>> _ = grid.add_full("reach_length", 100.0, at="link")  # m

>>> depth = np.full(grid.number_of_links, 1.0)  # m
>>> initialize_parcels = BedParcelInitializerDepth(grid, flow_depth_at_link=depth)
>>> parcels = initialize_parcels()
calc_d50()[source]#
class BedParcelInitializerDischarge(*args, **kwds)[source]#

Bases: BedParcelInitializerBase

Create a landlab DataRecord to represent parcels of sediment on a river network.

The function takes discharge data for each link as input, as well as channel geometry (channel_width, reach_length, channel_slope) fields attached to the NetworkModelGrid.

This function currently estimates median parcel grain size at a link according to Snyder et al. (2013), assuming a lognormal parcel grain size distribution.

Code author: Eric Hutton, Allison Pfeiffer, Muneer Ahammad

Parameters:

  • grid (NetworkModelGrid) – landlab NetworkModelGrid to place sediment parcels on.

  • time (float, optional) – The initial time to add to the record.

  • discharge_at_link (float) – Dominant/formative discharge at each link in the network [m^3 / s].

  • mannings_n (float, optional) – Manning’s n value for all links, used to calculate median parcel grain size at a link.

  • tau_c_50 (float, optional) – Critical Shields stress for d50 at dominant discharge for all links, used to calculate median parcel grain size.

  • rho_sediment (float, optional) – Sediment grain density [kg / m^3].

  • rho_water (float, optional) – Density of water [kg / m^3].

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

  • D84_D50 (float, optional) – Ratio of D84:D50, used to set lognormal distribution of grain size.

  • sed_thickness (float, optional) – Sediment thickness in multiples of d84.

  • abrasion_rate (float, optional) – Abrasion rate of parcels during transport [1/m].

  • median_number_of_starting_parcels (int, optional) – Median number of parcels in a link.

  • extra_parcel_attributes (str or list of str, optional) – Name of user-defined parcel attribute to be added to parcel data record, which will be returned as an empty parcel attribute.

Examples

>>> from landlab import NetworkModelGrid
>>> from landlab.components.network_sediment_transporter import (
...     BedParcelInitializerDischarge,
... )

>>> y_of_node = (0, 100, 200, 200, 300, 400, 400, 125)
>>> x_of_node = (0, 0, 100, -50, -100, 50, -150, -100)
>>> nodes_at_link = ((1, 0), (2, 1), (1, 7), (3, 1), (3, 4), (4, 5), (4, 6))

>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)

>>> _ = grid.add_full("channel_width", 1.0, at="link")  # m
>>> _ = grid.add_full("channel_slope", 0.01, at="link")  # m / m
>>> _ = grid.add_full("reach_length", 100.0, at="link")  # m

>>> discharge = np.full(grid.number_of_links, 10.0)  # m^3 / s
>>> initialize_parcels = BedParcelInitializerDischarge(
...     grid, discharge_at_link=discharge
... )
>>> parcels = initialize_parcels()
calc_d50()[source]#
class BedParcelInitializerUserD50(*args, **kwds)[source]#

Bases: BedParcelInitializerBase

Create a landlab DataRecord to represent parcels of sediment on a river network.

The function takes either a scalar value or an array (of of length, number_of_links) to assign the median grain size for parcels on each link in the network grid.

This function creates a lognormal grain size distribution for the parcels in the link.

Code author: Eric Hutton, Allison Pfeiffer, Muneer Ahammad

Parameters:

  • grid (ModelGrid) – landlab ModelGrid to place sediment parcels on.

  • time (float, optional) – The initial time to add to the record.

  • user_d50 (float, optional) – Either an array of d50 (of length number_of_links) or a scalar to be applied to all links in the network.

  • rho_sediment (float, optional) – Sediment grain density [kg / m^3].

  • rho_water (float, optional) – Density of water [kg / m^3].

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

  • D84_D50 (float, optional) – Ratio of D84:D50, used to set lognormal distribution of grain size.

  • sed_thickness (float, optional) – Sediment thickness in multiples of d84.

  • abrasion_rate (float, optional) – Abrasion rate of parcels during transport [1 / m].

  • median_number_of_starting_parcels (int, optional) – Median number of parcels in a link.

  • extra_parcel_attributes (str or list of str, optional) – Name of user-defined parcel attribute to be added to parcel data record, which will be returned as an empty parcel attribute.

Examples

>>> from landlab import NetworkModelGrid
>>> from landlab.components.network_sediment_transporter import (
...     BedParcelInitializerUserD50,
... )

>>> y_of_node = (0, 100, 200, 200, 300, 400, 400, 125)
>>> x_of_node = (0, 0, 100, -50, -100, 50, -150, -100)
>>> nodes_at_link = ((1, 0), (2, 1), (1, 7), (3, 1), (3, 4), (4, 5), (4, 6))

>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)

>>> _ = grid.add_full("channel_width", 1.0, at="link")  # m
>>> _ = grid.add_full("channel_slope", 0.01, at="link")  # m / m
>>> _ = grid.add_full("reach_length", 100.0, at="link")  # m

>>> initialize_parcels = BedParcelInitializerUserD50(grid, user_d50=0.05)
>>> parcels = initialize_parcels()
calc_d50()[source]#
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.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 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

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.

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, slope_threshold=0.0001)[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.

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

property time#

Return current time.

Bases: SedimentPulserBase

Send a pulse of parcels to specific links in a channel network

SedimentPulserAtLinks is instantiated by specifying the NetworkModelGrid it will pulse the parcels into and the time(s) when a pulse is allowed to occur. It inherits attributes and functions from the SedimentPulserBase.

SedimentPulserAtLinks is run (adds parcels to DataRecord) by calling the instance with a list of links and a list of the number of parcels added to each link.

If parcel attributes are constant with time and uniform across the basin, these constant-uniform-attributes can be defined when SedimentPulserAtLinks is instantiated. If parcel attributes vary with location and time, the user specifies the varying parcel attributes each time the instance is called with a list for each attribute of length equal to the number of links included in the pulse.

Code author: Jeff Keck, Allison Pfeiffer, Shelby Ahrendt (with help from Eric Hutton and Katy Barnhart)

Examples

>>> import numpy as np
>>> from landlab import NetworkModelGrid

Create the network model grid the parcels will be added to.

>>> y_of_node = (0, 100, 200, 200, 300, 400, 400, 125)
>>> x_of_node = (0, 0, 100, -50, -100, 50, -150, -100)
>>> nodes_at_link = ((1, 0), (2, 1), (1, 7), (3, 1), (3, 4), (4, 5), (4, 6))
>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)
>>> grid.at_link["channel_width"] = np.full(grid.number_of_links, 1.0)  # m
>>> grid.at_link["channel_slope"] = np.full(grid.number_of_links, 0.01)  # m / m
>>> grid.at_link["reach_length"] = np.full(grid.number_of_links, 100.0)  # m

Define a function that contains which times a pulse is allowed to occur. This function says a pulse can occur at any time

>>> def time_to_pulse(time):
...     return True
...

Instantiate SedimentPulserAtLinks

>>> make_pulse = SedimentPulserAtLinks(grid, time_to_pulse=time_to_pulse)

Run the instance with inputs for the time, link location and number of parcels. Other attributes will use the default values in the base class

>>> time = 11
>>> links = [2, 6]
>>> n_parcels_at_link = [2, 3]
>>> parcels = make_pulse(
...     time=time, links=links, n_parcels_at_link=n_parcels_at_link
... )

Check the element_id of each parcel

>>> print(parcels.dataset["element_id"].values)
[[2]
 [2]
 [6]
 [6]
 [6]]

Create SedimentPulserAtLinks.

Parameters:

  • grid (ModelGrid) – landlab ModelGrid to place sediment parcels on.

  • time_to_pulse (function, optional) – The condition when a pulse occurs using the _pulse_characteristics method. If not specified, a pulse occurs whenever the instance is run

  • parcels (landlab DataRecord) – Tracks parcel location and variables.

  • D50 (float, optional) – Median grain size [m].

  • D84_D50 (float, optional) – Ratio of 84th percentile grain size to the median grain size.

  • rho_sediment (float, optional) – Sediment grain density [kg / m^3].

  • parcel_volume (float) – Parcel volume [m^3]

  • abrasion_rate (float) – Volumetric abrasion exponent [1 / m]

__call__(time, links=None, n_parcels_at_link=None, D50=None, D84_D50=None, rho_sediment=None, parcel_volume=None, abrasion_rate=None)[source]#

specify the time, link(s) and attributes of pulses added to a NetworkModelGrid at stochastically determined locations within the link(s).

Parameters:

  • time (integer or datetime64) – Time that the pulse is occurs.

  • links (list of int) – Link ID # that parcels are added to.

  • n_parcels_at_link (list of int) – Number of parcels added to each link listed in links

  • D50 (list of float, optional) – Median grain size of parcels added to each link listed in links [m].

  • D84_D50 (list of float, optional) – Ratio of 84th percentile grain size to the median grain size.

  • rho_sediment (list of float, optional) – Density of grains [kg / m^3].

  • parcel_volume (list of float, optional) – Volume of each parcel added to link listed in links [m^3].

  • abrasion_rate (list of float, optional) – Rate that grain size decreases with distance along channel [mm / km?].

Returns:

DataRecord containing all information on each individual parcel.

Return type:

parcels

__init__(grid, time_to_pulse=None, parcels=None, D50=0.05, D84_D50=2.1, rho_sediment=2650.0, parcel_volume=0.5, abrasion_rate=0.0, rng=None)[source]#

Create SedimentPulserAtLinks.

Parameters:

  • grid (ModelGrid) – landlab ModelGrid to place sediment parcels on.

  • time_to_pulse (function, optional) – The condition when a pulse occurs using the _pulse_characteristics method. If not specified, a pulse occurs whenever the instance is run

  • parcels (landlab DataRecord) – Tracks parcel location and variables.

  • D50 (float, optional) – Median grain size [m].

  • D84_D50 (float, optional) – Ratio of 84th percentile grain size to the median grain size.

  • rho_sediment (float, optional) – Sediment grain density [kg / m^3].

  • parcel_volume (float) – Parcel volume [m^3]

  • abrasion_rate (float) – Volumetric abrasion exponent [1 / m]

class SedimentPulserEachParcel(*args, **kwds)[source]#

Bases: SedimentPulserBase

Send pulses of sediment to specific point locations within the channel network and divide the pulses into parcels. Pulses may be any volume. Parcels must be less than or equal to a user specified maximum volume.

SedimentPulserEachParcel is instantiated by specifying the network model grid it will pulse the parcels into

SedimentPulserEachParcel is run (adds parcels to DataRecrod) by calling the SedimentPulserEachParcel instance with the time that pulses are added to the channel network and a sediment pulse table (PulseDF)

PulseDF is a pandas dataframe. At a minimum, the dataframe must have columns ‘Link#’ ‘normalized_downstream_distance’ and ‘pulse_volume’. Optionally, the parcel volume that the pulse is divided into and grain characteristics of each pulse can also be specified in PulseDF.

Examples

>>> import numpy as np
>>> import pandas as pd
>>> from landlab import NetworkModelGrid

Create the network model grid. Pulses are added to the links of the network model grid.

>>> y_of_node = (0, 100, 200, 200, 300, 400, 400, 125)
>>> x_of_node = (0, 0, 100, -50, -100, 50, -150, -100)
>>> nodes_at_link = ((1, 0), (2, 1), (1, 7), (3, 1), (3, 4), (4, 5), (4, 6))
>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)
>>> grid.at_link["channel_width"] = np.full(grid.number_of_links, 1.0)  # m
>>> grid.at_link["channel_slope"] = np.full(grid.number_of_links, 0.01)  # m / m
>>> grid.at_link["reach_length"] = np.full(grid.number_of_links, 100.0)  # m

Instantiate ‘SedimentPulserEachParcel’

>>> make_pulse = SedimentPulserEachParcel(grid)

Define the PulseDF and time of the pulse

>>> PulseDF = pd.DataFrame(
...     {
...         "pulse_volume": [0.2, 1, 1.1, 0.5],
...         "link_#": [1, 3, 5, 2],
...         "normalized_downstream_distance": [0.8, 0.7, 0.5, 0.2],
...     }
... )
>>> time = 7

Run the instance

>>> parcels = make_pulse(time, PulseDF)

This should yield a UserWarning: Parcels not provided, created a new DataRecord

check element_id of each parcel

>>> print(parcels.dataset["element_id"].values)
[[1]
[3]
[3]
[5]
[5]
[5]
[2]]

instantiate SedimentPulserEachParcel

Parameters:

  • grid (ModelGrid) – landlab ModelGrid to place sediment parcels on.

  • parcels (landlab DataRecord, optional) – Tracks parcel location and attributes

  • D50 (float, optional) – median grain size [m]

  • D84_D50 (float, optional) – ratio of 84th percentile grain size to the median grain size

  • rho_sediment (float, optional) – Sediment grain density [kg/m^3].

  • parcel_volume (float, optional) – parcel volume [m^3]

  • abrasion_rate (float, optional) – volumetric abrasion exponent [1/m]

__call__(time, PulseDF=None)[source]#

specify the location and attributes of each pulse of material added to a Network Model Grid DataRecord

Parameters:

  • time (integer or datetime64 value equal to nst.time) – time that the pulse is triggered in the network sediment transporter

  • PulseDF (pandas dataframe) – each row contains information on the deposition location and volume of a single pulse of sediment. The pulse is divided into ‘n’ number of parcels, where ‘n’ equals the np.ceil(pulse volume / parcel volume) For details on the format of the DataFrame, see the docstring for function _sediment_pulse_dataframe

Returns:

a DataRecord containing all information on each individual parcel

Return type:

self._parcels

__init__(grid, parcels=None, D50=0.05, D84_D50=2.1, rho_sediment=2650.0, parcel_volume=0.5, abrasion_rate=0.0, rng=None)[source]#

instantiate SedimentPulserEachParcel

Parameters:

  • grid (ModelGrid) – landlab ModelGrid to place sediment parcels on.

  • parcels (landlab DataRecord, optional) – Tracks parcel location and attributes

  • D50 (float, optional) – median grain size [m]

  • D84_D50 (float, optional) – ratio of 84th percentile grain size to the median grain size

  • rho_sediment (float, optional) – Sediment grain density [kg/m^3].

  • parcel_volume (float, optional) – parcel volume [m^3]

  • abrasion_rate (float, optional) – volumetric abrasion exponent [1/m]