Metadata-Version: 2.4
Name: hydrodl2
Version: 1.3.0
Summary: Differentiable Hydrologic Model Library
Project-URL: Homepage, https://mhpi.github.io/benchmarks/
Project-URL: Repository, https://github.com/mhpi/hydrodl2
Project-URL: Documentation, https://github.com/mhpi/hydrodl2/tree/master/docs
Project-URL: Issues, https://github.com/mhpi/hydrodl2/issues
Project-URL: Changelog, https://github.com/mhpi/hydrodl2/blob/master/docs/CHANGELOG.md
Author-email: Leo Lonzarich <lglonzaric@gmail.com>, Yalan Song <songyalan1@gmail.com>, Wencong Yang <yangwconion@gmail.com>, Tadd Bindas <taddbindas@gmail.com>
Maintainer-email: Leo Lonzarich <lglonzaric@gmail.com>
License: Non-Commercial Software License Agreement
        
        By downloading the hydrodl2 software (the “Software”) you agree to
        the following terms of use:
        Copyright (c) 2020, The Pennsylvania State University (“PSU”). All rights reserved.
        
        1. PSU hereby grants to you a perpetual, nonexclusive and worldwide right, privilege and
        license to use, reproduce, modify, display, and create derivative works of Software for all
        non-commercial purposes only. You may not use Software for commercial purposes without
        prior written consent from PSU. Queries regarding commercial licensing should be directed
        to The Office of Technology Management at 814.865.6277 or otminfo@psu.edu.
        2. Neither the name of the copyright holder nor the names of its contributors may be used
        to endorse or promote products derived from this software without specific prior written
        permission.
        3. This software is provided for non-commercial use only.
        4. Redistribution and use in source and binary forms, with or without modification, are
        permitted provided that redistributions must reproduce the above copyright notice, license,
        list of conditions and the following disclaimer in the documentation and/or other materials
        provided with the distribution.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS";
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: deep-learning,differentiable-modeling,hybrid-modeling,hydrology,physics-informed,pytorch,scientific-computing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.9.0
Requires-Dist: numpy
Requires-Dist: platformdirs
Requires-Dist: sourcedefender
Requires-Dist: torch
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: ipywidgets; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# HydroDL2: Differentiable Hydrologic Models

<!-- <img src="docs/images/hydrodl2.png" alt="HydroDL2" width="500" height="500"> -->

[![Python](https://img.shields.io/badge/python-3.9--3.13-blue?labelColor=333333)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/pypi/v/hydrodl2?logo=pypi&logoColor=white&labelColor=333333)](https://pypi.org/project/hydrodl2/)
[![PyTorch](https://img.shields.io/badge/PyTorch-required-EE4C2C?logo=pytorch&logoColor=white&labelColor=333333)](https://pytorch.org/)

[![Build](https://img.shields.io/github/actions/workflow/status/mhpi/hydrodl2/pytest.yaml?branch=master&logo=github&label=tests&labelColor=333333)](https://github.com/mhpi/hydrodl2/actions/workflows/pytest.yaml)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&labelColor=333333)](https://github.com/astral-sh/ruff)
[![License](https://img.shields.io/badge/license-Non--Commercial_(PSU)-yellow?labelColor=333333)](#license)

---

</br>

A library of hydrological models developed on PyTorch and designed alongside [𝛿MG](https://github.com/mhpi/generic_deltamodel) for the creation of end-to-end [differentiable models](https://www.nature.com/articles/s43017-023-00450-9), enabling parameter learning, bias correction, missing process representation, and more.

See [`𝛿MG/examples`](https://github.com/mhpi/generic_deltamodel/tree/master/example/hydrology) using HydroDL2-based HBV models for published differentiable parameter learning (dPL) applications.

</br>

## Installation

```bash
uv pip install hydrodl2
```

For development installs, see [setup](./docs/setup.md).


## Quick Start

```python
import hydrodl2

# List all available models
hydrodl2.available_models()
# {'hbv': ['hbv', 'hbv_1_1p', 'hbv_2', 'hbv_2_hourly', 'hbv_2_mts', 'hbv_adj']}

# Load a model class
Hbv = hydrodl2.load_model('hbv')

# Instantiate and use in a differentiable pipeline
model = Hbv()
```

Models are standard `torch.nn.Module` subclasses and can be composed with neural networks via [&delta;MG](https://github.com/mhpi/generic_deltamodel) for end-to-end differentiable training.

</br>

## Available Models

| Model | Name | Description |
|-------|------|-------------|
| HBV 1.0 | `hbv` | Base differentiable HBV model |
| HBV 1.1p | `hbv_1_1p` | HBV with capillary rise modification |
| HBV 2.0 | `hbv_2` | Multi-scale HBV with elevation-dependent parameters |
| HBV 2.0 Hourly | `hbv_2_hourly` | Sub-daily variant of HBV 2.0 |
| HBV 2.0 MTS | `hbv_2_mts` | Multi-timescale variant of HBV 2.0 |
| HBV Adjoint | `hbv_adj` | Implicit scheme with adjoint-based gradients |

</br>

## Repository Structure

```text
.
├── src/
│   └── hydrodl2/
│       ├── api/                   # Main API
│       │   ├── __init__.py
│       │   └── methods.py         # Methods exposed to end-users
│       ├── core/                  # Methods used internally
│       ├── models/                # Shared models directory
│       │   └── hbv/               # HBV model variants
│       └── modules/               # Augmentations for δMG models
├── docs/
├── tests/
└── pyproject.toml
```

## Citation

This work is maintained by [MHPI](http://water.engr.psu.edu/shen/) and advised by [Dr. Chaopeng Shen](https://water.engr.psu.edu/shen/). If you find it useful, please cite:

> Shen, C., et al. (2023). Differentiable modelling to unify machine learning and physical models for geosciences. *Nature Reviews Earth & Environment*, 4(8), 552--567. https://doi.org/10.1038/s43017-023-00450-9

<details>
<summary>BibTeX</summary>

```bibtex
@article{shen2023differentiable,
  title={Differentiable modelling to unify machine learning and physical models for geosciences},
  author={Shen, Chaopeng and others},
  journal={Nature Reviews Earth \& Environment},
  volume={4},
  number={8},
  pages={552--567},
  year={2023},
  publisher={Nature Publishing Group},
  doi={10.1038/s43017-023-00450-9}
}
```
</details>

<!-- ## License

HydroDL2 is released under a **Non-Commercial Software License Agreement** by The Pennsylvania State University. It is free for non-commercial use. Commercial use requires prior written consent from PSU. See [LICENSE](./LICENSE) for full terms.

For commercial licensing inquiries, contact the Office of Technology Management at 814.865.6277 or otminfo@psu.edu. -->

## Contributing

We welcome contributions! See [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for details.

---

*Please submit an [issue](https://github.com/mhpi/hydrodl2/issues) to report any questions, concerns, or bugs.*
