landlab.components.concentration_tracker.concentration_tracker_for_space¶

Created on Fri Jun 16 15:06:50 2023

@author: LaurentRoberge

class ConcentrationTrackerForSpace[source]¶

Bases: Component

This component tracks the concentration of any user-defined property of sediment using a mass balance approach in which concentration \(C_s\) is calculated as:

\[∂C_sH/∂t = C_s_w*D_s_w + C_s*E_s\]

where \(H\) is sediment depth, \(C_s_w\) is concentration in sediment suspended in the water column, \(D_s_w\) is volumetric depositional flux of sediment from the water column per unit bed area, and \(E_s\) is volumetric erosional flux of sediment from the bed per unit bed area.

Note

This component requires the “sediment__outflux”, “bedrock__erosion_flux” “sediment__erosion_flux”, and “sediment__deposition_flux” fields calculated by the SpaceLargeScaleEroder component. This component does not use the typical run_one_step(dt) method. Instead, a start_tracking() method is implemented immediately before every SpaceLargeScaleEroder step and a stop_tracking(dt) method immediately after every SpaceLargeScaleEroder step. See the docstring examples below.

The required inputs “phi”, “fraction_fines”, and “settling_velocity” must have the same value as those used for the instance of SpaceLargeScaleEroder.

Examples

A 1-D stream channel:

>>> import numpy as np
>>> from landlab import NodeStatus, RasterModelGrid
>>> from landlab.components import PriorityFloodFlowRouter
>>> from landlab.components import SpaceLargeScaleEroder
>>> from landlab.components import ConcentrationTrackerForSpace

>>> mg = RasterModelGrid((3, 5), xy_spacing=10.0)

>>> mg.set_status_at_node_on_edges(
...     right=NodeStatus.CLOSED,
...     top=NodeStatus.CLOSED,
...     left=NodeStatus.CLOSED,
...     bottom=NodeStatus.CLOSED,
... )
>>> mg.status_at_node[5] = mg.BC_NODE_IS_FIXED_VALUE
>>> mg.status_at_node.reshape(mg.shape)
array([[4, 4, 4, 4, 4],
       [1, 0, 0, 0, 4],
       [4, 4, 4, 4, 4]], dtype=uint8)

>>> mg.at_node["sediment_property__concentration"] = [
...     [0.0, 0.0, 0.0, 0.0, 0.0],
...     [0.0, 0.0, 0.0, 1.0, 0.0],
...     [0.0, 0.0, 0.0, 0.0, 0.0],
... ]
>>> mg.at_node["soil__depth"] = [
...     [1.0, 1.0, 1.0, 1.0, 1.0],
...     [1.0, 1.0, 1.0, 1.0, 1.0],
...     [1.0, 1.0, 1.0, 1.0, 1.0],
... ]
>>> mg.at_node["bedrock__elevation"] = mg.node_x / 100
>>> mg.at_node["topographic__elevation"] = (
...     mg.at_node["soil__depth"] + mg.at_node["bedrock__elevation"]
... )

>>> fr = PriorityFloodFlowRouter(mg)
>>> fr.run_one_step()
>>> sp = SpaceLargeScaleEroder(mg, phi=0, F_f=0, v_s=1)
>>> ct = ConcentrationTrackerForSpace(
...     mg,
...     phi=0,
...     fraction_fines=0,
...     settling_velocity=1,
... )

>>> for i in range(40):
...     fr.run_one_step()
...     ct.start_tracking()
...     sp.run_one_step(10.0)
...     ct.stop_tracking(10.0)
...

Erosion has lowered the topography and reduced channel bed sediment depth. >>> np.allclose( … mg.at_node[“topographic__elevation”][mg.core_nodes], … np.array([1.00292211, 1.00902572, 1.0258774]), … ) True >>> np.allclose( … mg.at_node[“soil__depth”][mg.core_nodes], … np.array([0.90294696, 0.80909071, 0.72601329]), … ) True

Some high-concentration sediment has been transported from upstream to be deposited on the channel bed further downstream. >>> np.allclose( … mg.at_node[“sediment_property__concentration”][mg.core_nodes], … np.array([0.0496547, 0.0997232, 0.9999151]), … ) True

Now, a 2-D landscape with stream channels. All boundaries are closed except for Node 0, which is the outlet of the catchment.

>>> mg = RasterModelGrid((6, 6), xy_spacing=10.0)

>>> mg.set_status_at_node_on_edges(
...     right=NodeStatus.CLOSED,
...     top=NodeStatus.CLOSED,
...     left=NodeStatus.CLOSED,
...     bottom=NodeStatus.CLOSED,
... )
>>> mg.status_at_node[0] = mg.BC_NODE_IS_FIXED_VALUE
>>> mg.status_at_node.reshape(mg.shape)
array([[4, 4, 4, 4, 4, 4],
       [4, 0, 0, 0, 0, 4],
       [4, 0, 0, 0, 0, 4],
       [4, 0, 0, 0, 0, 4],
       [4, 0, 0, 0, 0, 4],
       [1, 4, 4, 4, 4, 4]], dtype=uint8)

