fastscapelib.FlowGraph

class fastscapelib.FlowGraph

Main class used to compute or follow flow routes on the topographic surface.

__init__(self, grid: Any, operators: List[FlowOperator]) → None

FlowGraph initializer.

Parameters:

• grid (object) – Any Fastscapelib grid object.

• operators (list) – A list of FlowOperator instances that will be applied in chain (in the given order) when computing the graph (flow routing).

Methods

__init__(self, grid, operators)	FlowGraph initializer.
accumulate(*args, **kwargs)	Traverse the flow graph in the top->down direction and accumulate locally produced quantities or fluxes.
apply_kernel(self, flow_kernel, flow_kernel_data)	Apply a given kernel along the flow graph.
basins(self)	Delineate catchments (or basins).
elevation_snapshot(self, name)	Elevation snapshot getter.
graph_snapshot(self, name)	Graph snapshot getter.
impl(self)	Graph implementation getter.
update_routes(self, elevation)	(Re-)Compute flow routing and update the flow graph from an input topgraphic surface.

Attributes

base_levels	Indices of the base level nodes.
elevation_snapshot_keys	Returns the list of elevation snapshot names
graph_snapshot_keys	Returns the list of graph snasphot names
grid_shape	Shape of grid arrays.
mask	Mask where elements with value True correspond to grid nodes that are not included in the flow graph.
operators	Returns the graph's sequence (list) of FlowOperator instances.
single_flow	Returns True if the graph has single direction flow (tree).
size	Total number of graph (grid) nodes.

accumulate(*args, **kwargs) → numpy.ndarray | None

Traverse the flow graph in the top->down direction and accumulate locally produced quantities or fluxes.

The local quantitites or fluxes (i.e., source) may for example correspond to precipitation, surface water runoff, sediment flux, etc.

The accumulated values represent at each node of the graph the integral of the source over the node upslope contributing area.

For example, if the source units are meters (height), the units of the output accumulated values are cubic meters (volume).

Note: the shape of the input and/or output arrays must match the shape of the node arrays of the grid used to build the flow graph.

Overloaded method that supports the following signatures:

1. accumulate(acc: numpy.ndarray, src: numpy.ndarray) -> None

2. accumulate(acc: numpy.ndarray, src: float) -> None

3. accumulate(src: numpy.ndarray) -> numpy.ndarray

4. accumulate(src: float) -> numpy.ndarray

Parameters:

• acc (numpy.ndarray) – Output accumulated values (array values are overwritten). Only for overloads 1/2.

• src (numpy.ndarray or float) – Spatially variable (overloads 1/3) or uniform (overloads 2/4) source term (values must be given per area unit).

Returns:

acc (numpy.ndarray) – Output accumulated values, only for overloads 3/4. Otherwise return None.

apply_kernel(self, flow_kernel: NumbaFlowKernel, flow_kernel_data: NumbaFlowKernelData) → int

Apply a given kernel along the flow graph.

Visit the graph nodes in the direction and order given in the kernel object, call the kernel function and fill the output variables referenced in the kernel data.

Parameters:

• kernel (NumbaFlowKernel) – The flow kernel object to apply along the graph.

• kernel_data (NumbaFlowKernelData) – The object holding or referencing input and output data used by the flow kernel.

property base_levels

Indices of the base level nodes.

basins(self) → numpy.ndarray

Delineate catchments (or basins).

A basin is defined by all adjacent nodes that flow towards the same outlet (or pit) graph node.

Returns:

basins (numpy.ndarray) – Basin ids. The shape of the array is the same than the shape of the arrays of the grid used to build the flow graph.

Notes

Results may be cached so the same computation is not run multiple times.

All masked grid nodes have the same assigned catchment id set by the maximum limit of the integer value range. It is therefore preferable to mask the results prior to, e.g., plotting it.

elevation_snapshot(self, name: str) → numpy.ndarray

Elevation snapshot getter.

The returned array has the same shape than the arrays of the grid used to build the flow graph.

property elevation_snapshot_keys

Returns the list of elevation snapshot names

graph_snapshot(self, name: str) → FlowGraph

Graph snapshot getter.

property graph_snapshot_keys

Returns the list of graph snasphot names

property grid_shape

Shape of grid arrays.

impl(self) → FlowGraphImpl

Graph implementation getter.

Returns:

impl (FlowGraphImpl) – The flow graph implementation instance.

property mask

Mask where elements with value True correspond to grid nodes that are not included in the flow graph.

property operators

Returns the graph’s sequence (list) of FlowOperator instances.

property single_flow

Returns True if the graph has single direction flow (tree).

property size

Total number of graph (grid) nodes.

update_routes(self, elevation: numpy.ndarray) → numpy.ndarray

(Re-)Compute flow routing and update the flow graph from an input topgraphic surface.

This applies in chain the flow operators and takes snapshots (if any).

Parameters:

elevation (numpy.ndarray) – The input topographic surface used to perform flow routing. The shape of the array must match the shape of the arrays of the grid used to build the flow graph.

Returns:

elevation_copy (numpy.ndarray) – A copy of the input elevation, maybe updated (e.g., with filled depressions).