FlowTopo builds reusable orderings, parallel layerings and spatial partitions from a D8 flow-direction grid.
topological sort from the sourcesordering="topo" | breadth-first from the pitordering="bfs" | depth-first from the pitordering="dfs" |
|---|---|---|
 |  |  |
| a cell is appended once all its donors are done | cells in order of hop count from the pit | one tributary subtree at a time; best cache locality |
Three serial orderings visit every cell once while respecting the flow dependencies.
git clone https://github.com/hellolulujiang/flowtopo.git
cd flowtopo
pip install -e ".[speed]"Python 3.10 or newer. The speed extra enables threaded kernels.
import flowtopo
topo = flowtopo.FlowTopo.from_raster("data/dir_example.tif")
upa = topo.upstream_area(ordering="dfs") # km²
upa_grid = topo.to_2d(upa)The bundled MERIT Hydro basin has 93,432 valid cells. Input requirements.
Three parallel layerings. Layers run in order; the cells of one layer run at the same time.
as-soon-as-possiblelayering="asap" | conflict-free downstreamlayering="cfds" | as-late-as-possiblelayering="alap" |
|---|---|---|
 |  |  |
| every cell in the earliest layer its donors allow | as-soon-as-possible, plus: no two cells in a layer share a receiver | every cell as late as the longest flow path allows; the most evenly filled layers in practice |
Two basins onto two subregions: (a) whole basins, unbalanced; (b) the dominant basin cut along its mainstem, a tributary subtree moved; (c) balanced.
basin-levellevel="basin" | subbasin-levellevel="subbasin" |
|---|---|
| whole basins go to subregions; a dominant basin cannot be balanced | the basins that keep the parts from balancing, usually the dominant one, are opened along their mainstems; their tributary subtrees balance the load, and the held-back mainstem section runs in a separate stage |
Three propagation manners. The structure decides when a cell runs; the manner decides who writes the result.
pullmanner="pull" | atomic pushmanner="atomic_push" | pushmanner="push" |
|---|---|---|
 |  |  |
| each receiver reads its donors and writes only itself; needs the donor table | donors write through atomics; correct, but float sums are not reproducible | donors write directly; deterministic, no locks; safe only under cfds |
FullTopo v1.1 provides saved structures for the 90 MERIT Hydro regions of FullDivide v1.1. Contents and use.
User guide · Methods and provenance · Notebook · Video · Animations · FullHydro tools
Tests · 
Cite this repository with the release used and downloaded products by version. Paper: MERIT-FlowTopo v1.0: a reusable computational foundation for hyperresolution hydrology on the global 90 m drainage network (Jiang et al., submitted to Geoscientific Model Development). Archived paper code.
MERIT Hydro (Yamazaki et al., 2019) supplies the example grid. Foundational conventions follow pyflwdir (D. Eilander, Deltares; MIT); see provenance.
MIT; see LICENSE. The bundled MERIT Hydro excerpt retains its terms, CC BY-NC 4.0 or ODbL 1.0; see DATA_NOTICE.md.