Metadata-Version: 2.1
Name: ewatercycle
Version: 1.0.0
Summary: A Python package for running and validating a hydrology model
Home-page: https://github.com/eWaterCycle/ewatercycle
Author: Stefan Verhoeven
Author-email: s.verhoeven@esciencecenter.nl
License: Apache Software License 2.0
Keywords: ewatercycle,FAIR,BMI,Geoscience
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Typing :: Typed
License-File: LICENSE
License-File: NOTICE
Requires-Dist: basic-modeling-interface
Requires-Dist: cftime
Requires-Dist: esmvaltool
Requires-Dist: grpc4bmi (<0.3,>=0.2.12)
Requires-Dist: hydrostats
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pyoos
Requires-Dist: python-dateutil
Requires-Dist: ruamel.yaml
Requires-Dist: scipy
Requires-Dist: xarray
Provides-Extra: dev
Requires-Dist: deepdiff ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: pytest-mypy ; extra == 'dev'
Requires-Dist: pytest-runner ; extra == 'dev'
Requires-Dist: types-python-dateutil ; extra == 'dev'
Requires-Dist: isort ; extra == 'dev'
Requires-Dist: prospector[with_mypy,with_pyroma] ; extra == 'dev'
Requires-Dist: pycodestyle ; extra == 'dev'
Requires-Dist: yapf ; extra == 'dev'
Requires-Dist: nbsphinx ; extra == 'dev'
Requires-Dist: recommonmark ; extra == 'dev'
Requires-Dist: sphinx ; extra == 'dev'
Requires-Dist: sphinx-rtd-theme ; extra == 'dev'
Requires-Dist: ipython ; extra == 'dev'
Requires-Dist: build ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'

################################################################################
ewatercycle
################################################################################

.. image:: https://github.com/eWaterCycle/ewatercycle/raw/main/docs/examples/logo.png

A Python package for running hydrological models.

.. image:: https://github.com/eWaterCycle/ewatercycle/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/eWaterCycle/ewatercycle/actions/workflows/ci.yml

.. image:: https://sonarcloud.io/api/project_badges/measure?project=eWaterCycle_ewatercycle&metric=alert_status
    :target: https://sonarcloud.io/dashboard?id=eWaterCycle_ewatercycle

.. image:: https://sonarcloud.io/api/project_badges/measure?project=eWaterCycle_ewatercycle&metric=coverage
    :target: https://sonarcloud.io/component_measures?id=eWaterCycle_ewatercycle&metric=coverage

.. image:: https://readthedocs.org/projects/ewatercycle/badge/?version=latest
    :target: https://ewatercycle.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. image:: https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B%20%20%E2%97%8F%20%20%E2%97%8B-orange
    :target: https://fair-software.eu


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 <https://github.com/eWaterCycle/grpc4bmi>`_
* Generates rain and sunshine required for the model using `ESMValTool <https://www.esmvaltool.org/>`_
* Supports observation data from `GRDC or USGS <https://ewatercycle.readthedocs.io/en/latest/observations.html>`_
* Exposes `simple interface <https://ewatercycle.readthedocs.io/en/latest/examples/ewatercycle_api_notebook.html>`_ 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:

.. code-block:: bash

    wget https://raw.githubusercontent.com/eWaterCycle/ewatercycle/main/environment.yml
    conda env create --file environment.yml
    conda activate ewatercycle

The ewatercycle package is installed with

.. code-block:: bash

    pip install git+https://github.com/eWaterCycle/ewatercycle.git#egg=ewatercycle


Besides installing software you will need to create a configuration file, download several data sets and get container images.
See the `system setup chapter <https://ewatercycle.readthedocs.org/en/latest/system_setup.html>`_ for instructions.

Usage
-----

Example using the `Marrmot M14 (TOPMODEL) <https://github.com/wknoben/MARRMoT/blob/master/MARRMoT/Models/Model%20files/m_14_topmodel_7p_2s.m>`_ hydrological model on Merrimack catchment to generate forcing, run it and produce a hydrograph.

.. code-block:: python

    import pandas as pd
    import ewatercycle.analysis
    import ewatercycle.forcing
    import ewatercycle.models
    import ewatercycle.observation.grdc

    forcing = ewatercycle.forcing.generate(
        target_model='marrmot',
        dataset='ERA5',
        start_time='2010-01-01T00:00:00Z',
        end_time='2010-12-31T00:00:00Z',
        shape='Merrimack/Merrimack.shp'
    )

    model = ewatercycle.models.MarrmotM14(version="2020.11", forcing=forcing)

    cfg_file, cfg_dir = model.setup(
        threshold_flow_generation_evap_change=0.1,
        leakage_saturated_zone_flow_coefficient=0.99,
        zero_deficit_base_flow_speed=150.0,
        baseflow_coefficient=0.3,
        gamma_distribution_phi_parameter=1.8
    )

    model.initialize(cfg_file)

    observations_df, station_info = ewatercycle.observation.grdc.get_grdc_data(
        station_id=4147380,
        start_time=model.start_time_as_isostr,
        end_time=model.end_time_as_isostr,
    )
    observations_df = observations_df.rename(columns={'streamflow': 'observation'})

    simulated_discharge = []
    timestamps = []
    while (model.time < model.end_time):
        model.update()
        value = model.get_value('flux_out_Q')[0]
        # flux_out_Q unit conversion factor from mm/day to m3/s
        area = 13016500000.0  # from shapefile in m2
        conversion_mmday2m3s = 1 / (1000 * 24 * 60 * 60)
        simulated_discharge.append(value * area * conversion_mmday2m3s)
        timestamps.append(model.time_as_datetime.date())
    simulated_discharge_df = pd.DataFrame({'simulated': simulated_discharge}, index=pd.to_datetime(timestamps))

    ewatercycle.analysis.hydrograph(simulated_discharge_df.join(observations_df), reference='observation')

    model.finalize()

More examples can be found in the `documentation <https://ewatercycle.readthedocs.io>`_.

Contributing
************

If you want to contribute to the development of ewatercycle package,
have a look at the `contribution guidelines <CONTRIBUTING.rst>`_.

License
*******

Copyright (c) 2018, Netherlands eScience Center & Delft University of Technology

Apache Software License 2.0




