<p align="center">
<img src="doc/_images/roger-logo.png">
</p>
<p align="center">
<i>Runoff Generation Research - a hydrologic toolbox in Python</i>
</p>
<p align="center">
<a href="http://roger.readthedocs.io/?badge=latest">
<img src="https://readthedocs.org/projects/roger/badge/?version=latest" alt="Documentation status">
</a>
<a href="https://github.com/Hydrology-IFH/roger/actions/workflows/test-all.yml">
<img src="https://github.com/Hydrology-IFH/roger/actions/workflows/test-all.yml/badge.svg" alt="Test status">
</a>
<a href="https://codecov.io/gh/Hydrology-IFH/roger" >
<img src="https://codecov.io/gh/Hydrology-IFH/roger/branch/main/graph/badge.svg?token=KXSVNGDDNH"/>
</a>
<a href="https://zenodo.org/badge/latestdoi/536477819"><img src="https://zenodo.org/badge/536477819.svg" alt="DOI"></a>
</p>
Roger, *Runoff Generation Research*, is a process-based hydrologic 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 hydrologic modelling with a clear focus on flexibility and usability.
Roger supports a NumPy backend for small-scale problems, and a
high-performance [JAX](https://github.com/google/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](https://veros.readthedocs.io/en/latest/).
## Documentation
We strongly recommend to [visit our documentation](https://roger.readthedocs.io/en/latest/).
## Features
<p align="center">
<a href="https://vimeo.com/797828563">
<img src="doc/_images/theta_and_tt.gif?raw=true" alt="25 square meter resolved simulations
of a rectangular soil covered by grass">
</a>
</p>
<p align="center">
(25 square meter resolved simulations
of a rectangular soil covered
by grass, click for better
quality)
</p>
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](https://github.com/Hydrology-IFH/roger/blob/master/roger/examples/plot_scale/svat_tutorial):
After setting up your model, all you need to do is call the model setup:
```bash
# move into the folder containing the model script
python svat.py
```
For more information on using Roger, have a look at [our
documentation](http://roger.readthedocs.io).
## Contributing
Contributions to Roger are always welcome, no matter if you spotted an
inaccuracy in [the documentation](https://roger.readthedocs.io), wrote a
new setup, fixed a bug, or even extended Roger\' core mechanics. There
are 2 ways to contribute:
1. If you want to report a bug or request a missing feature, please
[open an issue](https://github.com/Hydrology-IFH/roger/issues). If you
are reporting a bug, make sure to include all relevant information
for reproducing it (ideally through a *minimal* code sample).
2. 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](https://github.com/Hydrology-IFH/roger/pulls). However,
before you do so, please check [the contribution
guide](http://roger.readthedocs.io/quickstart/get-started.html#enhancing-Roger)
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](https://www.python.org/dev/peps/pep-0008/), use
*meaningful* variable names, and document your code using
[Google-style
docstrings](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
## How to cite
If you use Roger in scientific work, please consider citing [the following publication](...):
```bibtex
@article{
title = {Roger v3.0 – a hydrologic toolbox in {Python}},
volume = {...},
doi = {https://doi.org/10.5194/gmd-xxx},
journal = {Geosci. Model Dev.},
author = {Schwemmle, Robin, and Leistert, Hannes, and Weiler, Markus},
year = {2023},
pages = {...},
}
```
Or have a look at [our documentation](https://roger.readthedocs.io/en/latest/more/publications.html)
for more publications involving Roger.
## TODO
- implement runoff and channel routing (e.g. kinematic wave or hydraulic approach)
- implement distributed model with run-on infiltration
- use coarser spatial and temporal resolution for computation of
groundwater-related processes
- implement baseflow in the groundwater routine. requires surface water depth.
- implement surface runoff generation for gravity-driven infiltration
- implement gravity-driven infiltration and percolation and include it into the transport routine
- implement time-variant sowing and harvesting of crops
## License
This software can be distributed freely under the MIT license. Please read the LICENSE for further information.
© 2022, Robin Schwemmle (<robin.schwemmle@hydrology.uni-freiburg.de>)
Raw data
{
"_id": null,
"home_page": "https://roger.readthedocs.io",
"name": "roger",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "hydrology python parallel numpy multi-core geophysics hydrologic-model gpu jax",
"author": "Robin Schwemmle (University of Freiburg)",
"author_email": "robin.schwemmle@hydrology.uni-freiburg.de",
"download_url": "https://files.pythonhosted.org/packages/fe/f2/9ede2d5b83b0332e19f28251196958a0e4b664ae79b9673d3e3d7808e33c/roger-3.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n<img src=\"doc/_images/roger-logo.png\">\n</p>\n\n<p align=\"center\">\n<i>Runoff Generation Research - a hydrologic toolbox in Python</i>\n</p>\n\n<p align=\"center\">\n <a href=\"http://roger.readthedocs.io/?badge=latest\">\n <img src=\"https://readthedocs.org/projects/roger/badge/?version=latest\" alt=\"Documentation status\">\n </a>\n <a href=\"https://github.com/Hydrology-IFH/roger/actions/workflows/test-all.yml\">\n <img src=\"https://github.com/Hydrology-IFH/roger/actions/workflows/test-all.yml/badge.svg\" alt=\"Test status\">\n </a>\n <a href=\"https://codecov.io/gh/Hydrology-IFH/roger\" > \n <img src=\"https://codecov.io/gh/Hydrology-IFH/roger/branch/main/graph/badge.svg?token=KXSVNGDDNH\"/> \n </a>\n <a href=\"https://zenodo.org/badge/latestdoi/536477819\"><img src=\"https://zenodo.org/badge/536477819.svg\" alt=\"DOI\"></a>\n</p>\n\nRoger, *Runoff Generation Research*, is a process-based hydrologic 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 hydrologic modelling with a clear focus on flexibility and usability.\n\nRoger supports a NumPy backend for small-scale problems, and a\nhigh-performance [JAX](https://github.com/google/jax) backend\nwith CPU and GPU support. Parallel computation is available via MPI and supports\ndistributed execution on any number of nodes/CPU cores.\n\nInspired by [Veros](https://veros.readthedocs.io/en/latest/).\n\n## Documentation\n\nWe strongly recommend to [visit our documentation](https://roger.readthedocs.io/en/latest/).\n\n\n## Features\n\n<p align=\"center\">\n <a href=\"https://vimeo.com/797828563\">\n <img src=\"doc/_images/theta_and_tt.gif?raw=true\" alt=\"25 square meter resolved simulations \nof a rectangular soil covered by grass\">\n </a>\n</p>\n\n<p align=\"center\">\n(25 square meter resolved simulations \nof a rectangular soil covered \nby grass, click for better\nquality)\n</p>\n\nRoger provides\n\n- grid-based **1D models**\n- **offline solute transport** with several **StorAge selection (SAS) functions**\n- solute-specific biogeochemical processes\n- implementations of **capillary-driven infiltration (Green-Ampt)**\n- several **pre-implemented diagnostics** such as averages or collecting values\n at given time interval, variable time aggregation, travel time distributions\n and residence time distributions (written to netCDF4 output)\n- **pre-configured idealized and realistic setups** that are ready to\n run and easy to adapt\n- **accessibility and extensibility** due to high-level programming language Python\n\n\n## Basic usage\n\nTo run Roger, you need to set up a model --- i.e., specify which settings\nand model domain you want to use. This is done by subclassing the\n`RogerSetup` base class in a *setup script* that is written in Python. A good\nplace to start is the\n[SVAT Tutorial](https://github.com/Hydrology-IFH/roger/blob/master/roger/examples/plot_scale/svat_tutorial):\n\n\nAfter setting up your model, all you need to do is call the model setup:\n```bash\n# move into the folder containing the model script\npython svat.py\n```\n\nFor more information on using Roger, have a look at [our\ndocumentation](http://roger.readthedocs.io).\n\n## Contributing\n\nContributions to Roger are always welcome, no matter if you spotted an\ninaccuracy in [the documentation](https://roger.readthedocs.io), wrote a\nnew setup, fixed a bug, or even extended Roger\\' core mechanics. There\nare 2 ways to contribute:\n\n1. If you want to report a bug or request a missing feature, please\n [open an issue](https://github.com/Hydrology-IFH/roger/issues). If you\n are reporting a bug, make sure to include all relevant information\n for reproducing it (ideally through a *minimal* code sample).\n2. If you want to fix the issue yourself, or wrote an extension for\n Roger - great! You are welcome to submit your code for review by\n committing it to a repository and opening a [pull\n request](https://github.com/Hydrology-IFH/roger/pulls). However,\n before you do so, please check [the contribution\n guide](http://roger.readthedocs.io/quickstart/get-started.html#enhancing-Roger)\n for some tips on testing and benchmarking, and to make sure that\n your modifications adhere with our style policies. Most importantly,\n please ensure that you follow the [PEP8\n guidelines](https://www.python.org/dev/peps/pep-0008/), use\n *meaningful* variable names, and document your code using\n [Google-style\n docstrings](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).\n\n## How to cite\n\nIf you use Roger in scientific work, please consider citing [the following publication](...):\n\n```bibtex\n@article{\n\ttitle = {Roger v3.0 \u2013 a hydrologic toolbox in {Python}},\n\tvolume = {...},\n\tdoi = {https://doi.org/10.5194/gmd-xxx},\n\tjournal = {Geosci. Model Dev.},\n\tauthor = {Schwemmle, Robin, and Leistert, Hannes, and Weiler, Markus},\n\tyear = {2023},\n\tpages = {...},\n}\n```\n\nOr have a look at [our documentation](https://roger.readthedocs.io/en/latest/more/publications.html)\nfor more publications involving Roger.\n\n## TODO\n- implement runoff and channel routing (e.g. kinematic wave or hydraulic approach)\n- implement distributed model with run-on infiltration\n- use coarser spatial and temporal resolution for computation of\ngroundwater-related processes\n- implement baseflow in the groundwater routine. requires surface water depth.\n- implement surface runoff generation for gravity-driven infiltration\n- implement gravity-driven infiltration and percolation and include it into the transport routine\n- implement time-variant sowing and harvesting of crops\n\n## License\nThis software can be distributed freely under the MIT license. Please read the LICENSE for further information.\n\u00a9 2022, Robin Schwemmle (<robin.schwemmle@hydrology.uni-freiburg.de>)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Runoff Generation Research - a hydrologic toolbox in Python",
"version": "3.0",
"project_urls": {
"Homepage": "https://roger.readthedocs.io"
},
"split_keywords": [
"hydrology",
"python",
"parallel",
"numpy",
"multi-core",
"geophysics",
"hydrologic-model",
"gpu",
"jax"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fef29ede2d5b83b0332e19f28251196958a0e4b664ae79b9673d3e3d7808e33c",
"md5": "40d9bce4978727e374374220613e14ab",
"sha256": "c80797523a6a6044a91c143e07147cd084e170080a1bd1174a38d1fbd42425fc"
},
"downloads": -1,
"filename": "roger-3.0.tar.gz",
"has_sig": false,
"md5_digest": "40d9bce4978727e374374220613e14ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 388972,
"upload_time": "2023-02-12T14:20:41",
"upload_time_iso_8601": "2023-02-12T14:20:41.470272Z",
"url": "https://files.pythonhosted.org/packages/fe/f2/9ede2d5b83b0332e19f28251196958a0e4b664ae79b9673d3e3d7808e33c/roger-3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-12 14:20:41",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "roger"
}
JSON