landlab.components.overland_flow.generate_overland_flow_deAlmeida

Landlab component that simulates overland flow.

This component simulates overland flow using the 2-D numerical model of shallow-water flow over topography using the de Almeida et al., 2012 algorithm for storage-cell inundation modeling.

Code author: Jordan Adams

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> from landlab.components.overland_flow import OverlandFlow

Create a grid on which to calculate overland flow.

>>> grid = RasterModelGrid((4, 5))

The grid will need some data to provide the overland flow component. To check the names of the fields that provide input to the overland flow component use the input_var_names class property.

>>> OverlandFlow.input_var_names
('surface_water__depth', 'topographic__elevation')

Create fields of data for each of these input variables.

>>> grid.at_node["topographic__elevation"] = [
...     [0.0, 0.0, 0.0, 0.0, 0.0],
...     [1.0, 1.0, 1.0, 1.0, 1.0],
...     [2.0, 2.0, 2.0, 2.0, 2.0],
...     [3.0, 3.0, 3.0, 3.0, 3.0],
... ]
>>> grid.at_node["surface_water__depth"] = [
...     [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.1, 0.1, 0.1, 0.1, 0.1],
... ]

Instantiate the OverlandFlow component to work on this grid, and run it.

>>> of = OverlandFlow(grid, steep_slopes=True)
>>> of.run_one_step()

After calculating the overland flow, new fields have been added to the grid. Use the output_var_names property to see the names of the fields that have been changed.

>>> of.output_var_names
('surface_water__depth', 'surface_water__discharge', 'water_surface__gradient')

The surface_water__depth field is defined at nodes.

>>> of.var_loc("surface_water__depth")
'node'
>>> grid.at_node["surface_water__depth"]
array([1.0000e-05, 1.0000e-05, 1.0000e-05, 1.0000e-05, 1.0000e-05,
       1.0000e-05, 1.0000e-05, 1.0000e-05, 1.0000e-05, 1.0000e-05,
       1.0000e-05, 2.0010e-02, 2.0010e-02, 2.0010e-02, 1.0000e-05,
       1.0001e-01, 1.0001e-01, 1.0001e-01, 1.0001e-01, 1.0001e-01])

The surface_water__discharge field is defined at links. Because our initial topography was a dipping plane, there is no water discharge in the horizontal direction, only toward the bottom of the grid.

>>> of.var_loc("surface_water__discharge")
'link'
>>> q = grid.at_link["surface_water__discharge"]
>>> np.all(q[grid.horizontal_links] == 0.0)
True
>>> np.all(q[grid.vertical_links] <= 0.0)
True

The water_surface__gradient is also defined at links.

>>> of.var_loc("water_surface__gradient")
'link'
>>> grid.at_link["water_surface__gradient"]
array([0. , 0. , 0. , 0. ,
       0. , 1. , 1. , 1. , 0. ,
       0. , 0. , 0. , 0. ,
       0. , 1. , 1. , 1. , 0. ,
       0. , 0. , 0. , 0. ,
       0. , 1.1, 1.1, 1.1, 0. ,
       0. , 0. , 0. , 0. ])
class OverlandFlow[source]

Bases: Component

Simulate overland flow using de Almeida approximations.

Landlab component that simulates overland flow using the de Almeida et al., 2012 approximations of the 1D shallow water equations to be used for 2D flood inundation modeling.

This component calculates discharge, depth and shear stress after some precipitation event across any raster grid. Default input file is named “overland_flow_input.txt’ and is contained in the landlab.components.overland_flow folder.

The primary method of this class is run_one_step.

References

Required Software Citation(s) Specific to this Component

Adams, J., Gasparini, N., Hobley, D., Tucker, G., Hutton, E., Nudurupati, S., Istanbulluoglu, E. (2017). The Landlab v1. 0 OverlandFlow component: a Python tool for computing shallow-water flow across watersheds. Geoscientific Model Development 10(4), 1645. https://dx.doi.org/10.5194/gmd-10-1645-2017

Additional References

de Almeida, G., Bates, P., Freer, J., Souvignet, M. (2012). Improving the stability of a simple formulation of the shallow water equations for 2-D flood modeling. Water Resources Research 48(5) https://dx.doi.org/10.1029/2011wr011570

Create an overland flow component.

Parameters:

  • grid (RasterModelGrid) – A landlab grid.

  • h_init (float, optional) – Thicknes of initial thin layer of water to prevent divide by zero errors (m).

  • alpha (float, optional) – Time step coeffcient, described in Bates et al., 2010 and de Almeida et al., 2012.

  • mannings_n (float, optional) – Manning’s roughness coefficient.

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

  • theta (float, optional) – Weighting factor from de Almeida et al., 2012.

  • rainfall_intensity (float or array of float, optional) – Rainfall intensity. Default is zero.

  • steep_slopes (bool, optional) – Modify the algorithm to handle steeper slopes at the expense of speed. If model runs become unstable, consider setting to True.

__init__(grid, default_fixed_links=False, h_init=1e-05, alpha=0.7, mannings_n=0.03, g=scipy.constants.g, theta=0.8, rainfall_intensity=0.0, steep_slopes=False)[source]

Create an overland flow component.

