Landlab component that simulates overland flow.
This component simulates overland flow using the 2D numerical model of shallowwater flow over topography using the de Almeida et al., 2012 algorithm for storagecell inundation modeling.
Code author: Jordan Adams
>>> 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'] = np.array([
... 0., 0., 0., 0., 0.,
... 1., 1., 1., 1., 1.,
... 2., 2., 2., 2., 2.,
... 3., 3., 3., 3., 3.])
>>> grid.at_node['surface_water__depth'] = np.array([
... 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.00000000e05, 1.00000000e05, 1.00000000e05,
1.00000000e05, 1.00000000e05, 1.00000000e05,
1.00000000e05, 1.00000000e05, 1.00000000e05,
1.00000000e05, 1.00000000e05, 2.00100000e02,
2.00100000e02, 2.00100000e02, 1.00000000e05,
1.00010000e01, 1.00010000e01, 1.00010000e01,
1.00010000e01, 1.00010000e01])
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.)
True
>>> np.all(q[grid.vertical_links] <= 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. ])
OverlandFlow
(*args, **kwds)[source]¶Bases: landlab.core.model_component.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.
Parameters:  grid : RasterModelGrid
h_init : float, optional
alpha : float, optional
mannings_n : float, optional
g : float, optional
theta : float, optional
rainfall_intensity : float, optional
The primary method of this class is :func:`run_one_step`. Construction::


calc_time_step
()[source]¶Calculate time step.
Adaptive time stepper from Bates et al., 2010 and de Almeida et al., 2012
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)
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.
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.
find_active_neighbors_for_fixed_links
(grid)[source]¶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


Returns:  ndarray of int, shape (*, )

Examples
>>> from landlab.grid.structured_quad.links import neighbors_at_link
>>> from landlab import RasterModelGrid
>>> from landlab.components.overland_flow.generate_overland_flow_deAlmeida import find_active_neighbors_for_fixed_links
>>> from landlab import RasterModelGrid, FIXED_GRADIENT_BOUNDARY
>>> grid = RasterModelGrid((4, 5))
>>> grid.status_at_node[:5] = FIXED_GRADIENT_BOUNDARY
>>> grid.status_at_node[::5] = FIXED_GRADIENT_BOUNDARY
>>> grid.status_at_node
array([2, 2, 2, 2, 2,
2, 0, 0, 0, 1,
2, 0, 0, 0, 1,
2, 1, 1, 1, 1], dtype=int8)
>>> 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.set_fixed_link_boundaries_at_grid_edges(True, True, True, True)
>>> find_active_neighbors_for_fixed_links(rmg)
array([20, 21, 22, 23, 24, 14, 17, 27, 30, 20, 21, 22, 23, 24])
generate_overland_flow.py
This component simulates overland flow using the 2D numerical model of shallowwater flow over topography using the Bates et al. (2010) algorithm for storagecell inundation modeling.
Written by Jordan Adams, based on code written by Greg Tucker.
Last updated: April 21, 2016
OverlandFlowBates
(grid, h_init=1e05, alpha=0.7, mannings_n=0.03, g=9.81, rainfall_intensity=0.0, **kwds)[source]¶Bases: landlab.core.model_component.Component
Simulate overland flow using Bates et al. (2010).
Landlab component that simulates overland flow using the Bates et al., (2010) 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.
Parameters:  grid : RasterGridModel
input_file : str
h_init : float, optional
g : float, optional
alpha : float, optional
rho : integer, optional
ten_thirds : float, optional


Examples
>>> DEM_name = 'DEM_name.asc'
>>> (rg, z) = read_esri_ascii(DEM_name)
>>> of = OverlandFlowBates(rg)
overland_flow
(dt=None, **kwds)[source]¶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.
Parameters:  grid : RasterModelGrid
dt : float, optional


