landlab.components.priority_flood_flow_router.priority_flood_flow_router

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

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

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.

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

calc_flow_dir_acc(hill_flow=False, update_depressions=True)

Calculate flow direction and accumulation using the richdem package

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 = (('depression_free_elevation', 'Filled land surface topographic elevation, at closed borders, value equals -1!'), ('drainage_area', "Upstream accumulated surface area contributing to the node's discharge"), ('flood_status_code', 'Map of flood status (_PIT, _CURRENT_LAKE, _UNFLOODED, or _FLOODED).'), ('flow__link_to_receiver_node', 'ID of link downstream of each node, which carries the discharge'), ('flow__receiver_node', 'Node array of receivers (node that receives flow from current node)'), ('flow__receiver_proportions', 'Node array of proportion of flow sent to each receiver.'), ('flow__upstream_node_order', 'Node array containing downstream-to-upstream ordered list of node IDs'), ('hill_drainage_area', 'Node array of proportion of flow sent to each receiver.'), ('hill_flow__receiver_node', 'Node array of receivers (node that receives flow from current node)'), ('hill_flow__receiver_proportions', 'Node array of proportion of flow sent to each receiver.'), ('hill_flow__upstream_node_order', 'Node array containing downstream-to-upstream ordered list of node IDs'), ('hill_surface_water__discharge', 'Node array of proportion of flow sent to each receiver.'), ('hill_topographic__steepest_slope', 'The steepest *downhill* slope'), ('squared_length_adjacent', 'Length to adjacent nodes, squared (calcualted in advance to save time during calculation'), ('surface_water__discharge', 'Volumetric discharge of surface water'), ('topographic__elevation', 'Land surface topographic elevation'), ('topographic__steepest_slope', 'The steepest *downhill* slope'), ('water__unit_flux_in', 'External volume water per area per time input to each node (e.g., rainfall rate)'))

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 = ()

static load_richdem()

name = 'PriorityFloodFlowRouter'

property node_drainage_area

Return the drainage area.

property node_water_discharge

Return the surface water discharge.

optional_var_names = ('hill_drainage_area', 'hill_flow__receiver_node', 'hill_flow__receiver_proportions', 'hill_flow__upstream_node_order', 'hill_surface_water__discharge', 'hill_topographic__steepest_slope', 'topographic__elevation', 'water__unit_flux_in')

output_var_names = ('depression_free_elevation', 'drainage_area', 'flood_status_code', 'flow__link_to_receiver_node', 'flow__receiver_node', 'flow__receiver_proportions', 'flow__upstream_node_order', 'squared_length_adjacent', 'surface_water__discharge', 'topographic__steepest_slope')

remove_depressions(flow_metric='D8')

run_one_step()

property shape

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

property surface_values

Values of the surface over which flow is directed.

unit_agnostic = True

units = (('depression_free_elevation', 'm'), ('drainage_area', 'm**2'), ('flood_status_code', '-'), ('flow__link_to_receiver_node', '-'), ('flow__receiver_node', '-'), ('flow__receiver_proportions', '-'), ('flow__upstream_node_order', '-'), ('hill_drainage_area', '-'), ('hill_flow__receiver_node', '-'), ('hill_flow__receiver_proportions', '-'), ('hill_flow__upstream_node_order', '-'), ('hill_surface_water__discharge', '-'), ('hill_topographic__steepest_slope', '-'), ('squared_length_adjacent', '-'), ('surface_water__discharge', 'm**3/s'), ('topographic__elevation', 'm'), ('topographic__steepest_slope', '-'), ('water__unit_flux_in', 'm/s'))

update_hill_fdfa(update_depressions=False)

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 = (('depression_free_elevation', 'node'), ('drainage_area', 'node'), ('flood_status_code', 'node'), ('flow__link_to_receiver_node', 'node'), ('flow__receiver_node', 'node'), ('flow__receiver_proportions', 'node'), ('flow__upstream_node_order', 'node'), ('hill_drainage_area', 'node'), ('hill_flow__receiver_node', 'node'), ('hill_flow__receiver_proportions', 'node'), ('hill_flow__upstream_node_order', 'node'), ('hill_surface_water__discharge', 'node'), ('hill_topographic__steepest_slope', 'node'), ('squared_length_adjacent', 'node'), ('surface_water__discharge', 'node'), ('topographic__elevation', 'node'), ('topographic__steepest_slope', 'node'), ('water__unit_flux_in', '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