Metadata-Version: 2.4
Name: river_route
Version: 2.0.0
Summary: Perform river routing computations on large river networks
Home-page: https://github.com/rileyhales/river-route
Author: Riley Hales PhD
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.12.0
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: dask
Requires-Dist: geopandas
Requires-Dist: netcdf4
Requires-Dist: networkx
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pyyaml
Requires-Dist: scipy
Requires-Dist: shapely
Requires-Dist: tqdm
Requires-Dist: xarray
Provides-Extra: all
Requires-Dist: pytest>=9.0.2; extra == "all"
Requires-Dist: mkdocs<2; extra == "all"
Requires-Dist: mkdocs-material; extra == "all"
Requires-Dist: mkdocstrings; extra == "all"
Requires-Dist: mkdocstrings-python; extra == "all"
Requires-Dist: mkdocs-include-markdown-plugin; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=9.0.2; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs<2; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings; extra == "docs"
Requires-Dist: mkdocstrings-python; extra == "docs"
Requires-Dist: mkdocs-include-markdown-plugin; extra == "docs"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# River Route

[![Documentation Status](https://readthedocs.org/projects/river-route/badge/?version=latest)](https://river-route.hales.app/en/latest/)
[![PyPI version](https://badge.fury.io/py/river-route.svg)](https://pypi.org/project/river-route/)
[![GitHub repo size](https://img.shields.io/github/repo-size/rileyhales/river-route)](https://github.com/rileyhales/river-route)
![License](https://img.shields.io/github/license/rileyhales/river-route)

`river-route` is a Python package for routing runoff and discharge through large river
networks. It uses numba-compiled kernels and sparse matrix operations for efficient
Muskingum-family routing at watershed scale.

## Router Options

| Router           | Use case                                                        |
|------------------|-----------------------------------------------------------------|
| `Muskingum`      | Channel routing only (no lateral runoff input).                 |
| `RapidMuskingum` | Route runoff directly to channels at each timestep.             |
| `UnitMuskingum`  | Transform runoff with a unit hydrograph before channel routing. |

## Installation

```bash
pip install river-route
```

For local development:

```bash
git clone https://github.com/rileyhales/river-route.git
cd river-route
conda env create -f environment.yaml
conda activate rr
python -m pip install -e ".[all]"
```

## Quick Start

```python
import river_route as rr

(
    rr
    .RapidMuskingum("examples/config_rapid_muskingum.yaml")
    .route()
)
```

Configuration can be provided by:

1. A YAML/JSON config file path.
2. Keyword arguments.
3. Both (kwargs override file values).

Core required inputs are:

- `params_file` (network topology and Muskingum parameters)
- One runoff source (`qlateral_files` or `grid_runoff_files` + `grid_weights_file`) for transform routers
- `discharge_dir` (or explicit `discharge_files`)

## CLI

```bash
rr --help
rr RapidMuskingum examples/config_rapid_muskingum.yaml
rr UnitMuskingum examples/config_unit_muskingum.yaml
```

## Documentation

- Hosted docs: https://river-route.hales.app
- Migration guide: [`docs/migrating/v1-to-v2.md`](docs/migrating/v1-to-v2.md)

Build docs locally:

```bash
mkdocs serve
```

## Testing

```bash
pytest tests -v
```

Integration tests use external sample data:

```bash
./tests/download_test_data.sh
pytest tests -v -s
```
