PriorityFloodFlowRouter: Accumulate flow and calculate drainage area using RICHDEM#

Fill or breach a DEM, accumulate flow and calculate drainage area using the priority flood algorithm.

PriorityFloodFlowRouter is a wrapper of the RichDEM package: https://richdem.readthedocs.io/en/latest/flow_metrics.html

The component merges a filling/breaching algorithm, a flow director as well as a flow accumulator. Moreover, the component supports the definition of two flow accumulator fields associated to the same grid. This prevents the user from updating the filling/breaching algorithms in between calculation of flow accumulator one and two.

@author: benjaminCampforts

class PriorityFloodFlowRouter(*args, **kwds)[source]#

Bases: Component

Component to accumulate flow and calculate drainage area based RICHDEM software package.

See also: https://richdem.readthedocs.io/en/latest/

Note

The perimeter nodes NEVER contribute to the accumulating flux, even if the gradients from them point inwards to the main body of the grid. This is because under Landlab definitions, perimeter nodes lack cells, so cannot accumulate any discharge.

FlowAccumulatorPf stores as ModelGrid fields:

  • ‘drainage_area’: Node array of drainage areas

  • ‘flood_status_code’: Map of flood status (_PIT, _CURRENT_LAKE, _UNFLOODED, or _FLOODED).

  • ‘surface_water__discharge’: Node array of discharges.

  • ‘Distance to receiver’: Distance to receiver

  • ‘water__unit_flux_in’: External volume water per area per time input to each node.

  • ‘flow__upstream_node_order’: Node array containing downstream-to-upstream ordered list of node IDs.

  • ‘flow__receiver_node’: Node array of receivers (nodes that receive flow), or ITS OWN ID if there is no receiver. This array is 2D for RouteToMany methods and has the shape (n-nodes x max number of receivers).

  • ‘flow__receiver_proportions’: Node array of flow proportions. This array is 2D, for RouteToMany methods and has the shape (n-nodes x max number of receivers).

  • ‘topographic__steepest_slope’: Node array of downhill slopes from each receiver. This array is 2D for RouteToMany methods and has the shape (n-nodes x max number of receivers).

  • ‘flow__link_to_receiver_node’: Node array of links carrying flow.

  • ‘flow__receiver_proportion’s: Node array of proportion of flow sent to each receiver.

  • ‘depression_free_elevation’: Depression free land surface topographic elevation, at closed borders, value equals -1.

The following fields are required when an additional hillslope flowrouting scheme is required, can be completed with flow acc and discharge if required:

  • ‘hill_flow__upstream_node_order’: Node array containing downstream-to-upstream ordered list of node IDs

  • ‘hill_flow__receiver_node’: Node array of receivers (node that receives flow from current node)

  • ‘hill_topographic__steepest_slope’: The steepest downhill slope.

  • ‘hill_flow__receiver_proportions’: Node array of proportion of flow sent to each receiver

The primary method of this class is run_one_step.

Parameters:

  • grid (ModelGrid) – A Landlab grid.

  • surface (str or array_like, optional) – The surface to direct flow across. An at-node field name or an array of length n_node.

  • flow_metric (str, optional) – String has to be one of ‘D8’ (O’Callaghan and Mark, 1984), ‘Rho8’ (Fairfield and Leymarie, 1991), ‘Quinn’ (1991), ‘Freeman’ (1991), ‘Holmgren’ (1994), ‘Dinf’ (Tarboton, 1997). For details and comparison, see https://richdem.readthedocs.io/en/latest/flow_metrics.html

  • runoff_rate (str, array_like, or float, optional) – If provided, sets the runoff rate (m / time) and will be assigned to the grid field ‘water__unit_flux_in’. If a spatially and and temporally variable runoff rate is desired, pass this field name and update the field through model run time. If both the field and argument are present at the time of initialization, runoff_rate will overwrite the field. If neither are set, defaults to spatially constant unit input. Both a runoff_rate array and the ‘water__unit_flux_in’ field are permitted to contain negative values, in which case they mimic transmission losses rather than e.g. rain inputs.

  • update_flow_depressions (bool, optional) – Build-in depression handler. Can be through filling or breaching (see below).

  • update_hill_depressions (bool, optional) – Only needed if DEM needs to be filled separately for second (hill flow) flow accumulator. Default behavior is not to execute a separate filling procedure in between the first and the second flow accumulator.

  • depression_handler (str, optional) –

    Must be one of ‘fill or ‘breach’. Depression-Filling or breaching algorithm to process depressions

  • exponent (float, optional) – Some methods require an exponent (see flow_metric) Default {1}

  • epsilon (bool, optional) – If True, an epsilon gradient is imposed to all flat regions. This ensures that there is always a local gradient.

  • accumulate_flow (bool, optional) – If True flow directions and accumulations will be calculated. Set to False when only interested in flow directions

  • accumulate_flow_hill (bool, optional) – If True flow directions and accumulations will be calculated for second FD component (Hill). Set to False when only interested in flow directions.

  • separate_hill_flow (bool, optional) – For some applications (e.g. HyLands) both single and multiple flow direction and accumulation is required. By calculating them in the same component, we can optimize procedures involved with filling and breaching of DEMs

  • update_hill_flow_instantaneous (bool, optional) – Update separate hillslope director and accumulator simultaneously on update. Set if other operations have to be performed in between updating the principle flow properties and the hillslope properties.

  • hill_flow_metric (str, optional) – Must be one ‘D8’ (O’Callaghan and Mark, 1984),’D4’ (O’Callaghan and Mark, 1984), ‘Rho8’ (Fairfield and Leymarie, 1991), ‘Rho4’ (Fairfield and Leymarie, 1991), ‘Quinn’ (1991) {default},’Freeman’ (1991), ‘Holmgren’ (1994), ‘Dinf’ (Tarboton, 1997). For details and comparison, see https://richdem.readthedocs.io/en/latest/flow_metrics.html

  • hill_exponent (float, optional) – Some methods require an exponent (see flow_metric)

  • suppress_out (bool, optional) – Suppress verbose of priority flood algorithm

References

Required Software Citation(s) Specific to this Component

Barnes, R., 2017. Parallel non-divergent flow accumulation for trillion cell digital elevation models on desktops or clusters. Environmental Modelling & Software 92, 202–212. doi: 10.1016/j.envsoft.2017.02.022

Additional References

https://richdem.readthedocs.io/en/latest/

Initialize the FlowAccumulator component.

Saves the grid, tests grid type, tests input types and compatibility for the flow_metric and depression_finder keyword arguments, tests the argument of runoff, and initializes new fields.

__init__(grid, surface='topographic__elevation', flow_metric='D8', runoff_rate=None, update_flow_depressions=True, depression_handler='fill', exponent=1, epsilon=True, accumulate_flow=True, accumulate_flow_hill=False, separate_hill_flow=False, update_hill_depressions=False, update_hill_flow_instantaneous=True, hill_flow_metric='Quinn', hill_exponent=1, suppress_out=True)[source]#

Initialize the FlowAccumulator component.

Saves the grid, tests grid type, tests input types and compatibility for the flow_metric and depression_finder keyword arguments, tests the argument of runoff, and initializes new fields.

calc_flow_dir_acc(hill_flow=False, update_depressions=True)[source]#

Calculate flow direction and accumulation using the richdem package

static load_richdem()[source]#
property node_drainage_area#

Return the drainage area.

property node_water_discharge#

Return the surface water discharge.

remove_depressions(flow_metric='D8')[source]#
run_one_step()[source]#
property surface_values#

Values of the surface over which flow is directed.

update_hill_fdfa(update_depressions=False)[source]#