# NeuralHydrology: deep learning for rainfall-runoff, configured entirely in YAML

> NeuralHydrology is a PyTorch based Python library for training neural networks on hydrological problems, built around a modular design where datasets, model architectures, losses, optimizers and regularizers are all pluggable and selected through configuration files. The group behind it is the AI for Earth Science team at the Institute for Machine Learning in Linz, Austria.

**neuralhydrology/neuralhydrology** — Python library to train neural networks with a strong focus on hydrological applications.

- Repository: https://github.com/neuralhydrology/neuralhydrology
- Website: https://neuralhydrology.readthedocs.io/
- Stars: 588 · Forks: 279
- Language: Python
- License: BSD-3-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/neuralhydrology-neuralhydrology

## A research library, used in publications, built by a research group

NeuralHydrology is a Python library to train neural networks with a strong focus on hydrological applications. The README is direct about its provenance: the package has been used extensively in research over the last years and was used in various academic publications, and the maintainers are the AI for Earth Science group at the Institute for Machine Learning, Johannes Kepler University, Linz, Austria, who state that they use the code in their day-to-day research and will continue to integrate their new research findings into the public repository. That last sentence is the one that matters for an adopter, because it tells you the code is a by-product of ongoing research rather than a frozen release, so upstream changes arrive when the group publishes something. The licence is BSD-3-Clause, and the package metadata lists Frederik Kratzert, Daniel Klotz and Martin Gauch as the authors.

## Modularity as the organising principle, in every direction

The core idea of the package is described as modularity in all places, to allow easy integration of new datasets, new model architectures or any training-related aspects, and the README gives the specific list of things that should be swappable: loss functions, optimizer and regularization. That is a wider surface than most libraries offer, and it explains the shape of the code. The same modularity also means there is a decision to make before anything runs, because each of those axes has several implementations and the choice is expressed in a configuration file rather than in an import. This is the library for a researcher whose question changes between papers, where the same data pipeline is reused with a different architecture or a different loss, and the value is in being able to change the configuration and rerun rather than in any particular model.

## Configuration files are the interface, not an afterthought

One of the core concepts of the code base are configuration files, which let anyone train neural networks without touching the code itself. That sentence is the design decision in full, and it cuts both ways. On the benefit side, a training run becomes a YAML file plus a command, which is exactly what a paper needs when you have to rerun the same experiment with one value changed, and it is what makes the results reproducible by someone other than the person who wrote the script. On the cost side, the flexibility is a surface area, and the failure mode of a fully declarative system is a configuration error that surfaces minutes into a training run rather than at import time. The example configuration ships in the repository as examples/config.yml.example, and the numbered example directories show the intended progression.

## A worked example sequence, from data prerequisites to finetuning

The examples directory is the best available guide to how the library expects to be used, because the directory names describe a learning path. It starts with 00-Data-Prerequisites, which is where the domain-specific part lives, since a rainfall-runoff network needs discharge gauges, catchment boundaries and meteorological forcing before any model exists. 01-Introduction covers the basics, then 02-Adding-Models, 03-Adding-Datasets and 04-Multi-Timescale show the three modularity axes in action, one directory each. 05-Inspecting-LSTMs is a debugging session, 06-Finetuning is the transfer-learning workflow, and a separate examples/locales directory holds language files. The ordering matters: a newcomer who starts at 02 will spend their time on data format problems instead of on the model, and the library is opinionated enough that skipping the prerequisites is painful.

## PyTorch underneath, with a wide scientific dependency set

The NeuralHydrology package is built on top of the deep learning framework PyTorch, since it has proven to be the most flexible and useful for research purposes, and the README is explicit that the choice is about research flexibility rather than convenience. The dependency list in the packaging metadata tells you what a working environment needs: numpy, pandas, scipy, matplotlib, tensorboard, tqdm and numba for the numerical and plotting side, ruamel.yaml for configuration, xarray with netcdf4 and h5py for the gridded and array data formats that catchment work produces, and torch itself. The dev group adds pytest and pytest-cov, yapf for formatting, bokeh and jupyter for the notebook workflow, and the docs group pulls in Sphinx with the read-the-docs theme, nbsphinx and its link extension. The netCDF and h5py dependencies are a useful signal, because they are the formats of the data rather than of the framework.

## Three console entry points for running and comparing experiments

The package installs three command line programs, and each one answers a different question about a set of experiments. The scripts section of the packaging metadata lists nh-run as the entry point for a single run, nh-schedule-runs for scheduling runs, and nh-results-ensemble for combining results across runs, which is how you get an ensemble out of independently trained models. The version number is read from the package itself rather than being hard-coded, through the dynamic version configuration pointing at the attribute in the package's about module, so the installed version and the source version cannot drift. For a user, the practical consequence is that the library is not only importable, it is usable from a shell, which matters for a grid of configurations on a cluster.

## Citing the JOSS paper, and where to ask questions

The README asks that if you use NeuralHydrology in your research or work, you include a reference to the JOSS paper in any kind of publication, and gives the full BibTeX entry, which is the Journal of Open Source Software article from 2022, volume 7, number 71, page 4050, with a DOI. A repository carries a CITATION.cff file as well, which is the newer machine-readable format for the same thing, and the two together are a reasonable sign that the project takes attribution seriously. Questions and comments go to the GitHub discussions section, bug reports and feature requests go to the issue tracker, and there is an email address for special cases. Documentation is on readthedocs, and there is a research blog at neuralhydrology.github.io for the findings that sit alongside the code. The project is BSD-3-Clause licensed, and the last push was on 2026-10-10, with the most recent release v1.13.0 from 2026-01-14.

## Conclusion

NeuralHydrology fits a hydrology researcher or a student who wants to train a neural network on rainfall and discharge data without writing a training loop, and who wants to swap datasets, architectures or loss functions without touching code. It does not fit a general machine learning project with no hydrology in it, since the data loaders, the evaluation metrics and the example configurations are all domain specific. Before adopting it, read the documentation on readthedocs and work through the numbered example directories, and if you intend to publish, use the JOSS citation the README points to, since that is the reference the project asks for.

## FAQ

### What is NeuralHydrology used for?

It is a Python library to train neural networks with a strong focus on hydrological applications, built on PyTorch. The README says it has been used extensively in research over the last years and in various academic publications.

### Why does NeuralHydrology use configuration files?

Configuration files are one of the core concepts of the code base, and they let anyone train neural networks without touching the code itself. An example configuration ships as examples/config.yml.example, and the numbered example directories walk through adding models, datasets and multi-timescale setups.

### What can I plug into NeuralHydrology?

The core idea is modularity in all places: new datasets, new model architectures, and training-related aspects such as loss functions, optimizer and regularization are all designed to be integrated without modifying the rest of the code.

### How do I cite NeuralHydrology?

The README asks that you include a reference to the JOSS paper, the 2022 Journal of Open Source Software article with DOI 10.21105/joss.04050, and provides the BibTeX entry. The repository also carries a CITATION.cff file, and the licence is BSD-3-Clause.

## Sources

- [License: BSD-3-Clause](https://github.com/neuralhydrology/neuralhydrology/blob/master/LICENSE)
- [neuralhydrology/neuralhydrology on GitHub](https://github.com/neuralhydrology/neuralhydrology)
- [Project website](https://neuralhydrology.readthedocs.io/)
- [README](https://github.com/neuralhydrology/neuralhydrology/blob/master/README.md)
- [Releases](https://github.com/neuralhydrology/neuralhydrology/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/neuralhydrology-neuralhydrology