Class PITFill¶
- class flow.pitfilling.PITFill(*args, **kwargs)[source]¶
Depression filling is an important preconditioning step to many landscape evolution models.
This class implements a linearly-scaling parallel priority-flood depression-filling algorithm based on Barnes (2016) algorithm.
Note
Unlike previous algorithms, Barnes (2016) approach guarantees a fixed number of memory access and communication events per processors. As mentionned in his paper based on comparison testing, it runs generally faster while using fewer resources than previous methods.
The approach proposed here is more general than the one in the initial paper. First, it handles both regular and irregular meshes, allowing for complex distributed meshes to be used as long as a clear definition of inter-mesh connectivities is available. Secondly, to prevent iteration over unnecessary vertices (such as marine regions), it is possible to define a minimal elevation (i.e. sea-level position) above which the algorithm is performed. Finally, it creates directions over flat regions allowing for downstream flows in cases where the entire volume of a depression is filled.
For inter-mesh connections and message passing, the approach relies on PETSc DMPlex functions.
The main functions return the following parameters:
the elevation of the filled surface,
the information for each depression (e.g., a unique global ID, its spillover local points and related processor),
the description of each depression (total volume and maximum filled depth).
Initialise
__init__(*args, **kwargs)The initialisation of PITFill class consists in the declaration of PETSc vectors, matrices and each partition internals edge vertices.
Public Methods
fillElevation([sed])This functions is the main entry point to perform pit filling.
Private Methods
_buildPitDataframe(label1, label2)Definition of a Pandas data frame used to find a unique pit ID between processors.
This function finds routes to spillover points on filled depressions to ensure downstream distribution if they are overfilled.
_fillFromEdges(mgraph)Combine local meshes by joining their edges based on local spillover graphs.
_getPitParams(hl, nbpits)Define depression global parameters:
_offsetGlobal(lgth)Computes the offset between processors to ensure a unique number for considered indices.
_performFilling(hl, level, sed)This functions implements the linearly-scaling parallel priority-flood depression-filling algorithm from Barnes (2016) but adapted to unstructured meshes.
_pitInformation(hl, level[, sed])This function extracts depression informations available to all processors.
_sortingPits(df)Sorts depressions number before combining them to ensure no depression index is changed in an unsorted way.
_transferIDs(pitIDs)This function transfers local depression IDs along local borders and combines them with a unique identifier.
Public functions¶
Private functions¶
- PITFill._buildPitDataframe(label1, label2)[source]¶
Definition of a Pandas data frame used to find a unique pit ID between processors.
- Parameters
label1 – depression ID in a given processors
label2 – same depression ID in a neighbouring mesh
- Returns
df (sorted dataframe of pit ID between processors)
- PITFill._dirFlats()[source]¶
This function finds routes to spillover points on filled depressions to ensure downstream distribution if they are overfilled.
- PITFill._fillFromEdges(mgraph)[source]¶
Combine local meshes by joining their edges based on local spillover graphs.
- Parameters
mgraph – numpy array containing local mesh edges information
ggraph – numpy array containing filled elevation values based on other processors values
- PITFill._getPitParams(hl, nbpits)[source]¶
Define depression global parameters:
volume of each depression
maximum filled depth
- Parameters
hl – numpy array of unfilled surface elevation
nbpits – number of depression in the global mesh
- PITFill._offsetGlobal(lgth)[source]¶
Computes the offset between processors to ensure a unique number for considered indices.
- Parameters
lgth – local length of the data to distribute
- Returns
cumulative sum and sum of the labels to add to each processor
- PITFill._performFilling(hl, level, sed)[source]¶
This functions implements the linearly-scaling parallel priority-flood depression-filling algorithm from Barnes (2016) but adapted to unstructured meshes.
- Parameters
hl – local elevation.
level – minimal elevation above which the algorithm is performed.
sed – boolean specifying if the pits are filled with water or sediments.
- PITFill._pitInformation(hl, level, sed=False)[source]¶
This function extracts depression informations available to all processors. It stores the following things:
the information for each depression (e.g., a unique global ID, its spillover local points and related processor),
the description of each depression (total volume and maximum filled depth).
- Parameters
hl – local elevation.
sed – boolean specifying if the pits are filled with water or sediments.