Parameters:

  • grid (RasterModelGrid) – A landlab grid.

  • h_init (float, optional) – Thicknes of initial thin layer of water to prevent divide by zero errors (m).

  • alpha (float, optional) – Time step coeffcient, described in Bates et al., 2010 and de Almeida et al., 2012.

  • mannings_n (float, optional) – Manning’s roughness coefficient.

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

  • theta (float, optional) – Weighting factor from de Almeida et al., 2012.

  • rainfall_intensity (float or array of float, optional) – Rainfall intensity. Default is zero.

  • steep_slopes (bool, optional) – Modify the algorithm to handle steeper slopes at the expense of speed. If model runs become unstable, consider setting to True.

static __new__(cls, *args, **kwds)
calc_time_step()[source]

Calculate time step.

Adaptive time stepper from Bates et al., 2010 and de Almeida et al., 2012

cite_as = '@article{adams2017landlab,\n        title={The Landlab v1. 0 OverlandFlow component: a Python\n            tool for computing shallow-water flow across watersheds},\n        author={Adams, Jordan M and Gasparini, Nicole M and\n            Hobley, Daniel EJ and Tucker, Gregory E and\n            Hutton, Eric WH and Nudurupati, Sai S and\n            Istanbulluoglu, Erkan},\n        journal={Geoscientific Model Development},\n        volume={10},\n        number={4},\n        pages={1645},\n        year={2017},\n        publisher={Copernicus GmbH}\n        }\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 = (('surface_water__depth', 'Depth of water on the surface'), ('surface_water__discharge', 'Volumetric discharge of surface water'), ('topographic__elevation', 'Land surface topographic elevation'), ('water_surface__gradient', 'Downstream gradient of the water surface.'))
discharge_mapper(input_discharge, convert_to_volume=False)[source]

Maps discharge value from links onto nodes.

This method takes the discharge values on links and determines the links that are flowing INTO a given node. The fluxes moving INTO a given node are summed.

This method ignores all flow moving OUT of a given node.

This takes values from the OverlandFlow component (by default) in units of [L^2/T]. If the convert_to_cms flag is raised as True, this method converts discharge to units [L^3/T] - as of Aug 2016, only operates for square RasterModelGrid instances.

The output array is of length grid.number_of_nodes and can be used with the Landlab imshow_grid plotter.

Returns a numpy array (discharge_vals)

property dt

Component timestep.

Type:

dt

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.

property h

The depth of water at each node.

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__depth', 'topographic__elevation')
name = 'OverlandFlow'
optional_var_names = ()
output_var_names = ('surface_water__depth', 'surface_water__discharge', 'water_surface__gradient')
overland_flow(dt=None)[source]

Generate overland flow across a grid.

For one time step, this generates ‘overland flow’ across a given grid by calculating discharge at each node.

Using the depth slope product, shear stress is calculated at every node.

Outputs water depth, discharge and shear stress values through time at every point in the input grid.

property rainfall_intensity

the rainfall rate [m/s]

Must be positive.

Type:

rainfall_intensity

run_one_step(dt=None)[source]

Generate overland flow across a grid.

For one time step, this generates ‘overland flow’ across a given grid by calculating discharge at each node.

Using the depth slope product, shear stress is calculated at every node.

Outputs water depth, discharge and shear stress values through time at every point in the input grid.

set_up_neighbor_arrays()[source]

Create and initialize link neighbor arrays.

Set up arrays of neighboring horizontal and vertical links that are needed for the de Almeida solution.

property shape

Return the grid shape attached to the component, if defined.

unit_agnostic = False
units = (('surface_water__depth', 'm'), ('surface_water__discharge', 'm3/s'), ('topographic__elevation', 'm'), ('water_surface__gradient', '-'))
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__discharge', 'link'), ('topographic__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

Find active link neighbors for every fixed link.

Specialized link ID function used to ID the active links that neighbor fixed links in the vertical and horizontal directions.

If the user wants to assign fixed gradients or values to the fixed links dynamically, this function identifies the nearest active_link neighbor.

Each fixed link can either have 0 or 1 active neighbor. This function finds if and where that active neighbor is and stores those IDs in an array.

Parameters:

grid (RasterModelGrid) – A landlab grid.

Returns:

Flat array of links.

Return type:

ndarray of int, shape (*, )

Examples

>>> from landlab import NodeStatus, RasterModelGrid

>>> grid = RasterModelGrid((4, 5))
>>> grid.status_at_node[:5] = NodeStatus.FIXED_GRADIENT
>>> grid.status_at_node[::5] = NodeStatus.FIXED_GRADIENT
>>> grid.status_at_node.reshape(grid.shape)
array([[2, 2, 2, 2, 2],
       [2, 0, 0, 0, 1],
       [2, 0, 0, 0, 1],
       [2, 1, 1, 1, 1]], dtype=uint8)

>>> grid.fixed_links
array([ 5,  6,  7,  9, 18])
>>> grid.active_links
array([10, 11, 12, 14, 15, 16, 19, 20, 21, 23, 24, 25])

>>> find_active_neighbors_for_fixed_links(grid)
array([14, 15, 16, 10, 19])

>>> rmg = RasterModelGrid((4, 7))

>>> rmg.at_node["topographic__elevation"] = rmg.zeros(at="node")
>>> rmg.at_link["topographic__slope"] = rmg.zeros(at="link")
>>> rmg.status_at_node[rmg.perimeter_nodes] = rmg.BC_NODE_IS_FIXED_GRADIENT
>>> find_active_neighbors_for_fixed_links(rmg)
array([20, 21, 22, 23, 24, 14, 17, 27, 30, 20, 21, 22, 23, 24])