landlab.components.dimensionless_discharge.dimensionless_discharge¶
Calculate dimensionless discharge of stream sections based on Tang et al. (2019)
- class DimensionlessDischarge[source]¶
Bases:
Component- Component that calculates dimensionless discharge of stream
segments.
The dimensionless discharge model calculates the unitless discharge value of streams and can be used to help determine locations of debris flows. It uses an equation from Tang et al. (2019) to calculate the dimensionless discharge as well as the threshold for whether a debris flow will occur for a specified location.
\[ \begin{align}\begin{aligned} q* = \frac{q}{\sqrt{\frac{\rho_s-\rho}{\rho}*g*D_{50}^3}}\\where :math:`q*` is the dimensionless discharge value for a stream segment, :math:`q` is flux in a stream segment, :math:`\rho_s` is soil density, :math:`\rho` is water density, :math:`g` is the gravitational constant, and :math:`D_50` is the average sediment partical size in the stream segment area.\\Constants C and N are coefficients used in the slope-dependent equation\\.. math::\\ q*_{thresold} = \frac{C}{(tan(\theta))^N}\\to determine whether the dimensionless discharge calculated exceeds thresholds for a sediment-laden (Upper Limit) or water-producing only (Lower Limit) debris flow. C and N are empirically-derived by comparing dimensionless discharge estimates against previous debris flow events. The values will vary based on local geology and soil type. In southern California values of C=12 and N=0.85 (upper limits, Tang et al, 2019) and C=4.29, N=0.78 (lower limits, Tang et al, 2019) have been used, while values of C=0.195 and N=1.27 have been in used in the Italian Dolomites (Gregoretti and Fontana, 2008). Default values are C=12 and N=0.85.\\Examples -------- >>> from landlab.components import DimensionlessDischarge >>> from landlab import RasterModelGrid >>> import random >>> watershed_grid = RasterModelGrid((3, 3)) >>> surface_water__unit_discharge = watershed_grid.add_ones( ... "surface_water__unit_discharge", at="node" ... ) >>> d50 = watershed_grid.add_ones( ... "channel_bottom_sediment_grain__d50_diameter", at="node" ... ) >>> watershed_grid.at_node["topographic__elevation"] = np.array( ... [[1.1, 2, 3, 4, 2, 3, 4, 5, 3]] ... ) >>> dd = DimensionlessDischarge(watershed_grid, gravity=9.8) >>> dd.run_one_step() >>> watershed_grid.at_node["dimensionless_discharge"] array([0.55372743, 0.55372743, 0.55372743, 0.55372743, 0.55372743, 0.55372743, 0.55372743, 0.55372743, 0.55372743])\\References ---------- Tang, H., McGuire, L. A., Rengers, F. K., Kean, J. W., Staley, D. M., & Smith, J. B. (2019). Developing and Testing Physically Based Triggering Thresholds for Runoff-Generated Debris Flows. Geophysical Research Letters, 46(15), 8830–8839. https://doi.org/10.1029/2019GL083623\end{aligned}\end{align} \]Initialize the DimensionlessDischarge.
- Parameters:
soil_density (float, field name, or array, optional) – density of soil (kg/m^3) (defaults to 1330)
water_density (float, optional) – density of water (kg/m^3) (defaults to 997.9)
C (float, optional) – Numerator of the debris flow threshold equation; Empirically derived constant (See Tang et al. 2019). (defaults to 12.0)
N (float, optional) – Exponent for slope in the denominator of the debris flow threshold equation; Empirically derived constant (See Tang et al. 2019). (defaults to 0.85)
gravity (float, optional) – (defaults to scipy’s standard acceleration of gravity)
channel_bottom_sediment_grain__d50_diameter (float, field_name, or array) – defaults to the field name “channel_bottom_sediment_grain__d50_diameter”
- __init__(grid, soil_density=1330, water_density=997.9, C=12.0, N=0.85, gravity=scipy.constants.g, channel_bottom_sediment_grain__d50_diameter='channel_bottom_sediment_grain__d50_diameter')[source]¶
Initialize the DimensionlessDischarge.
- Parameters:
soil_density (float, field name, or array, optional) – density of soil (kg/m^3) (defaults to 1330)
water_density (float, optional) – density of water (kg/m^3) (defaults to 997.9)
C (float, optional) – Numerator of the debris flow threshold equation; Empirically derived constant (See Tang et al. 2019). (defaults to 12.0)
N (float, optional) – Exponent for slope in the denominator of the debris flow threshold equation; Empirically derived constant (See Tang et al. 2019). (defaults to 0.85)
gravity (float, optional) – (defaults to scipy’s standard acceleration of gravity)
channel_bottom_sediment_grain__d50_diameter (float, field_name, or array) – defaults to the field name “channel_bottom_sediment_grain__d50_diameter”
- 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_timeattribute is incremented. Otherwise it is set to None.- Return type:
current_time
- definitions = (('channel_bottom_sediment_grain__d50_diameter', 'soil grain size average in stream segment'), ('dimensionless_discharge', 'Dimensionless discharge value for a stream segment.'), ('dimensionless_discharge_above_threshold', 'True if dimensionless discharge value is above threshold value, false otherwise.'), ('dimensionless_discharge_threshold', 'Dimensionless discharge threshold for each stream segment.'), ('surface_water__unit_discharge', 'Volumetric discharge of surface water per unit width'), ('topographic__elevation', 'Land surface topographic elevation'))¶
- classmethod from_path(grid, path)¶
Create a component from an input file.
- 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 = ('surface_water__unit_discharge', 'topographic__elevation')¶
- name = 'DimensionlessDischargeModel'¶
- optional_var_names = ('channel_bottom_sediment_grain__d50_diameter',)¶
- output_var_names = ('dimensionless_discharge', 'dimensionless_discharge_above_threshold', 'dimensionless_discharge_threshold', 'topographic__elevation')¶
- property shape¶
Return the grid shape attached to the component, if defined.
- unit_agnostic = False¶
- units = (('channel_bottom_sediment_grain__d50_diameter', 'm'), ('dimensionless_discharge', 'none'), ('dimensionless_discharge_above_threshold', 'none'), ('dimensionless_discharge_threshold', 'none'), ('surface_water__unit_discharge', 'm**2/s'), ('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.
- var_mapping = (('channel_bottom_sediment_grain__d50_diameter', 'node'), ('dimensionless_discharge', 'node'), ('dimensionless_discharge_above_threshold', 'node'), ('dimensionless_discharge_threshold', 'node'), ('surface_water__unit_discharge', 'node'), ('topographic__elevation', 'node'))¶