>>> mg.at_node["sediment_property__concentration"] = [
...     [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...     [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...     [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...     [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...     [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...     [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
... ]
>>> mg.at_node["soil__depth"] = [
...     [1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
...     [1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
...     [1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
...     [1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
...     [1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
...     [0.0, 1.0, 1.0, 1.0, 1.0, 1.0],
... ]

# Add noise to the bedrock to create some topographic structure. >>> np.random.seed(5) >>> mg.add_zeros(“bedrock__elevation”, at=”node”) >>> mg.at_node[“bedrock__elevation”] += np.random.rand(mg.number_of_nodes) / 100 >>> mg.at_node[“bedrock__elevation”][0] = 0

>>> mg.at_node["topographic__elevation"] = (
...     mg.at_node["soil__depth"] + mg.at_node["bedrock__elevation"]
... )

# Instantiate components. >>> fr = PriorityFloodFlowRouter(mg) >>> fr.run_one_step() >>> sp = SpaceLargeScaleEroder(mg, phi=0, F_f=0, v_s=1) >>> ct = ConcentrationTrackerForSpace( … mg, … phi=0, … fraction_fines=0, … settling_velocity=1, … )

# Run SPACE for 1,000 years to generate a fluvial network. >>> for i in range(1000): … mg.at_node[“bedrock__elevation”][mg.core_nodes] += 0.001 … mg.at_node[“topographic__elevation”][:] = ( … mg.at_node[“soil__depth”] + mg.at_node[“bedrock__elevation”] … ) … fr.run_one_step() … sp.run_one_step(1.0) …

# Set high concentration at a headwater node to trace sediment downstream. >>> mg.at_node[“sediment_property__concentration”][22] += 1

>>> for i in range(100):
...     mg.at_node["bedrock__elevation"][mg.core_nodes] += 0.001
...     mg.at_node["topographic__elevation"][:] = (
...         mg.at_node["soil__depth"] + mg.at_node["bedrock__elevation"]
...     )
...     fr.run_one_step()
...     ct.start_tracking()
...     sp.run_one_step(1.0)
...     ct.stop_tracking(1.0)
...

Some high-concentration sediment has been transported from the headwaters to be deposited on the channel bed further downstream. We can trace this sediment and see where the channel lies within the landscape. >>> np.allclose( … mg.at_node[“sediment_property__concentration”][mg.core_nodes], … np.array( … [ … [0.0288311, 0.0447778, 0.0, 0.0], … [0.0, 0.0, 0.0598574, 0.0], … [0.0, 0.0, 0.0, 0.9548471], … [0.0, 0.0, 0.0, 0.0], … ] … ).flatten(), … ) True

References

Required Software Citation(s) Specific to this Component

CITATION

Parameters:

grid (ModelGrid) – Landlab ModelGrid object
phi (float) – Sediment porosity, [-]
fraction_fines (float) – Fraction of permanently suspendable fines in bedrock, [-].
settling_velocity (float) – Net effective settling velocity for chosen grain size metric, [L/T]
concentration_initial (positive float, array, or field name (optional)) – Initial concentration in soil/sediment, [-/L^3]
concentration_in_bedrock (positive float, array, or field name (optional)) – Concentration in bedrock, [-/L^3]

property C_br¶: Concentration in bedrock (kg/m^3).

property C_init¶: Initial concentration in soil/sediment (kg/m^3).

__init__(grid, phi=None, fraction_fines=None, settling_velocity=None, concentration_initial=0, concentration_in_bedrock=0)[source]¶

Parameters:

grid (ModelGrid) – Landlab ModelGrid object
phi (float) – Sediment porosity, [-]
fraction_fines (float) – Fraction of permanently suspendable fines in bedrock, [-].
settling_velocity (float) – Net effective settling velocity for chosen grain size metric, [L/T]
concentration_initial (positive float, array, or field name (optional)) – Initial concentration in soil/sediment, [-/L^3]
concentration_in_bedrock (positive float, array, or field name (optional)) – Concentration in bedrock, [-/L^3]

static __new__(cls, *args, **kwds)¶

cite_as = '\n CITATION\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)'), ('bedrock_property__concentration', 'Mass concentration of property per unit volume of bedrock'), ('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__outflux', 'Sediment flux (volume per unit time of sediment leaving each node)'), ('sediment_property__concentration', 'Mass concentration of property per unit volume of sediment'), ('soil__depth', 'Depth of soil or weathered bedrock'), ('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__erosion_flux', 'sediment__deposition_flux', 'sediment__erosion_flux', 'sediment__outflux', 'soil__depth', 'topographic__elevation')¶

name = 'ConcentrationTrackerForSpace'¶

optional_var_names = ()¶

output_var_names = ('bedrock_property__concentration', 'sediment_property__concentration')¶

run_one_step()[source]¶: run_one_step is not implemented for this component.

property shape¶: Return the grid shape attached to the component, if defined.

start_tracking()[source]¶: Stores values necessary for calculating changes in concentration. This method must be called prior to running the sediment flux component that changes physical properties of bedrock, soil, and/or topography.

stop_tracking(dt)[source]¶

Calculate changes in concentration that have occurred in the timestep since tracking was started. This method must be called after running the sediment flux component that changes physical properties of bedrock, soil, and/or topography.

Parameters:: dt (float (time)) – The imposed timestep.

unit_agnostic = True¶

units = (('bedrock__erosion_flux', 'm/yr'), ('bedrock_property__concentration', '-/m^3'), ('sediment__deposition_flux', 'm/yr'), ('sediment__erosion_flux', 'm/yr'), ('sediment__outflux', 'm^3/yr'), ('sediment_property__concentration', '-/m^3'), ('soil__depth', '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__erosion_flux', 'node'), ('bedrock_property__concentration', 'node'), ('sediment__deposition_flux', 'node'), ('sediment__erosion_flux', 'node'), ('sediment__outflux', 'node'), ('sediment_property__concentration', 'node'), ('soil__depth', 'node'), ('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