River networks are crucial in hydrologic and Earth system models. + Accurately representing river networks in hydrologic models requires + considering the model’s spatial resolution and computational mesh. + However, current river network representation methods often have + several limitations: (1) vector-based; (2) they perform poorly at + coarse resolution (3) they do not support unstructured meshes. To + overcome these limitations, we developed PyFlowline, a Python package + that generates mesh-independent river networks. With PyFlowline, + hydrologic modelers can generate conceptual river networks at various + spatial resolutions for both structured and unstructured computational + meshes. The generated river network datasets can be used by hydrologic + models across scales.
+For hydrologic modelers, river networks are a key input for
+ hydrologic models. While some hydrologic models accept vector-based
+ river networks
+ (
Structured mesh-based methods use fixed cartesian or geographic
+ cell sizes, which have several limitations: (1) they cannot resolve
+ fine-scale river networks at coarse cell resolutions (>1km), and
+ (2) they cannot be seamlessly coupled with other unstructured
+ mesh-based hydrologic models such as oceanic models
+ (
Although unstructured meshes offer these flexibilities, additional + efforts are required to generate conceptual river networks that + capture real-world river networks across different spatial scales.
+A mesh-independent river network representation method that + preserves topological relationships across scales could address this + limitation. PyFlowline is a Python package that provides a framework + for generating river networks for hydrologic models, meeting the + identified need. Using an object-oriented programming approach, + PyFlowline represents river network elements and mesh cell + relationships. It relies on open-source Python libraries like GDAL and + Cython for data input/output and spatial data operations.
+The computational geometry algorithms used in PyFlowline are
+ designed and implemented using a unified spherical framework, making
+ it suitable for regional and global-scale simulations. PyFlowline uses
+ topological relationships to capture the river networks so they are
+ preserved even at coarse spatial resolutions. Moreover, PyFlowline is
+ mesh-independent, supporting both structured and unstructured meshes.
+ It can quickly adopt other mesh types, such as triangulated irregular
+ networks (TIN) or discrete global grid systems (DGGs)
+ (
PyFlowline uses Python’s object-oriented programming (OOP) + architecture to describe river networks using three essential + elements: segments, reaches, and confluences. When applicable, river + networks are processed as objects throughout the package.
+The data model. A vertex class object represents a point
+ on the Earth surface. It has three coordinates. An edge class object
+ represents a directed line between two points. Besides, it has a
+ length attribute. A flowline class object represents a list of
+ connected lines.
+
PyFlowline provides several key features, including
+-
+
Support for both structured and unstructured meshes, with JSON + as the default file I/O format. For geospatial datasets such as + vector river networks, GEOJSON is used.
+Regional and global-scale processing capabilities through the + use of fast Cython- and (global-only) AABB tree-based + algorithms.
+Built-in visualization functions (experimental) based on the
+ Python Matplotlib package
+ (
Existing river network representation methods often fall into three + categories, each with associated strengths and weaknesses:
+-
+
Vector-based. Hydrologic models that use this method can
+ represent fine-scale river networks, but cannot couple river and
+ land without one-to-one mapping between river segments and land
+ model cells
+ (
High-resolution DEM-based. Flow networks derived from
+ structured rectangle-grid DEMs are widely available, but resolving
+ fine-scale river networks requires grids with very high spatial
+ resolution (e.g., 30m x 30m or finer)
+ (
Upscaling-based methods address the scale mismatch between
+ coarse-resolution grids and fine-scale river networks, but only
+ support structured geographic grids (e.g., 0.5 degree x 0.5
+ degree) at coarse resolutions
+ (
PyFlowline is the only modeling software that provides these unique + features:
+-
+
It can generate river networks on unstructured meshes;
+It uses topological relationships to capture river networks + precisely;
+It can be applied at both high and coarse resolutions;
+It can provide global coverage, including Greenland and the + Antarctic.
+Model documentation is hosted at + https://pyflowline.readthedocs.io/en/latest/, including a case study + for the Susquehanna River Basin in the Mid-Atlantic region of the + United States.
+The model described in this repository was supported by the + following:
+-
+
the Earth System Model Development and Regional and Global + Model Analysis program areas of the U.S. Department of Energy, + Office of Science, Biological and Environmental Research program + as part of the multi-program, collaborative Integrated Coastal + Modeling (ICoM) project.
+the Earth System Model Development and Regional and Global + Model Analysis program areas of the U.S. Department of Energy, + Office of Science, Biological and Environmental Research program + as part of the multi-program, collaborative Interdisciplinary + Research for Arctic Coastal Environments (InteRFACE) project.
+the Next Generation Ecosystem Experiments-Tropics project, + funded by the U.S. Department of Energy, Office of Science, Office + of Biological and Environmental Research at Pacific Northwest + National Laboratory.
+A portion of this research was performed using PNNL Research + Computing at Pacific Northwest National Laboratory.
+PNNL is operated for DOE by Battelle Memorial Institute under + contract DE-AC05-76RL01830.
+