landlab.components.overland_flow.generate_overland_flow_implicit_kinwave¶

Landlab component for overland flow using a local implicit solution to the kinematic-wave approximation.

Created on Fri May 27 14:26:13 2016

@author: gtucker

class KinwaveImplicitOverlandFlow[source]¶

Bases: Component

Calculate shallow water flow over topography.

Landlab component that implements a two-dimensional kinematic wave model. This is a form of the 2D shallow-water equations in which energy slope is assumed to equal bed slope. The solution method is locally implicit, and works as follows. At each time step, we iterate from upstream to downstream over the topography. Because we are working downstream, we can assume that we know the total water inflow to a given cell. We solve the following mass conservation equation at each cell:

\[(H^{t+1} - H^t)/\Delta t = Q_{in}/A - Q_{out}/A + R\]

where \(H\) is water depth, \(t\) indicates time step number, \(\Delta t\) is time step duration, \(Q_{in}\) is total inflow discharge, \(Q_{out}\) is total outflow discharge, \(A\) is cell area, and \(R\) is local runoff rate (precipitation minus infiltration; could be negative if runon infiltration is occurring).

The specific outflow discharge leaving a cell along one of its faces is:

\[q = (1/C_r) H^\alpha S^{1/2}\]

where \(C_r\) is a roughness coefficient (such as Manning’s n), \(\alpha\) is an exponent equal to \(5/3\) for the Manning equation and \(3/2\) for the Chezy family, and \(S\) is the downhill-positive gradient of the link that crosses this particular face. Outflow discharge is zero for links that are flat or “uphill” from the given node. Total discharge out of a cell is then the sum of (specific discharge x face width) over all outflow faces

\[Q_{out} = \sum_{i=1}^N (1/C_r) H^\alpha S_i^{1/2} W_i\]

where \(N\) is the number of outflow faces (i.e., faces where the ground slopes downhill away from the cell’s node), and \(W_i\) is the width of face \(i\).

We use the depth at the cell’s node, so this simplifies to:

\[Q_{out} = (1/C_r) H'^\alpha \sum_{i=1}^N S_i^{1/2} W_i\]

We define \(H\) in the above as a weighted sum of the “old” (time step \(t\)) and “new” (time step \(t+1\)) depth values:

\[H' = w H^{t+1} + (1-w) H^t\]

If \(w=1\), the method is fully implicit. If \(w=0\), it is a simple forward explicit method.

When we combine these equations, we have an equation that includes the unknown \(H^{t+1}\) and a bunch of terms that are known. If \(w\ne 0\), it is a nonlinear equation in \(H^{t+1}\), and must be solved iteratively. We do this using a root-finding method in the scipy.optimize library.

Examples

>>> from landlab import RasterModelGrid
>>> rg = RasterModelGrid((4, 5), xy_spacing=10.0)
>>> z = rg.add_zeros("topographic__elevation", at="node")
>>> kw = KinwaveImplicitOverlandFlow(rg)
>>> round(kw.runoff_rate * 1.0e7, 2)
2.78
>>> kw.vel_coef  # default value
100.0
>>> rg.at_node["surface_water__depth"][6:9]
array([0., 0., 0.])

References

Required Software Citation(s) Specific to this Component

None Listed

Additional References

None Listed

Initialize the KinwaveImplicitOverlandFlow.

Parameters:

grid (ModelGrid) – Landlab ModelGrid object
runoff_rate (float, optional (defaults to 1 mm/hr)) – Precipitation rate, mm/hr. The value provided is divided by 3600000.0.
roughness (float, defaults to 0.01) – Manning roughness coefficient; units depend on depth_exp.
changing_topo (boolean, optional (defaults to False)) – Flag indicating whether topography changes between time steps
depth_exp (float (defaults to 1.5)) – Exponent on water depth in velocity equation (3/2 for Darcy/Chezy, 5/3 for Manning)
weight (float (defaults to 1.0)) – Weighting on depth at new time step versus old time step (1 = all implicit; 0 = explicit)

__init__(grid, runoff_rate=1.0, roughness=0.01, changing_topo=False, depth_exp=1.5, weight=1.0)[source]¶

Initialize the KinwaveImplicitOverlandFlow.

Parameters:

grid (ModelGrid) – Landlab ModelGrid object
runoff_rate (float, optional (defaults to 1 mm/hr)) – Precipitation rate, mm/hr. The value provided is divided by 3600000.0.
roughness (float, defaults to 0.01) – Manning roughness coefficient; units depend on depth_exp.
changing_topo (boolean, optional (defaults to False)) – Flag indicating whether topography changes between time steps
depth_exp (float (defaults to 1.5)) – Exponent on water depth in velocity equation (3/2 for Darcy/Chezy, 5/3 for Manning)
weight (float (defaults to 1.0)) – Weighting on depth at new time step versus old time step (1 = all implicit; 0 = explicit)

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_inflow__discharge', 'water volume inflow rate to the cell around each node'), ('topographic__elevation', 'Land surface topographic elevation'), ('topographic__gradient', 'Gradient of the ground surface'))¶

property depth¶: The depth of water at each node.

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 = 'KinwaveImplicitOverlandFlow'¶

optional_var_names = ()¶

output_var_names = ('surface_water__depth', 'surface_water_inflow__discharge', 'topographic__gradient')¶

run_one_step(dt)[source]¶: Calculate water flow for a time period dt.

property runoff_rate¶

Runoff rate.

Parameters:: runoff_rate (float, optional (defaults to 1 mm/hr)) – Precipitation rate, mm/hr. The value provide is divided by 3600000.0.
Return type:: The current value of the runoff rate.

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

unit_agnostic = False¶

units = (('surface_water__depth', 'm'), ('surface_water_inflow__discharge', 'm3/s'), ('topographic__elevation', 'm'), ('topographic__gradient', 'm/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 = (('surface_water__depth', 'node'), ('surface_water_inflow__discharge', 'node'), ('topographic__elevation', 'node'), ('topographic__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.

water_fn(x, a, b, c, d, e)[source]¶

Evaluates the solution to the water-depth equation.

Called by scipy.newton() to find solution for \(x\) using Newton’s method.

Parameters:

x (float) – Water depth at new time step.
a (float) – “alpha” parameter (see below)
b (float) – Weighting factor on new versus old time step. \(b=1\) means purely implicit solution with all weight on \(H\) at new time step. \(b=0\) (not recommended) would mean purely explicit.
c (float) – Water depth at old time step (time step \(t\) instead of \(t+1\))
d (float) – Depth-discharge exponent; normally either 5/3 (Manning) or 3/2 (Chezy)
e (float) – Water inflow volume per unit cell area in one time step.

This equation represents the implicit solution for water depth \(H\) at the next time step. In the code below, it is formulated in a generic way. Written using more familiar terminology, the equation is:

\[H - H_0 + \alpha ( w H + (w-1) H_0)^d - \Delta t (R + Q_{in} / A)\]

\[\alpha = \frac{\Delta t \sum S^{1/2}}{C_f A}\]

where \(H\) is water depth at the given node at the new time step, \(H_0\) is water depth at the prior time step, \(w\) is a weighting factor, \(d\) is the depth-discharge exponent (2/3 or 1/2), \(\Delta t\) is time-step duration, \(R\) is local runoff rate, \(Q_{in}\) is inflow discharge, \(A\) is cell area, \(C_f\) is a dimensional roughness coefficient, and \(\sum S^{1/2}\) represents the sum of square-root-of-downhill-gradient over all outgoing (downhill) links.