PriorityFloodFlowRouter: Accumulate flow and calculate drainage area using RICHDEM#
priority_flood_flow_router.py: Component to 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
’fill’: Depression-Filling. Depression-filling is often used to fill in all the depressions in a DEM to the level of their lowest outlet or spill-point. See also: https://richdem.readthedocs.io/en/latest/depression_filling.html
’breach’: Complete Breaching. Depression-breaching is used to dig channels from the pit cells of a DEM to the nearest cells (in priority-flood sense) outside of the depression containing the pit. This resolves the depression as all cells in the depression now have a drainage path to the edge of the DEM. See also: https://richdem.readthedocs.io/en/latest/depression_breaching.html
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 toFalse
when only interested in flow directionsaccumulate_flow_hill (bool, optional) – If
True
flow directions and accumulations will be calculated for second FD component (Hill). Set toFalse
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.
- WITH_RICHDEM = True#
- __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
- property node_drainage_area#
Return the drainage area.
- property node_water_discharge#
Return the surface water discharge.
- property surface_values#
Values of the surface over which flow is directed.