KinematicWaveRengers
(*args, **kwds)[source]¶Bases: landlab.core.model_component.Component
A midcomplexity kinematic wave flood model, after Rengers et al (2016)
This code is based on an overland flow model by Francis Rengers and colleagues, after Julien et al., 1995. It uses an explicit facecentered solution to a depthvarying Manning’s equation, broadly following, e.g., Mugler et al., 2011. It was implemented in Landlab by DEJH, March ‘16. Please cite Rengers et al., 2016, Model Predictions of Water Runoff in Steep Catchments after Wildfire, WRR.
Note: You will not have a good day if you have pits present in your topo
before routing flow with this component. Fill pits before instantiating
the component (or call update_topographic_params()
once you have
filled after instantiation).
Note this module assumes that the topography DOES NOT change during the
run. If it does, call update_topographic_params()
to update the
component to the new topo.
Boundary condition control can be... interesting with this component. Be sure to close boundaries you do not wish water to leave  or enter!  through. To allow free water discharge from the grid edge it is recommended to use fixed gradient boundary conditions at the open edges. The component will then set the fixed gradient as equal to the underlying topographic gradient throughout the run.
It is also possible to fix the water depth at the open edge, but this is not really recommended.
Construction:
KinematicWaveRengers(grid, mannings_n=0.03, critical_flow_depth=0.003,
mannings_epsilon=0.33333333, dt_max=0.3,
max_courant=0.2, min_surface_water_depth=1.e8)
Parameters:  grid : RasterModelGrid
mannings_n : float
critical_flow_depth : float (m)
mannings_epsilon : float
dt_max : float or None (s)
max_courant : float
min_surface_water_depth : float (m)


Examples
>>> from landlab import RasterModelGrid
>>> from landlab import CLOSED_BOUNDARY, FIXED_GRADIENT_BOUNDARY
>>> mg = RasterModelGrid((5, 10), spacing=10.)
>>> mg.status_at_node[mg.nodes_at_left_edge] = FIXED_GRADIENT_BOUNDARY
>>> mg.status_at_node[mg.nodes_at_top_edge] = CLOSED_BOUNDARY
>>> mg.status_at_node[mg.nodes_at_bottom_edge] = CLOSED_BOUNDARY
>>> mg.status_at_node[mg.nodes_at_right_edge] = CLOSED_BOUNDARY
>>> _ = mg.add_field('node', 'topographic__elevation', 0.05*mg.node_x)
>>> _ = mg.add_empty('node', 'surface_water__depth')
>>> mg.at_node['surface_water__depth'].fill(1.e8)
>>> dt = 60. # 1 min intervals
>>> rain_intensities = (1.e5, 1.e5, 1.e5, 1.e5, 1.e5)
>>> kw = KinematicWaveRengers(mg)
>>> for i in rain_intensities:
... kw.run_one_step(dt, rainfall_intensity=i)
>>> mg.at_node['surface_water__depth']
array([ 1.00000000e08, 1.00000000e08, 1.00000000e08,
1.00000000e08, 1.00000000e08, 1.00000000e08,
1.00000000e08, 1.00000000e08, 1.00000000e08,
1.00000000e08, 2.95578314e03, 2.95578314e03,
2.90945761e03, 2.82912876e03, 2.70127141e03,
2.51202011e03, 2.24617193e03, 1.88032853e03,
1.35451064e03, 1.00000000e08, 2.95578314e03,
2.95578314e03, 2.90945761e03, 2.82912876e03,
2.70127141e03, 2.51202011e03, 2.24617193e03,
1.88032853e03, 1.35451064e03, 1.00000000e08,
2.95578314e03, 2.95578314e03, 2.90945761e03,
2.82912876e03, 2.70127141e03, 2.51202011e03,
2.24617193e03, 1.88032853e03, 1.35451064e03,
1.00000000e08, 1.00000000e08, 1.00000000e08,
1.00000000e08, 1.00000000e08, 1.00000000e08,
1.00000000e08, 1.00000000e08, 1.00000000e08,
1.00000000e08, 1.00000000e08])
calc_grads_and_timesteps
(update_topography, track_min_depth)[source]¶Perform the first part of the calculation for the main run, mainly velocities and fluxes. The main objective of this part of the calculation is to derive the stable timestep for the run.
Parameters:  update_topography : bool
track_min_depth : bool


Returns:  internal_dt : float

internal_timestep
¶Return the internal timestep last used by the kinematic wave component.
run_one_step
(dt, rainfall_intensity=1e05, update_topography=False, track_min_depth=False)[source]¶Update fields with current hydrologic conditions.
Parameters:  rain_intensity : float or array (m/s)
update_topography : bool
track_min_depth : bool


update_topographic_params
()[source]¶If the topo changes during the run, change the held params used by
run_one_step()
.
water_balance
¶Return a list of the fractional gain/loss of water mass during the run, if it was tracked using the track_min_depth flag.