landlab.components.overland_flow.linear_diffusion_overland_flow_router¶

Landlab component for overland flow using the linearized diffusion-wave approximation.

Created on Fri May 27 14:26:13 2016

@author: gtucker

class LinearDiffusionOverlandFlowRouter[source]¶

Bases: Component

Calculate water flow over topography.

Landlab component that implements a two-dimensional, linearized diffusion-wave model. The diffusion-wave approximation is a simplification of the shallow-water equations that omits the momentum terms. The flow velocity is calculated using the local water-surface slope as an approximation of the energy slope. With this linearized form, flow velocity is calculated using a linearized Manning equation, with the water-surface slope being used as the slope factor. There are two governing equations, one that represents conservation of water mass:

..math:

\frac{\partial H}{\partial t} = (P - I) - \nabla\cdot\mathbf{q}

where \(H(x,y,t)\) is local water depth, \(t\) is time, \(P\) is precipitation rate, \(I\) is infiltration rate, and \(\mathbf{q}\) is specific water discharge, which equals depth times depth-averaged velocity. The other governing equation represents specific discharge as a function of gravity, pressure, and friction:

..math:

\mathbf{q} = \frac{H^{4/3}}{n^2 U_c} \nabla w

where \(n\) is the friction factor (“Manning’s n”), \(U_c\) is a characteristic flow velocity, and \(w\) is water-surface height, which is the sum of topographic elevation plus water depth.

Infiltration rate should decline smoothly to zero as surface water depth approaches zero. To ensure this, infiltration rate is calculated as

..math:

I = I_c \left( 1 - e^{-H / H_i} ) \right)

where \(H_i\) is a characteristic water depth. The concept here is that when \(H \le H_i\), small spatial variations in water depth will leave parts of the ground un-ponded and therefore not subject to any infiltration. Mathematically, \(I \approx 0.95 I_c\) when \(H = 3H_i\).

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 3))
>>> _ = grid.add_zeros("topographic__elevation", at="node")
>>> olf = LinearDiffusionOverlandFlowRouter(grid, roughness=0.1)
>>> round(olf.vel_coef)
100
>>> olf.rain_rate
1e-05
>>> olf.rain_rate = 1.0e-4
>>> olf.run_one_step(dt=10.0)
>>> grid.at_node["surface_water__depth"][4]
0.001

References

Required Software Citation(s) Specific to this Component

None Listed

Additional References

None Listed

Initialize the LinearDiffusionOverlandFlowRouter.

Parameters:

grid (ModelGrid) – Landlab ModelGrid object
roughness (float, defaults to 0.01) – Manning roughness coefficient, s/m^1/3
rain_rate (float, optional (defaults to 36 mm/hr)) – Rainfall rate, m/s
infilt_depth_scale (float, defaults to 0.001) – Depth scale for water infiltration, m
infilt_rate (float, optional (defaults to 0)) – Maximum rate of infiltration, m/s
velocity_scale (float, defaults to 1) – Characteristic flow velocity, m/s
cfl_factor (float, optional (defaults to 0.2)) – Time-step control factor: fraction of maximum estimated time-step that is actually used (must be <=1)

__init__(grid, roughness=0.01, rain_rate=1e-05, infilt_rate=0.0, infilt_depth_scale=0.001, velocity_scale=1.0, cfl_factor=0.2)[source]¶

Initialize the LinearDiffusionOverlandFlowRouter.

Parameters:

grid (ModelGrid) – Landlab ModelGrid object
roughness (float, defaults to 0.01) – Manning roughness coefficient, s/m^1/3
rain_rate (float, optional (defaults to 36 mm/hr)) – Rainfall rate, m/s
infilt_depth_scale (float, defaults to 0.001) – Depth scale for water infiltration, m
infilt_rate (float, optional (defaults to 0)) – Maximum rate of infiltration, m/s
velocity_scale (float, defaults to 1) – Characteristic flow velocity, m/s
cfl_factor (float, optional (defaults to 0.2)) – Time-step control factor: fraction of maximum estimated time-step that is actually used (must be <=1)

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

definitions = (('surface_water__depth', 'Depth of water on the surface'), ('surface_water__depth_at_link', 'Depth of water on the surface at grid links'), ('topographic__elevation', 'Land surface topographic elevation'), ('water__specific_discharge', 'flow discharge component in the direction of the link'), ('water__velocity', 'flow velocity component in the direction of the link'), ('water_surface__elevation', 'Elevation of the water surface.'), ('water_surface__gradient', 'Downstream gradient of the water surface.'))¶

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 = ('topographic__elevation',)¶

name = 'LinearDiffusionOverlandFlowRouter'¶

optional_var_names = ()¶

output_var_names = ('surface_water__depth', 'surface_water__depth_at_link', 'water__specific_discharge', 'water__velocity', 'water_surface__elevation', 'water_surface__gradient')¶

property rain_rate¶: Rainfall rate

run_one_step(dt)[source]¶

Calculate water flow for a time period dt.

Default units for dt are seconds. We use a time-step subdivision algorithm that ensures step size is always below CFL limit.

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

unit_agnostic = True¶

units = (('surface_water__depth', 'm'), ('surface_water__depth_at_link', 'm'), ('topographic__elevation', 'm'), ('water__specific_discharge', 'm2/s'), ('water__velocity', 'm/s'), ('water_surface__elevation', 'm'), ('water_surface__gradient', 'm/s'))¶

update_for_one_iteration(iter_dt)[source]¶: Update state variables for one iteration of duration iter_dt.

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 = (('surface_water__depth', 'node'), ('surface_water__depth_at_link', 'link'), ('topographic__elevation', 'node'), ('water__specific_discharge', 'link'), ('water__velocity', 'link'), ('water_surface__elevation', 'node'), ('water_surface__gradient', 'link'))¶

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

property vel_coef¶

Velocity coefficient.

(1/(roughness^2 x velocity_scale)