What is DDR?¶

Distributed Differentiable Routing (DDR) is a end-to-end differentiable Muskingum Cunge flow router (src/ddr) + geospatial scaffolding (/engine) for building sparse graphs from geospatial fabrics. This work is brought to you by contributers/developers of the \(\delta\)MC, \(\delta\)MC-Juniata-hydroDL2, \(\delta\)MG and T-Route.

The goal of this project is to provide an open-sourced, easy to follow, routing module that can be applied to a wide variety of geospatial flow networks and input lateral flow datasets.

Why DDR?¶

Traditional river routing models require manual calibration of parameters like Manning's roughness coefficient across thousands of river segments. DDR solves this by using differentiable programming - the routing equations are implemented in a way that allows automatic computation of gradients through the entire network, enabling neural networks to learn optimal parameters from observed streamflow data.

How It Works¶

DDR combines physics-based river routing with machine learning:

Lumped Attributes → Neural Network → Physical Parameters → MC Routing → Runoff
        ↑                                                                 ↓
        └──────────────────── Gradient Backpropagation ───────────────────┘

1. Input: Lateral inflow predictions (Q') from unit catchments
2. Parameter Learning: A neural network predicts Manning's roughness (n) and other parameters from catchment attributes
3. Routing: The Muskingum-Cunge equations route flow downstream through the river network
4. Training: Gradients flow backward through the entire system to optimize the neural network

Supported Geospatial Datasets¶

DDR currently supports two major hydrographic datasets:

Architecture Overview¶

ddr/
├── src/ddr/                    # Core routing library
│   ├── routing/                # Muskingum-Cunge implementation
│   │   ├── mmc.py              # Core routing math
│   │   ├── torch_mc.py         # PyTorch nn.Module wrapper
│   │   └── utils.py            # Sparse solver utilities
│   ├── nn/                     # Neural network modules
│   │   └── kan.py              # Kolmogorov-Arnold Network
│   ├── geodatazoo/             # Dataset classes
│   │   ├── lynker_hydrofabric.py
│   │   └── merit.py
│   ├── io/                     # Data I/O utilities
│   └── validation/             # Metrics and plotting
├── engine/                     # Geospatial data preparation (ddr-engine)
│   └── scripts/                # Matrix building scripts
├── benchmarks/                 # Model benchmarking tools (ddr-benchmarks)
│   └── src/ddr_benchmarks/     # Benchmarking library
└── references/                 # Reference datasets and gage info

Citation¶

If you use DDR in your research, please cite:

@article{bindas2024improving,
  author = {Bindas, Tadd and Tsai, Wen-Ping and Liu, Jiangtao and others},
  title = {Improving River Routing Using a Differentiable Muskingum-Cunge Model and Physics-Informed Machine Learning},
  journal = {Water Resources Research},
  volume = {60},
  number = {1},
  year = {2024},
  doi = {https://doi.org/10.1029/2023WR035337}
}

A newer citation is in the works

Community¶

• GitHub Issues: Report bugs and request features
• Discussions: Ask questions and share ideas
• Contributing: We welcome contributions! See our contributing guide.

License¶

DDR is released under the Apache v2.0 License. See the LICENSE file for details.