Metadata-Version: 2.3
Name: hy2dl
Version: 1.0.1
Summary: Python library to create hydrological models for rainfall-runoff prediction using deep learning methods
Author: Eduardo Acuña Espinoza, Manuel Álvarez Chaves
Author-email: Eduardo Acuña Espinoza <eduardo.espinoza@kit.edu>, Manuel Álvarez Chaves <manuel.alvarez-chaves@simtech.uni-stuttgart.de>
License: MIT License
         
         Copyright (c) 2024 Eduardo Acuña Espinoza
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Requires-Dist: numpy>=2.2.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: torch>=2.2.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: xarray[io]>=2025.6.1
Requires-Python: >=3.10
Project-URL: Documentation, https://hy2dl.readthedocs.io/
Project-URL: Repository, https://github.com/eduardoAcunaEspinoza/Hy2DL
Description-Content-Type: text/markdown

# Hy<sup>2</sup>DL: Hybrid Hydrological modeling using Deep Learning methods
![Hy2DL Logo](https://raw.githubusercontent.com/eduardoAcunaEspinoza/Hy2DL/main/docs/source/_static/Hy2DL.png)

<p align="justify">
Hy<sup>2</sup>DL is a python library to create hydrological models for rainfall-runoff prediction using deep learning methods. The repository includes implementations with Large-Sample Hydrology datasets such as CAMELS-GB, CAMELS-US, and CAMELS-DE. Besides data-driven architectures, the repository also supports hybrid hydrological models that combine machine learning with process-based knowledge.

The logic of the codes presented here is based on 'NeuralHydrology --- A Python library for Deep Learning research in hydrology' (https://github.com/neuralhydrology/neuralhydrology.git). For a more modular implementation of deep learning method in hydrological modeling we advice the use of Neural Hydrology.

## Structure of the repository:
The codes presented in the repository are in the form of python scripts. Additionally several experiments are in the form of JupyterNotebooks for easy reproduction and execution. Following is a quick overview of the repository structure:
- **benchmarks**: Comparison of our library against other studies from scientific literature.
- **data**: Folder where the different datasets (e.g CAMELS-GB, CAMELS-US...) should be added. This information should be independently downloaded by the user.
- **docs**: Library documentation
- **examples**: Configuration files to run multiple examples.
- **notebooks**: Jupyter notebooks showing implementation examples, for different cases.
- **results**: Folder where the results generated by the codes will be stored.
- **src/hy2dl**: Code of the library.

## Installation
A release version is available on [PyPI](https://pypi.org/project/hy2dl/) and can be installed using:

`uv`
```
uv add hy2dl
```

or `pip`.
```
pip install hy2dl
```

The `pyproject.toml` file includes the package requirements.

## Documentation:
Detailed documentation for the repository can be found at [Hy2DL.readthedocs.io](https://hy2dl.readthedocs.io/en/latest/index.html). 

## Citation:
If you find **Hy²DL** useful in your research or applications, please cite it as:

```bibtex
@software{hy2dl2025,
  author       = {Eduardo Acuña-Espinoza},
  title        = {Hy²DL: Hybrid Hydrological Modeling using Deep Learning methods},
  year         = {2025},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.XXXXXXX},
  url          = {https://doi.org/10.5281/zenodo.XXXXXXX}
}
```
