landlab.utils.flow__distance module#

Functions to calculate flow distance.

calculate_flow__distance(grid, add_to_grid=False, clobber=False)[source]#

Calculate the along flow distance from node to outlet.

This utility calculates the along flow distance based on the results of running flow accumulation on the grid. It will use the connectivity used by the FlowAccumulator (e.g. D4, D8, Dinf).

Parameters:

  • grid (ModelGrid) –

  • add_to_grid (boolean, optional) – Flag to indicate if the stream length field should be added to the grid. Default is False. The field name used is flow__distance.

  • clobber (boolean, optional) – Flag to indicate if adding the field to the grid should not clobber an existing field with the same name. Default is False.

Returns:

flow__distance – The distance that has to be covered from an imaginary flow, located in each node of the grid, to reach the watershed’s outlet.

Return type:

float ndarray

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.components import FlowAccumulator
>>> from landlab.utils.flow__distance import calculate_flow__distance
>>> mg = RasterModelGrid((5, 4), xy_spacing=(1, 1))
>>> mg.at_node["topographic__elevation"] = [
...     [0.0, 0.0, 0.0, 0.0],
...     [0.0, 21.0, 10.0, 0.0],
...     [0.0, 31.0, 20.0, 0.0],
...     [0.0, 32.0, 30.0, 0.0],
...     [0.0, 0.0, 0.0, 0.0],
... ]
>>> mg.set_closed_boundaries_at_grid_edges(
...     bottom_is_closed=True,
...     left_is_closed=True,
...     right_is_closed=True,
...     top_is_closed=True,
... )
>>> fr = FlowAccumulator(mg, flow_director="D8")
>>> fr.run_one_step()
>>> flow__distance = calculate_flow__distance(mg, add_to_grid=True, clobber=True)
>>> mg.at_node["flow__distance"]
array([ 0.        ,  0.        ,  0.        ,  0.        ,
        0.        ,  1.        ,  0.        ,  0.        ,
        0.        ,  1.41421356,  1.        ,  0.        ,
        0.        ,  2.41421356,  2.        ,  0.        ,
        0.        ,  0.        ,  0.        ,  0.        ])

Now, let’s change to D4 the flow_director method, which does not consider diagonal links bewtween nodes.

>>> from landlab import RasterModelGrid
>>> from landlab.components import FlowAccumulator
>>> from landlab.utils.flow__distance import calculate_flow__distance
>>> mg = RasterModelGrid((5, 4), xy_spacing=(1, 1))
>>> mg.at_node["topographic__elevation"] = [
...     [0.0, 0.0, 0.0, 0.0],
...     [0.0, 21.0, 10.0, 0.0],
...     [0.0, 31.0, 20.0, 0.0],
...     [0.0, 32.0, 30.0, 0.0],
...     [0.0, 0.0, 0.0, 0.0],
... ]
>>> mg.set_closed_boundaries_at_grid_edges(
...     bottom_is_closed=True,
...     left_is_closed=True,
...     right_is_closed=True,
...     top_is_closed=True,
... )
>>> fr = FlowAccumulator(mg, flow_director="D4")
>>> fr.run_one_step()
>>> flow__distance = calculate_flow__distance(mg, add_to_grid=True, clobber=True)
>>> mg.at_node["flow__distance"]
array([ 0.,  0.,  0.,  0.,
        0.,  1.,  0.,  0.,
        0.,  2.,  1.,  0.,
        0.,  3.,  2.,  0.,
        0.,  0.,  0.,  0.])

The flow__distance utility can also work on irregular grids. For the example we will use a Hexagonal Model Grid, a special type of Voroni Grid that has regularly spaced hexagonal cells.

>>> from landlab import HexModelGrid
>>> from landlab.components import FlowAccumulator
>>> from landlab.utils.flow__distance import calculate_flow__distance
>>> dx = 1
>>> hmg = HexModelGrid((5, 3), spacing=dx)
>>> _ = hmg.add_field(
...     "topographic__elevation",
...     hmg.node_x + np.round(hmg.node_y),
...     at="node",
... )
>>> hmg.status_at_node[hmg.boundary_nodes] = hmg.BC_NODE_IS_CLOSED
>>> hmg.status_at_node[0] = hmg.BC_NODE_IS_FIXED_VALUE
>>> fr = FlowAccumulator(hmg, flow_director="D4")
>>> fr.run_one_step()
>>> flow__distance = calculate_flow__distance(hmg, add_to_grid=True, clobber=True)
>>> hmg.at_node["flow__distance"]
array([ 0.,  0.,  0.,
        0.,  1.,  2.,  0.,
        0.,  2.,  2.,  3.,  0.,
        0.,  3.,  3.,  0.,
        0.,  0.,  0.])