ewatercycle
A Python package for running hydrological models.
The eWaterCycle package makes it easier to use hydrological models without having intimate knowledge about how to install and run the models.
- Uses container for running models in an isolated and portable way with grpc4bmi or remotebmi
- Generates rain and sunshine required for the model using ESMValTool
- Supports observation data from GRDC or USGS
- Exposes simple interface to quickly get up and running
Install
The ewatercycle package needs some geospatial non-python packages to generate forcing data. It is preferred to create a Conda environment to install those dependencies:
curl -o conda-lock.yml https://raw.githubusercontent.com/eWaterCycle/ewatercycle/main/conda-lock.yml
conda install mamba conda-lock -n base -c conda-forge -y
conda-lock install --no-dev -n ewatercycle
conda activate ewatercycle
The ewatercycle package is installed with
pip install ewatercycle
The ewatercycle package ships without any models. Models are packaged in plugins. To install all endorsed plugins use
pip install ewatercycle-hype ewatercycle-lisflood ewatercycle-marrmot ewatercycle-pcrglobwb ewatercycle-wflow ewatercycle-leakybucket
Besides installing software you will need to create a configuration file, download several data sets and get container images. See the system setup chapter for instructions.
Usage
Example using the Marrmot M14 (TOPMODEL) hydrological model on Rhine catchment to generate forcing, run it and produce a hydrograph.
In condensed code:
forcing = ewatercycle.forcing.sources["MarrmotForcing"].generate(...)
model = ewatercycle.models.sources["MarrmotM14"](forcing)
model.setup(...)
model.initialize()
while model.time < model.end_time:
model.update()
value = model.get_value_as_xarray("flux_out_Q")
model.finalize()
ewatercycle.analysis.hydrograph(...)
(Click to see real code)
In real code:
import ewatercycle.analysis
import ewatercycle.forcing
import ewatercycle.models
import ewatercycle.observation.grdc
from ewatercycle.testing import rhine_shape
import shapefile
import xarray as xr
forcing = ewatercycle.forcing.sources["MarrmotForcing"].generate(
dataset="ERA5",
start_time="2010-01-01T00:00:00Z",
end_time="2010-12-31T00:00:00Z",
shape=rhine_shape(),
)
model = ewatercycle.models.sources["MarrmotM14"](version="2020.11", forcing=forcing)
cfg_file, cfg_dir = model.setup(
threshold_flow_generation_evap_change=0.1,
)
model.initialize(cfg_file)
# flux_out_Q unit conversion factor from mm/day to m3/s
sf = shapefile.Reader(rhine_shape())
area = sf.record(0)["SUB_AREA"] * 1e6 # from shapefile in m2
conversion_mmday2m3s = 1 / (1000 * 24 * 60 * 60)
conversion = conversion_mmday2m3s * area
simulated_discharge = []
while model.time < model.end_time:
model.update()
simulated_discharge.append(model.get_value_as_xarray("flux_out_Q"))
observations_ds = ewatercycle.observation.grdc.get_grdc_data(
station_id=6335020, # Rees, Germany
start_time=model.start_time_as_isostr,
end_time=model.end_time_as_isostr,
column="observation",
)
# Combine the simulated discharge with the observations
sim_da = xr.concat(simulated_discharge, dim="time") * conversion
sim_da.name = "simulated"
discharge = xr.merge([sim_da, observations_ds["observation"]]).to_dataframe()
discharge = discharge[["observation", "simulated"]].dropna()
ewatercycle.analysis.hydrograph(discharge, reference="observation")
model.finalize()
More examples can be found in the plugins listed in the documentation.
Contributing
If you want to contribute to the development of ewatercycle package, have a look at the contribution guidelines.
License
Copyright (c) 2018 - 2024, Netherlands eScience Center & Delft University of Technology
Apache Software License 2.0
6 maintainers
Release files for ewatercycle 2.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ewatercycle-2.6.0.tar.gz | 243.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ewatercycle-2.6.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 372.2 kB
Release files / ewatercycle-2.6.0.tar.gz
| Download URL | ewatercycle-2.6.0.tar.gz |
|---|---|
| Size | 243.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c192133267d1546443b72a5307154dfc79bbf45085df7bbe142d4bde464a50b0
|
|
BLAKE2b-256 checksum How to use checksums |
d3352952f8651e6d093be478eab8c318437e90fca2fefa48b145ab57551c2446
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / ewatercycle-2.6.0-py3-none-any.whl
| Download URL | ewatercycle-2.6.0-py3-none-any.whl |
|---|---|
| Size | 128.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
075689ac88977f09fa64d977c7ae03499b68fb84fe9c77be61e70a8da4599251
|
|
BLAKE2b-256 checksum How to use checksums |
405ec455aced084a170e3209d1a53e59873e7e606567d0dac8b732523b67776c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency log
