Skip to main content

A Python package for running and validating a hydrology model

Project description

ewatercycle

image

A Python package for running hydrological models.

Test CI Lint CI Build CI codecov Documentation Status PyPI image image Research Software Directory Badge SQAaaS badge shields.io Open in Dev Containers

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
  • 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.fixtures 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ewatercycle-2.4.0.tar.gz (233.5 kB view details)

Uploaded Source

Built Distribution

ewatercycle-2.4.0-py3-none-any.whl (122.5 kB view details)

Uploaded Python 3

File details

Details for the file ewatercycle-2.4.0.tar.gz.

File metadata

  • Download URL: ewatercycle-2.4.0.tar.gz
  • Upload date:
  • Size: 233.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for ewatercycle-2.4.0.tar.gz
Algorithm Hash digest
SHA256 6cd6323cc00d1c0c33cbb50d5feb558ae360dcb5e8df5aa274f006cde0fe76e7
MD5 d73ce9a1a2c03001328783196a95f3ff
BLAKE2b-256 ccf2cb97157fd52e6e867ea8d99dc1675899f15e51f2f128cc5f050a69df7d8b

See more details on using hashes here.

Provenance

The following attestation bundles were made for ewatercycle-2.4.0.tar.gz:

Publisher: python-publish.yml on eWaterCycle/ewatercycle

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ewatercycle-2.4.0-py3-none-any.whl.

File metadata

  • Download URL: ewatercycle-2.4.0-py3-none-any.whl
  • Upload date:
  • Size: 122.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for ewatercycle-2.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 02c4c74391aa30b479680929d4f8f34a5297334c35e074fba48d80d37e721adf
MD5 e41a1912f31e44d24207723058d87fe7
BLAKE2b-256 4a2030bdde879a5697ee4118cd25406e24059e6a7e5c6c5f5a04b3e1c4e9143a

See more details on using hashes here.

Provenance

The following attestation bundles were made for ewatercycle-2.4.0-py3-none-any.whl:

Publisher: python-publish.yml on eWaterCycle/ewatercycle

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page