landlab.components.river_flow_dynamics.river_flow_dynamics

Simulate surface fluid flow based on Casulli and Cheng (1992).

This component implements a semi-implicit, semi-Lagrangian finite-volume approximation of the depth-averaged shallow water equations originally proposed by Casulli and Cheng in 1992, and subsequent related work.

Written by Sebastian Bernal and Angel Monsalve.

Examples

This example demonstrates basic usage of the RiverFlowDynamics component to simulate a simple channel flow:

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> from landlab.components import RiverFlowDynamics

Create a small grid for demonstration purposes:

>>> grid = RasterModelGrid((8, 6), xy_spacing=0.1)

Set up a sloped channel with elevated sides (slope of 0.01).

>>> z = grid.add_zeros("topographic__elevation", at="node")
>>> z += 0.005 - 0.01 * grid.x_of_node
>>> z[grid.y_of_node > 0.5] = 1.0
>>> z[grid.y_of_node < 0.2] = 1.0

Instantiating the Component. To check the names of the required inputs, use the ‘input_var_names’ class property.

>>> RiverFlowDynamics.input_var_names
('surface_water__depth',
 'surface_water__elevation',
 'surface_water__velocity',
 'topographic__elevation')

Initialize required fields:

>>> h = grid.add_zeros("surface_water__depth", at="node")
>>> vel = grid.add_zeros("surface_water__velocity", at="link")
>>> wse = grid.add_zeros("surface_water__elevation", at="node")
>>> wse += h + z

Set up inlet boundary conditions (left side of channel): Water flows from left to right at a depth of 0.5 meters with a velocity of 0.45 m/s.

>>> fixed_entry_nodes = np.arange(12, 36, 6)
>>> fixed_entry_links = grid.links_at_node[fixed_entry_nodes][:, 0]
>>> entry_nodes_h_values = np.full(4, 0.5)
>>> entry_links_vel_values = np.full(4, 0.45)

Instantiate ‘RiverFlowDynamics’

>>> rfd = RiverFlowDynamics(
...     grid,
...     dt=0.1,
...     mannings_n=0.012,
...     fixed_entry_nodes=fixed_entry_nodes,
...     fixed_entry_links=fixed_entry_links,
...     entry_nodes_h_values=entry_nodes_h_values,
...     entry_links_vel_values=entry_links_vel_values,
... )

Run the simulation for 100 timesteps (equivalent to 10 seconds).

>>> n_timesteps = 100
>>> for timestep in range(n_timesteps):
...     rfd.run_one_step()
...

Examine the flow depth at the center of the channel after 10 seconds.

>>> flow_depth = np.reshape(grid["node"]["surface_water__depth"], (8, 6))[3, :]
>>> np.round(flow_depth, 3)
array([0.5  , 0.5  , 0.5  , 0.501, 0.502, 0.502])

And the velocity at links along the center of the channel.

>>> linksAtCenter = grid.links_at_node[np.array(np.arange(24, 30))][:-1, 0]
>>> flow_velocity = grid["link"]["surface_water__velocity"][linksAtCenter]
>>> np.round(flow_velocity, 3)
array([0.45 , 0.457, 0.455, 0.452, 0.453])
class RiverFlowDynamics[source]

Bases: Component

Simulate surface fluid flow based on Casulli and Cheng (1992).

This Landlab component simulates surface fluid flow using the approximations of the 2D shallow water equations developed by Casulli and Cheng in 1992. It calculates water depth and velocity across the raster grid, given a specific input discharge.

References

Required Software Citation(s) Specific to this Component

None Listed

Additional References

Casulli, V., Cheng, R.T. (1992). “Semi-implicit finite difference methods for three-dimensional shallow water flow”. International Journal for Numerical Methods in Fluids. 15: 629-648. https://doi.org/10.1002/fld.1650150602

Simulate the vertical-averaged surface fluid flow

Simulate vertical-averaged surface fluid flow using the Casulli and Cheng (1992) approximations of the 2D shallow water equations. This Landlab component calculates water depth and velocity across the raster grid based on a given input discharge.

Parameters:

  • grid (RasterModelGrid) – A grid.

  • dt (float, optional) – Time step in seconds. If not provided, it is calculated from the CFL condition.

  • eddy_viscosity (float, optional) – Eddy viscosity coefficient. Default = 1e-4 \(m^2 / s\)

  • mannings_n (float or array_like, optional) – Manning’s roughness coefficient. Default = 0.012 \(s / m^1/3\)

  • threshold_depth (float, optional) – Threshold at which a cell is considered wet. Default = 0.01 m

  • theta (float, optional) – Degree of ‘implicitness’ of the solution, ranging between 0.5 and 1.0. Default: 0.5. When set to 0.5, the approximation is centered in time; when set to 1.0, it is fully implicit.

  • fixed_entry_nodes (array_like or None, optional) – Node IDs where flow enters the domain (Dirichlet boundary condition). If not provided, existing water in the domain is not renewed.

  • fixed_entry_links (array_like or None, optional) – Link IDs where flow enters the domain (Dirichlet boundary condition). If not provided, existing water in the domain is not renewed.

  • entry_nodes_h_values (array_like, optional) – Water depth values at nodes where flow enters the domain (Dirichlet boundary condition). If not provided, existing water in the domain is not renewed.

  • entry_links_vel_values (array_like, optional) – Water velocity values at links where flow enters the domain (Dirichlet boundary condition). If not provided, existing water in the domain is not renewed.

  • pcg_tolerance (float, optional) – Tolerance for convergence in the Preconditioned Conjugate Gradient method. Default: 1e-05.

  • pcg_max_iterations (integer, optional) – Maximum number of iterations for the Preconditioned Conjugate Gradient method. Iteration stops after maxiter steps, even if the specified tolerance is not achieved. Default: None.

  • surface_water__elevation_at_N_1 (array_like of float, optional) – Water surface elevation at nodes at time N-1 [m].

  • surface_water__elevation_at_N_2 (array_like of float, optional) – Water surface elevation at nodes at time N-2 [m].

  • surface_water__velocity_at_N_1 (array_like of float, optional) – Speed of water flow at links above the surface at time N-1 [m/s].

