landlab.components.overland_flow.kinematic_wave_rengers¶

class KinematicWaveRengers[source]¶

Bases: Component

This code is based on an overland flow model by Francis Rengers and colleagues, after Julien et al., 1995. It uses an explicit face-centered solution to a depth-varying 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.e-8)

Parameters:

grid (RasterModelGrid) – A grid.
mannings_n (float) – A value to use for Manning’s n in the Manning discharge equation.
critical_flow_depth (float (m)) – An index flow depth for the depth-varying Manning’s equation, controlling the depth at which the effective Manning’s n begins to increase.
mannings_epsilon (float) – An exponent for the depth-varying Manning’s equation, controlling the rate of increase of effective Manning’s n at small flow depths.
dt_max (float or None (s)) – The largest permitted internal timestep for the component. If the Courant criterion produces a more restrictive condition, that will be used instead.
max_courant (float) – The maximum permitted Courant number for the courant stability criterion.
min_surface_water_depth (float (m)) – A water depth below which surface water thickness may never fall, to ensure model stabilty.

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.components import KinematicWaveRengers
>>> mg = RasterModelGrid((5, 10), 10.0)
>>> mg.status_at_node[mg.nodes_at_left_edge] = mg.BC_NODE_IS_FIXED_GRADIENT
>>> mg.status_at_node[mg.nodes_at_top_edge] = mg.BC_NODE_IS_CLOSED
>>> mg.status_at_node[mg.nodes_at_bottom_edge] = mg.BC_NODE_IS_CLOSED
>>> mg.status_at_node[mg.nodes_at_right_edge] = mg.BC_NODE_IS_CLOSED
>>> _ = 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.0e-8)
>>> dt = 60.0  # 1 min intervals
>>> rain_intensities = (1.0e-5, 1.0e-5, 1.0e-5, 1.0e-5, 1.0e-5)
>>> kw = KinematicWaveRengers(mg)
>>> for i in rain_intensities:
...     kw.run_one_step(dt, rainfall_intensity=i)
...
>>> mg.at_node["surface_water__depth"]
array([1.00000000e-08, 1.00000000e-08, 1.00000000e-08,
       1.00000000e-08, 1.00000000e-08, 1.00000000e-08,
       1.00000000e-08, 1.00000000e-08, 1.00000000e-08,
       1.00000000e-08, 2.95578314e-03, 2.95578314e-03,
       2.90945761e-03, 2.82912876e-03, 2.70127141e-03,
       2.51202011e-03, 2.24617193e-03, 1.88032853e-03,
       1.35451064e-03, 1.00000000e-08, 2.95578314e-03,
       2.95578314e-03, 2.90945761e-03, 2.82912876e-03,
       2.70127141e-03, 2.51202011e-03, 2.24617193e-03,
       1.88032853e-03, 1.35451064e-03, 1.00000000e-08,
       2.95578314e-03, 2.95578314e-03, 2.90945761e-03,
       2.82912876e-03, 2.70127141e-03, 2.51202011e-03,
       2.24617193e-03, 1.88032853e-03, 1.35451064e-03,
       1.00000000e-08, 1.00000000e-08, 1.00000000e-08,
       1.00000000e-08, 1.00000000e-08, 1.00000000e-08,
       1.00000000e-08, 1.00000000e-08, 1.00000000e-08,
       1.00000000e-08, 1.00000000e-08])

Initialize the kinematic wave approximation overland flow component.

__init__(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=1e-08)[source]¶: Initialize the kinematic wave approximation overland flow component.

static __new__(cls, *args, **kwds)¶

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) – If False, the underlying surface topography is assumed unchanged since the last run.
track_min_depth (bool) – If True, the internal list _water_balance will be appended with the volumetric fractional change in mass balance during the run.

Returns:

internal_dt – The internally stable timestep that will be used on this loop.

Return type:

float

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__discharge', 'Volumetric discharge of surface water'), ('surface_water__velocity', 'Speed of water flow above the surface'), ('topographic__elevation', 'Land surface topographic elevation'))¶

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

property internal_timestep¶: Return the internal timestep last used by the kinematic wave component.

name = 'KinematicWaveRengers'¶

optional_var_names = ()¶

output_var_names = ('surface_water__depth', 'surface_water__discharge', 'surface_water__velocity')¶

run_one_step(dt, rainfall_intensity=1e-05, update_topography=False, track_min_depth=False)[source]¶

Update fields with current hydrologic conditions.

Parameters:

rain_intensity (float or array (m/s)) – The rainfall intensity across the grid (water input rate at each node).
update_topography (bool) – Set to true if the topography of the grid evolves during the run.
track_min_depth (bool) – At very low rainfall inputs, there is a possibility this component could allow creation of small amounts of water mass. Set to true to track this mass, and use the water_balance property to investigate its evolution through time.

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

unit_agnostic = False¶

units = (('surface_water__depth', 'm'), ('surface_water__discharge', 'm**3/s'), ('surface_water__velocity', 'm/s'), ('topographic__elevation', 'm'))¶

update_topographic_params()[source]¶: If the topo changes during the run, change the held params used by run_one_step.

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

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 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.