FlowTopo

FlowTopo builds reusable orderings, parallel layerings and spatial partitions from a D8 flow-direction grid.

Three serial orderings visit every cell once while respecting the flow dependencies.

Install

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.

Quick start

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.

Structures and propagation

Many threads: which cells together?

Three parallel layerings. Layers run in order; the cells of one layer run at the same time.

Several processors: which cells where?

At a confluence: how does a value reach the receiver?

Three propagation manners. The structure decides when a cell runs; the manner decides who writes the result.

Data products

FullTopo v1.1 provides saved structures for the 90 MERIT Hydro regions of FullDivide v1.1. Contents and use.

Documentation

User guide · Methods and provenance · Notebook · Video · Animations · FullHydro tools

Tests ·

Citing

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.

Acknowledgements

MERIT Hydro (Yamazaki et al., 2019) supplies the example grid. Foundational conventions follow pyflwdir (D. Eilander, Deltares; MIT); see provenance.

Licence

MIT; see LICENSE. The bundled MERIT Hydro excerpt retains its terms, CC BY-NC 4.0 or ODbL 1.0; see DATA_NOTICE.md.