README.md

June 17, 2026 · View on GitHub

Runoff Generation Research - a process-based hydrological toolbox model in Python

RoGeR, Runoff Generation Research, is a process-based hydrological model that can be applied from plot to catchment scale. RoGeR is written in pure Python, which facilitates model setup and model workflows. We want to enable high-performance hydrological modelling with a clear focus on flexibility and usability.

RoGeR supports a NumPy backend for small-scale problems, and a high-performance JAX backend with CPU and GPU support. Parallel computation is available via MPI and supports distributed execution on any number of nodes/CPU cores.

Inspired by Veros.

Documentation

We strongly recommend to visit our documentation.

Features

(25 square meter resolved simulations of the Eberbaechle catchment, Germany (2019-2022), click for better quality)

RoGeR provides

grid-based 1D models
offline solute transport with several StorAge selection (SAS) functions
solute-specific biogeochemical processes
implementations of capillary-driven infiltration (Green-Ampt)
several pre-implemented diagnostics such as averages or collecting values at given time interval, variable time aggregation, travel time distributions and residence time distributions (written to netCDF4 output)
pre-configured idealized and realistic setups that are ready to run and easy to adapt
accessibility and extensibility due to high-level programming language Python

Basic usage

To run RoGeR, you need to set up a model --- i.e., specify which settings and model domain you want to use. This is done by subclassing the RogerSetup base class in a setup script that is written in Python. A good place to start is the SVAT Tutorial:

After setting up your model, all you need to do is call the model setup:

# move into the folder containing the model script
python svat.py

For more information on using RoGeR, have a look at our documentation.

Contributing

Contributions to RoGeR are always welcome, no matter if you spotted an inaccuracy in the documentation, wrote a new setup, fixed a bug, or even extended RoGeR' core mechanics. There are 2 ways to contribute:

If you want to report a bug or request a missing feature, please open an issue. If you are reporting a bug, make sure to include all relevant information for reproducing it (ideally through a minimal code sample).
If you want to fix the issue yourself, or wrote an extension for Roger - great! You are welcome to submit your code for review by committing it to a repository and opening a pull request. However, before you do so, please check the contribution guide for some tips on testing and benchmarking, and to make sure that your modifications adhere with our style policies. Most importantly, please ensure that you follow the PEP8 guidelines, use meaningful variable names, and document your code using Google-style docstrings.

How to cite

If you use Roger in scientific work, please consider citing the following publication:

@article{
	title = {RoGeR v.3.0.5 - a process-based hydrological toolbox model in Python},
	volume = {17},
	doi = {https://doi.org/10.5194/gmd-17-5249-2024},
	journal = {Geosci. Model Dev.},
	author = {Schwemmle, Robin, and Leistert, Hannes, and Weiler, Markus},
	year = {2024},
	pages = {5249-5262},
}

Or have a look at our documentation for more publications involving Roger.

TODO

implement runoff and channel routing (e.g. kinematic wave or hydraulic approach; roger/core/surface_runoff.py and roger/core/subsurface_runoff.py)
implement distributed model with run-on infiltration
complete the surface runoff generation for gravity-driven infiltration (roger/core/film_flow.py)
implement gravity-driven infiltration and percolation and include it into the transport routine (roger/core/film_flow.py)
implement a routing for solute transport
implement a GPU memory profiling to optimise GPU computing
write more and better unit tests

Where to start future developments

Add your new routine to roger/core/xxx.py and include it in roger/roger.py. If you introduce new variables, you have to add them to roger/variables.py. If you build a new model structure, you have to add it to roger/models/xxx

What would I do differently the next time?

better variable names (e.g. use perc_ss for percolation of subsurface runoff)
move percolation from subsurface runoff into a separate module e.g. roger/core/percolation.py
use more vertical layers of state variables (e.g. soil water content). Currently, only two hard coded soil layers exist *_rz and *_ss.
enable flexible usage of numerical solvers rather than calculate the processes in a given sequence
release versions with a higher frequency and better release notes

Contact

I have left academia to find a permanent position outside of academia. I will still fix minor bugs, if time is available. I have tried my best to document everything as good as possible and for sure you will encounter some bugs or incomplete documentation. My advice is that for advanced models a single person is not sufficient and I suggest the four eye principle. Many conceptual and technical issues can be avoided by building a development team. For major requests or questions please contact Markus Weiler or you can choose another implementation of RoGeR.