__init__(grid, dt=0.01, eddy_viscosity=0.0001, mannings_n=0.012, threshold_depth=0.01, theta=0.5, fixed_entry_nodes=None, fixed_entry_links=None, entry_nodes_h_values=None, entry_links_vel_values=None, pcg_tolerance=1e-05, pcg_max_iterations=None, surface_water__elevation_at_N_1=0.0, surface_water__elevation_at_N_2=0.0, surface_water__velocity_at_N_1=0.0)[source]

Simulate the vertical-averaged surface fluid flow

Simulate vertical-averaged surface fluid flow using the Casulli and Cheng (1992) approximations of the 2D shallow water equations. This Landlab component calculates water depth and velocity across the raster grid based on a given input discharge.

Parameters:

  • grid (RasterModelGrid) – A grid.

  • dt (float, optional) – Time step in seconds. If not provided, it is calculated from the CFL condition.

  • eddy_viscosity (float, optional) – Eddy viscosity coefficient. Default = 1e-4 \(m^2 / s\)

  • mannings_n (float or array_like, optional) – Manning’s roughness coefficient. Default = 0.012 \(s / m^1/3\)

  • threshold_depth (float, optional) – Threshold at which a cell is considered wet. Default = 0.01 m

  • theta (float, optional) – Degree of ‘implicitness’ of the solution, ranging between 0.5 and 1.0. Default: 0.5. When set to 0.5, the approximation is centered in time; when set to 1.0, it is fully implicit.

  • fixed_entry_nodes (array_like or None, optional) – Node IDs where flow enters the domain (Dirichlet boundary condition). If not provided, existing water in the domain is not renewed.

  • fixed_entry_links (array_like or None, optional) – Link IDs where flow enters the domain (Dirichlet boundary condition). If not provided, existing water in the domain is not renewed.

  • entry_nodes_h_values (array_like, optional) – Water depth values at nodes where flow enters the domain (Dirichlet boundary condition). If not provided, existing water in the domain is not renewed.

  • entry_links_vel_values (array_like, optional) – Water velocity values at links where flow enters the domain (Dirichlet boundary condition). If not provided, existing water in the domain is not renewed.

  • pcg_tolerance (float, optional) – Tolerance for convergence in the Preconditioned Conjugate Gradient method. Default: 1e-05.

  • pcg_max_iterations (integer, optional) – Maximum number of iterations for the Preconditioned Conjugate Gradient method. Iteration stops after maxiter steps, even if the specified tolerance is not achieved. Default: None.

  • surface_water__elevation_at_N_1 (array_like of float, optional) – Water surface elevation at nodes at time N-1 [m].

  • surface_water__elevation_at_N_2 (array_like of float, optional) – Water surface elevation at nodes at time N-2 [m].

  • surface_water__velocity_at_N_1 (array_like of float, optional) – Speed of water flow at links above the surface at time N-1 [m/s].

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__elevation', 'Water surface elevation at time N'), ('surface_water__velocity', 'Speed of water flow above the surface'), ('topographic__elevation', 'Land surface topographic elevation'))

Get adjacent links to the link.

This function finds the links at right, above, left and below the given link. Similar purpose to the “adjacent_nodes_at_node” function. Return the adjacent links in as many rows as given links. Link IDs are returned as columns in clock-wise order starting from East (E, N, W, S).

Link nearest a point.

Find the index to the link nearest the given x, y coordinates. Returns the indices of the links nearest the given coordinates.

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', 'surface_water__elevation', 'surface_water__velocity', 'topographic__elevation')
name = 'RiverFlowDynamics'
optional_var_names = ()
output_var_names = ('surface_water__depth', 'surface_water__elevation', 'surface_water__velocity')
path_line_tracing()[source]

“ Path line tracing algorithm.

This function implements the semi-analytical path line tracing method of Pollock (1988).

The semi-analytical path line tracing method was developed for particle tracking in ground water flow models. The assumption that each directional velocity component varies linearly in its coordinate directions within each computational volume or cell underlies the method. Linear variation allows the derivation of an analytical expression for the path line of a particle across a volume.

Given an initial point located at each volume faces of the domain, particle trayectories are traced backwards on time. Then, this function returns the departure point of the particle at the beginning of the time step.

run_one_step()[source]

Calculate water depth and water velocity for a time period dt.

property shape

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

unit_agnostic = False
units = (('surface_water__depth', 'm'), ('surface_water__elevation', 'm'), ('surface_water__velocity', 'm/s'), ('topographic__elevation', '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__elevation', 'node'), ('surface_water__velocity', 'link'), ('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