# 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}
}
```
