pyflwdir.partition.partition_plan#

pyflwdir.partition.partition_plan(flw: Flwdir, level: Literal['basin', 'subbasin'] = 'subbasin', n_parts: int = 4, *, seed: int = 42, refine: bool = True, min_subtree_size: int = 100000, imbalance_target: float = 1.005, upa: np.ndarray | None = None) → PartitionPlan[source]#

Divide a raster into parts, and return how the opened mainstems connect to them.

pyflwdir.FlwdirRaster.partition() calls this, with n_processes as n_parts. Pass the plan as partition_plan to pyflwdir.FlwdirRaster.upstream_area() or pyflwdir.FlwdirRaster.accuflux(), with parallel=True, to accumulate each part in its own process. Making a plan does not make any method run in parallel.

A tributary subtree is never cut, so the heaviest part is at least as heavy as the largest subtree of an opened basin, however large n_parts.

Parameters:

  • flw (FlwdirRaster) – The flow directions to divide.

  • level ({'basin', 'subbasin'}, optional) – "basin" (FlowTopo Method 1) keeps every basin whole. "subbasin" (FlowTopo Method 2), the default, also opens the basins that keep the parts from balancing, along their mainstems.

  • n_parts (int, optional) – Number of parts, by default 4; the accumulation runs one process a part with cells.

  • seed (int, optional) – Seed of the first METIS run, by default 42.

  • refine (bool, optional) – Move boundary nodes between parts after METIS to balance them, by default True.

  • min_subtree_size (int, optional) – At subbasin level, tributary subtrees smaller than this are grouped with a larger neighbour before METIS divides them, by default 100,000 cells as in the continental FlowTopo C workflow; the balance refinement still moves single subtrees. Regardless of this value, at least 8 * n_parts groups are kept, or every subtree if there are fewer.

  • imbalance_target (float, optional) – Largest part load divided by the mean load that the partition aims for, by default 1.005. At subbasin level, further basins open only while it is not reached.

  • upa (ndarray, optional) – Upstream area, one value a cell, finite and positive on the network. It decides between two tributaries with as many cells when a mainstem is traced, as in the FlowTopo C code; without it the one with the smaller cell index is taken.

Returns:

The cells of a part hold its label, from 0 to n_parts - 1; the cells of a mainstem section, accumulated after the parts, hold n_parts. A basin of a single cell takes no part: its cell keeps -1 in parts and adds to no load, as in the FlowTopo C code.

Return type:

PartitionPlan